administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages
DocForge2/docs/CONTRACT.md

2.5 KiB
Raw Blame History

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.