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
• 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, for engine-side review

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. An engine never hands quarantined content to any agent.

A revision and a patch carry their content in the clear.

Structs

ContextPatchV1

Patch of a proposal against base_revision, in the clear.

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.

KnowledgeRevisionV1

One revision of a vault’s knowledge; KnowledgeRevisionV1::validate refuses a revision without its document.

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.

Enums

DraftOrigin

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

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_REVISION_SCHEMA

MAX_DOCUMENT_CHARS

Characters of the serialized document.

MAX_FACTS

1.9: 5,000 facts (wiki scale).

MAX_KNOWLEDGE_BODY_BYTES

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

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

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).

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).