How Sponge knowledge works

The graph-native authoring, citation, Inquiry, proposal-review, edition, and public-route contracts described here are active in Production at spongeresearch.com. Public /k resolution is live. Signed-in review and publishing journeys, along with the editor's native browser and device matrix, remain under broader production verification.

Implemented

Versioned rich documents, loss-aware Markdown, graph citations, the ontology kernel, Inquiries, proposal review, editions, and release-gated /k pages.

Private first

Documents, Inquiries, graph records, agent proposals, and accepted research effects remain private unless a separate public boundary is satisfied.

Production

Knowledge records, reviewed editions, and release-gated read-only /k pages are active on spongeresearch.com.

No legacy model

Source, person, organization, account, place, event, and future domains are vocabulary concepts and composable Shapes, not privileged root records.

The Production v1 agent surface gives external agents a small JSON API for private document work and durable research. Download the Sponge research skill, discover the surface through the agent manifest, or read the OpenAPI 3.1 JSON. The API, matching CLI contract, discovery manifest, and skill are active at spongeresearch.com. The live research pressure test reached its required human-review barrier.

1. Delegate narrowly.A signed-in member creates a scoped token on the private Agent access page. Use account-wide access only to create the initial document, then replace it with a token bound to that document whenever possible. Choose only the capabilities, request budgets, and expiry the task needs. Every operation publishes its exact scope, document-boundary rule, and byte limits in OpenAPI.
2. Read exact state.Keep the bare Sponge-Revision, document version, and content digest returned with the canonical rich document. A weak ETag validates GET caches only and is never a command precondition. Opaque references remain opaque.
3. Apply semantic changes.Send a bounded mutation with a fresh idempotency key and the exact revision in Sponge-If-Revision. An exact retry reuses its original key, body, and revision even if the document has advanced. A missing revision returns 428; a stale changed command returns 412, so refresh the document and replan.
4. Delegate when useful.Start one durable research job in the same document, then poll canonical state or resume its monotonic event stream. Sponge uses one server-owned inference configuration. Research requests describe the report, not its execution policy. Report export returns exact rich JSON or loss-reported Markdown only after the report is ready.
5. Hand judgment back.An agent may propose work, but only a person can decide a review, expand rights, resolve identity, finalize an edition, enable publication, or publish.

POST /api/v1/documents
GET  /api/v1/documents/{documentRef}
POST /api/v1/documents/{documentRef}/mutations  Sponge-If-Revision: <revision>
POST /api/v1/research-jobs
GET  /api/v1/research-jobs/{jobId}/events
GET  /api/v1/research-jobs/{jobId}/report?format=markdown

From a repository checkout, run bun run cli -- …. The matching CLI provides sponge document create, document show, and document apply for the exact snapshot loop, plus sponge research commands for durable delegation, observation, report export, and explicit cancellation. External agents can call the same HTTP contract directly; the downloadable skill does not depend on access to this private repository.

Sponge stores the rich document as the canonical object. Headings, paragraphs, lists, tables, code, links, citations, and nested blocks retain structured meaning rather than being reduced to a Markdown string. Every durable version can be inspected and recovered.

1. Create privately.A document begins in the owner's workspace and does not become public by acquiring a URL.
2. Edit rich structure.Use one continuous editor with stable block identity, semantic tables, code, links, and evidence citations.
3. Follow durable state.Saved state follows server acknowledgement. Offline or rejected work remains recoverable instead of being silently discarded.
4. Inspect history.Compare exact versions, restore intentionally, and keep published checkpoints independent of later private edits.

A block is a stable, document-scoped unit of rich content. Moving or nesting it does not mint a new identity. Collaboration, links, history, agent changes, citation ordering, and public checkpoints follow that identity through the document tree.

• The outline indexes all supported block kinds and remains bounded for documents with 10,000 representative blocks.
• Deep imported hierarchies are walked iteratively, avoiding recursive stack failure.
• Large imports apply as one document transaction and one undo boundary.
• An agent must hold the exact current block editing lease; selection alone never grants mutation authority.
• Remote, local, undo, redo, recovery, and agent changes keep distinct origins so retry and reconciliation remain predictable.

