62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# DocForge 0.2 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.2.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.
|
|
|
|
Normal MCP access does not expose canonical application, arbitrary file writes, previews, renderer
|
|
execution, shell commands, Git mutation, build commands, deployment, or publication.
|