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

Make project MCP workflows self-synchronizing

Browse source
This commit is contained in:
Andraxion 2026-07-26 09:32:25 -04:00
parent a30f021a52
commit 73165c9f51
17 changed files with 1124 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/CONTRACT.md
View file

@ -19,7 +19,8 @@ commit when Git is available; it cannot change repository state.
- Result envelope: `schemas/result.schema.json`, version 1.
- Changeset schema: `schemas/changeset.schema.json`, version 1.
- Index schema: version 2, disposable and reproducible.
- Core, CLI, and MCP server: version 1.2.0.dev0.
- Index attestation: schema version 1, disposable and reproducible.
- Core, CLI, and MCP server: version 1.3.0.dev0.
- Incremental extraction cache: version 1, disposable and reproducible.
Schema files describe the generic interchange contract. Runtime validation remains responsible for
@ -39,8 +40,14 @@ gives special acyclic validation to `depends_on`; adapters may add stricter rule
## 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.
source hash. Errors use a stable code, direct message, structured details, and a bounded remediation
tool when recovery is safe. MCP operations synchronize disposable index state under a project lock
before reading or proposing. Canonical source validation remains fail-closed.
An atomic index build writes a whole-file SHA-256 attestation after complete graph, row, FTS, and
SQLite integrity verification. A fresh process may use that receipt to verify an unchanged index
without reconstructing all graph rows. A missing, malformed, or mismatched receipt falls back to
complete verification and is repaired only after that verification succeeds.
## Isolated proposal model
@ -57,6 +64,9 @@ The MCP process binds to one configured writer identity at startup. The project
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.
The atomic registration operation captures a complete operation list against one current base,
fills omitted existing-node hashes from that synchronized snapshot, validates once, and writes one
final changeset.
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
@ -64,6 +74,13 @@ sources. A stale canonical base, stale node hash, stale changeset hash, unauthor
path, invalid graph, dependency cycle, unresolved delete relationship, or configured limit fails
before the proposal file changes.
A stale proposal may be rebased only when its stored node hashes, source targets, relationship
preconditions, permissions, conflict set, and complete projected graph still validate against the
current project. Application and explicit abandonment create derived lifecycle receipts. The
default active listing contains only draft and ready work. Stale, applied, and abandoned proposals
remain queryable by explicit status or history request. Terminal proposals do not block new
proposals.
## Declared rendering and previews
Render configuration is optional. A configured project declares one template root, one isolated