Markdown is an import, export, and interchange format. It is not the canonical document model. Before replacing a document, Sponge parses a bounded source, shows the normalized rich preview, and reports syntax or semantics that cannot survive the conversion exactly.

The loss report identifies omitted citation structure, unsupported raw HTML or footnotes, table normalization, internal links, and any source that differs from the canonical preview. A warning never becomes an implicit destructive conversion.

A Source is an ordinary graph Entity classified through reviewed vocabulary. The evidence picker searches the current document's authorized knowledge space and presents human-readable source details. Authors do not paste private graph IDs or record digests into prose.

1. Choose a Source.Search the authorized graph by visible source identity, type, location, and evidence context.
2. State the bearing.Mark whether the evidence supports, contradicts, corroborates, quotes, reports a method, or provides background.
3. Preserve the selector.Keep the relevant passage, locator, observation, and graph revision bound to the citation.
4. Publish a safe artifact.Public pages receive ordered evidence markers, callouts, and bibliography data without private graph coordinates. A Source label becomes a link only while an exact artifact grant is active for that publication graph revision.

Rich paste rekeys citation clusters in one transaction so copied citations cannot collide. Citation numbers follow current recursive document order, while the verified private evidence rail remains the authority for duplication and publication.

Whole-document and block duplication currently stops before creating a copy when the source contains citations. Lossless cited duplication will return when the new copy can establish its own verified citation authority.

AI proposes; evidence and people decide. An agent can search bounded context and propose Entities, Statements, Contexts, Assertions, Evidence, type memberships, and Inquiry events. It cannot accept its own work, change identity, grant rights, finalize an edition, or publish.

1. Submit a bounded proposal.The proposed change set names exact evidence and is parsed before review.
2. Claim the review.A person opens the stable proposal detail, inspects the exact effect, and takes a short-lived review lease.
3. Accept or reject research use.Acceptance derives reviewed Assertions, Evidence, type memberships, provenance, review, and rights records as one recoverable effect.
4. Promote separately.If accepted research should support a public encyclopedia edition, a second review item is created for that purpose.

Seven primitives carry identity, meaning, epistemic stance, evidence, context, curiosity, and presentation. Domain categories live in versioned vocabularies and Shapes, so adding a scientific, legal, historical, geographic, or cultural domain does not add a new root kind.

Entity

A stable identity anchor for something that can be referred to.

Statement

An immutable proposition with a subject, predicate, object, and qualifiers.

Assertion

An attributable stance toward a statement for a particular purpose.

Evidence

A typed account of how a source or observation bears on an assertion.

Context

The time, place, language, perspective, or scenario in which knowledge applies.

Inquiry

A human question and the durable trail of investigation it creates.

Projection

A reproducible view or immutable edition derived from exact knowledge and policy.

An Inquiry makes curiosity durable. It begins with a human-authored question, an intended purpose, and private scope. Its append-only trail retains narrower questions, assumptions, observations, gaps, candidate statements, agent proposals, review decisions, and shifts in direction.

1. Ask the question.Create a private Inquiry with a stable identity and server-recorded beginning.
2. Develop the trail.Connect documents, Sources, Statements, Contexts, contradictions, and unresolved gaps.
3. Use agents as researchers.Let bounded tools search and propose while preserving every proposal as reviewable work.
4. Decide deliberately.Human decisions advance the research graph; rejected and superseded work remains attributable history.

Publishing a conclusion does not publish the private Inquiry trail. Only exact reviewed dependencies admitted to a released projection can cross the public boundary.

A public knowledge page is an immutable artifact plus an explicit release. The artifact carries supported passages and a complete dependency manifest. The release gives that artifact a public locator and can advance a canonical head without rewriting older editions.

