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

feat: add isolated proposal changesets

Browse source
This commit is contained in:
Andraxion 2026-07-22 02:58:51 -04:00
parent 9702ed1265
commit 8c75f4f44d
22 changed files with 2314 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/CONTRACT.md
View file

@ -1,12 +1,12 @@
# DocForge 0.1 contract
# 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 may validate and retrieve canonical nodes. A future proposal service may write only
isolated changesets. Canonical application, project builds, Git mutation, deployment, and
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.
@ -16,9 +16,9 @@ commit when Git is available; it cannot change repository state.
- 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.
- Changeset schema: `schemas/changeset.schema.json`, version 1.
- Index schema: version 1, disposable and reproducible.
- Core and CLI: version 0.1.0.
- 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
@ -40,10 +40,23 @@ Successful operations identify the project, adapter, current revision when avail
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
## 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
required incoming relationships. Validation and application are atomic; prose is never auto-merged.
every incident relationship. Proposal validation and storage are atomic. Canonical application
remains external, and prose is never auto-merged.
Normal MCP access will not expose canonical application or arbitrary file writes.
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.