50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
|
# DocForge 0.1 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 may validate and retrieve canonical nodes. A future proposal service may write 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, reserved for DFG-3.
|
||
|
|
- Index schema: version 1, disposable and reproducible.
|
||
|
|
- Core and CLI: version 0.1.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.
|
||
|
|
|
||
|
|
## Write model reserved for DFG-3
|
||
|
|
|
||
|
|
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
|
||
|
|
required incoming relationships. Validation and application are atomic; prose is never auto-merged.
|
||
|
|
|
||
|
|
Normal MCP access will not expose canonical application or arbitrary file writes.
|