Module knowledge 

Vault knowledge: the ctxpkg.research-context.v1 document, its revisions, and draft proposals streamed from engine sessions.

• GET /v1/vaults/{vault_id}/knowledge (If-None-Match: "<revision>") → KnowledgeRevisionV1 with ETag: "<revision>", or 304

• GET /v1/vaults/{vault_id}/knowledge/revisions?after=&limit= → RevisionListV1

• POST /v1/vaults/{vault_id}/proposals DraftProposalV1 → ProposalAckV1; Idempotency-Key = the engine’s outbox item id. A draft whose content is identical to an existing engine draft of the vault maps to that proposal (same number), whichever instance sent it first.

• GET /v1/vaults/{vault_id}/proposals?state=&mine=1 → ProposalListV1

• 1.6: GET /v1/vaults/{vault_id}/proposals/{number} → ProposalV1: the draft exactly as its engine sent it (a sealed patch stays sealed), for engine-side review of sealed vaults

• PUT /v1/vaults/{vault_id}/knowledge KnowledgePutRequestV1 → KnowledgeRevisionV1, or 409 revision_conflict; needs knowledge.merge. The new revision is always expected_revision + 1 (a sealed revision is sealed for that number). 1.6: merged_proposals marks those proposals merged at the new revision in the same transaction

• 1.9: GET /v1/vaults/{vault_id}/knowledge/diff?from=&to= → RevisionDiffV1: the ops from one released revision to another, so an engine with a large document fetches deltas (in the clear only; a sealed vault answers 409 invalid_state reason sealed)

Revision 0 is the empty document. A draft becomes a revision only after review in Hive.

Quarantine (1.9, owner O3): a revision that an auto-merge threshold produced (no person reviewed it) starts quarantined. GET …/knowledge delivers the newest released revision (revision is that delivered head) and counts the quarantined revisions after it in quarantined_after; ?revision=N reads a quarantined one for review (right knowledge.merge). An engine never hands quarantined content to any agent except for that review. A person releases it, or rolls it back, within 24 hours; otherwise Hive proposes a task (origin quarantine_timeout). A rollback appends a new revision with the document of an earlier one (rolls_back). In a sealed vault an engine performs it, because only an engine can re-seal for the new number.

Structs

ContextPatchV1

Patch of a proposal against base_revision: ops in the clear, or sealed (the encrypted ops array) for sealed vaults.

DraftProposalV1

POST /v1/vaults/{vault_id}/proposals: a draft from one session.

EngineScreeningV1

What the engine’s screening removed before the draft was queued.

FactV1

One fact.

KnowledgeEventV1

1.9 knowledge.event (service → client), on the vault channel: the engine fetches the delivered head (or the quarantined revision, to review it) over HTTP.

KnowledgePutRequestV1

PUT /v1/vaults/{vault_id}/knowledge: compare-and-set a whole revision.

KnowledgeRevisionV1

One revision of a vault’s knowledge; exactly one of document/sealed.

PageV1

1.9: a readable wiki page built from facts (the “tree” of the ctxpkg mapping). Pages are part of the reviewed document.

ProposalAckV1

Response of POST /v1/vaults/{vault_id}/proposals.

ProposalListV1

Response of GET /v1/vaults/{vault_id}/proposals.

ProposalSummaryV1

One proposal in a listing.

ProposalV1

Response of GET /v1/vaults/{vault_id}/proposals/{number} (1.6).

RelationV1

A typed edge between two facts.

ResearchContextDocumentV1

The knowledge document of one vault.

RevisionDiffV1

1.9: GET /v1/vaults/{vault_id}/knowledge/diff?from=&to=.

RevisionListV1

Response of GET /v1/vaults/{vault_id}/knowledge/revisions.

RevisionSummaryV1

One entry of the revision history.

Enums

DraftOrigin

1.9: the origin of a draft. Every origin passes the same engine admission filter before upload.

KnowledgeEventKind

PageItemV1

1.9: one item of a wiki page.

PatchOpV1

One edit of a proposal patch.

ProposalState

Review state of a proposal.

RevisionState

1.9: whether a revision is delivered to agents.

Constants

DRAFT_PROPOSAL_SCHEMA

FACT_KINDS

1.9 adds gotcha, dead_end, experience and convention.

KNOWLEDGE_PUT_REQUEST_SCHEMA

KNOWLEDGE_REVISION_SCHEMA

MAX_DOCUMENT_CHARS

Characters of the serialized document.

MAX_FACTS

1.9: 5,000 facts (wiki scale); engines fetch deltas with RevisionDiffV1.

MAX_KNOWLEDGE_BODY_BYTES

Largest knowledge request/response body (a full document fits).

MAX_MERGED_PROPOSALS

Most proposals one revision may merge.

MAX_PAGES

1.9: wiki pages per document, items per page, characters of a prose item.

MAX_PAGE_ITEMS

MAX_PATCH_OPS

Ops per proposal patch.

MAX_PROSE_CHARS

MAX_REFERENCES

MAX_RELATIONS

MAX_REVISIONS_PAGE

Revisions per page.

PROPOSAL_ACK_SCHEMA

PROPOSAL_LIST_SCHEMA

PROPOSAL_VIEW_SCHEMA

1.6: one proposal with its draft.

RELATION_TYPES

Edges between facts; 1.9 adds explains. Edges to code, work and actors belong to the graph view (super::graph), not to the document.

RESEARCH_CONTEXT_FORMAT

Format id of the knowledge document (the package format keeps its name).

REVISION_DIFF_SCHEMA

REVISION_LIST_SCHEMA

Functions

import_source_ok

1.9: an import source, import:docs:<path>#<slug> (repo-relative path, slug of [a-z0-9-]) or import:git:<sha> (40 or 64 lowercase hex).