1. Stage supported passages.Every passage names one or more reviewed Statements from an exact graph generation.
2. Review the synthesis.A person inspects the root, passages, support, omissions, dependencies, identity state, and rights eligibility.
3. Finalize immutably.The accepted candidate becomes a sealed Edition with its own stable identity.
4. Enable publications.The space owner crosses a separate, explicit boundary before any knowledge release is possible.
5. Publish a release.The exact Edition receives a canonical /k locator. A later edition creates a new artifact and release.

Withdrawal or tighter rights can stop a release from resolving without mutating the immutable artifact or inventing a new history. Public eligibility is checked again when a page is read.

The graph stores 18 immutable record kinds. They are semantic and authority records, not a fixed inventory of things in the universe. Source, person, organization, account, place, event, work, artifact, concept, process, and future domains are reviewed vocabulary terms.

Activity

An attributable action such as import, proposal, review, transformation, or publication.

Assertion

An attributable stance toward one Statement for a declared purpose and Context.

Context

A precise boundary for time, place, language, perspective, version, or scenario.

Dependency manifest

The complete ordered set of exact records required to reproduce an edition.

Edition

An immutable synthesis whose passages retain exact support and policy dependencies.

Entity

A durable identity anchor independent of its labels, types, and external identifiers.

Evidence

A typed account of how a source, observation, selector, or method bears on an Assertion.

Identity operation

A reviewed merge, split, redirect, quarantine, rekey, or tombstone over identity anchors.

Inquiry

A human question and the bounded investigation it initiates.

Inquiry event

One append-only step in an Inquiry, including a gap, observation, proposal, or decision.

Review decision

A human decision over an exact proposed effect under one review purpose.

Rights decision

A purpose-bound decision describing where an exact subject may be disclosed.

Schema

An immutable definition for a concept, predicate, unit, mapping, or extension value.

Shape

A composable validation and projection lens for one use, domain, or audience.

Statement

An immutable proposition with a subject, predicate, typed object, and qualifiers.

Type membership

Evidence-bearing membership of an Entity in a versioned concept.

View

A purpose-bound specification for selecting and presenting exact graph state.

Vocabulary

A versioned, owned collection of concepts, predicates, units, mappings, and Shapes.

Entity: "Voyager 1"
Type membership: Spacecraft
Statement: "Voyager 1 entered interstellar space"
Context: { time: "2012", definition: "plasma-density boundary" }
Assertion: { stance: "supports", purpose: "research" }
Evidence: { source: "mission report", selector: "findings" }
Projection: { purpose: "public encyclopedia", edition: "immutable" }

An Entity or Inquiry ID is an opaque identity anchor. Labels, classifications, external URLs, and vocabulary revisions can change without changing that anchor. A graph revision identifies exact knowledge state; an Edition digest identifies exact synthesis bytes; a release determines whether a public locator resolves.

Edition

https://spongeresearch.com/k/edition/<edition-id>/<edition-digest>

Entity

https://spongeresearch.com/k/entity/<entity-id>/<graph-revision>

Inquiry

https://spongeresearch.com/k/inquiry/<inquiry-id>/<graph-revision>

How identity stays conservative

• Similar names, shared URLs, model confidence, or overlapping types never merge two anchors automatically.
• Identity operations require explicit review and preserve enough history to understand or recover the change.
• A locator is not an access grant. It resolves only through a current, purpose-bound public release.

Document

A private, versioned rich research workspace composed of stable nested blocks.

Block

A durable document-scoped unit of rich content with bounded collaboration and agent actions.

Source

An Entity classified as a citable information resource through reviewed vocabulary and evidence.

Citation

A document reference to exact graph evidence, its bearing, selector, Context, and graph revision.

Inquiry

A human question with a private, append-only trail of research events, gaps, proposals, and decisions.

Shape

A versioned, composable validation and projection lens for one purpose or domain.

Proposal

An exact bounded change set that has no authority until a person reviews it.

Edition

An immutable synthesis whose passages and complete dependencies have passed human review.

Release

The explicit public binding between an eligible artifact and its canonical /k locator.