DocForge 0.4 contract

Authority boundary

DocForge is bound to one explicit project root. Canonical project files own documentation facts. Indexes, query results, context packs, changesets, previews, and renders are derived artifacts.

The generic core validates and retrieves canonical nodes. A project-bound proposal service writes only isolated changesets. Canonical application, project builds, Git mutation, deployment, and publication remain external integration actions. Passive revision detection may read the current Git commit when Git is available; it cannot change repository state.

Versioned contracts

Project descriptor schema: schemas/project.schema.json, version 1.
Node schema: schemas/node.schema.json, version 1.
Edge schema: schemas/edge.schema.json, version 1.
Result envelope: schemas/result.schema.json, version 1.
Changeset schema: schemas/changeset.schema.json, version 1.
Index schema: version 1, disposable and reproducible.
Core, CLI, and MCP server: version 0.4.0.

Schema files describe the generic interchange contract. Runtime validation remains responsible for path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale state, and adapter-specific rules that JSON Schema cannot prove by itself.

Generic node storage

Markdown nodes begin with a TOML metadata block delimited by +++. The remaining Markdown is the node content. TOML sources contain one or more [[nodes]] tables and store content in a content field. Every node has a stable project-wide ID.

The generic authority vocabulary is authoritative, approved_plan, derived, proposal, and historical. Projects define statuses and allowed relationship names in their descriptor. The core gives special acyclic validation to depends_on; adapters may add stricter rules.

Result identity

Successful operations identify the project, adapter, current revision when available, and canonical source hash. Errors use a stable code, direct message, and structured details. Query operations fail if canonical source no longer matches the derived index.

Isolated proposal model

Create, update, move, and delete are ordered node operations inside an isolated changeset. Every operation names its expected base hash. A move preserves the stable node ID. A delete must resolve every incident relationship. Proposal validation and storage are atomic. Canonical application remains external, and prose is never auto-merged.

The MCP process binds to one configured writer identity at startup. The project descriptor grants that writer explicit families and operation types. A changeset records its creator, project root fingerprint, base revision, canonical source hash, and ordered operations. Every append requires the current changeset hash, so simultaneous writers cannot silently lose an operation.

Changesets from the same canonical base may coexist only when their touched node and source sets do not overlap. Exact overlaps return structured conflicts naming the other changesets, nodes, and sources. A stale canonical base, stale node hash, stale changeset hash, unauthorized family, unsafe path, invalid graph, dependency cycle, unresolved delete relationship, or configured limit fails before the proposal file changes.

Declared rendering and previews

Render configuration is optional. A configured project declares one template root, one isolated preview root, and one or more stable view IDs. Each view names a built-in renderer, template, derived output file, title, and optional family filter. Paths are resolved under the project root and may not overlap canonical content, authority files, changesets, templates, or previews.

The initial generic_html renderer uses pinned CommonMark parsing with raw HTML disabled. Templates are UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable renderers. Render identity covers the canonical source hash, optional changeset hash, selected node and edge identities, view configuration, template hash, renderer contract, and exact parser version.

An explicit CLI render atomically replaces one declared derived output. MCP can render a validated changeset only to its isolated preview path. Status recomputes expected output without writing and reports current, stale, missing, unsafe, or oversized. Input changes detected before atomic replacement fail without replacing the prior output.

Normal MCP access does not expose canonical application, declared project-output rendering, arbitrary renderer execution, arbitrary file writes, shell commands, Git mutation, build commands, deployment, or publication.

Project adapter boundary

An adapter supplies one deterministically ordered AdapterProjection containing core nodes and edges plus ordered adapter metadata. The core validates root identity, graph integrity, stable ordering, and metadata-key uniqueness before exposing the projection through the standard derived index. The loader is called again during an operation so identity or source changes fail closed.

Adapters own stricter project semantics such as authority precedence, phase rules, context selection, query ordering, and render-model composition. They may not weaken root confinement, canonical authority, graph validation, hashing, stale-state checks, or derived-output boundaries. Shadow adapters are explicit local integrations and are not loaded by the normal MCP process.

5.4 KiB Raw Blame History