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

Manage graph viewers with a supervised local service

Browse source
This commit is contained in:
Andraxion 2026-07-25 00:17:21 -04:00
parent eb48ba1a51
commit 7c87536167
14 changed files with 1027 additions and 103 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/CONTRACT.md
View file

@ -1,4 +1,4 @@
# DocForge 0.11 contract
# DocForge 0.12 contract
## Authority boundary
@ -23,7 +23,7 @@ approved contract and measured cross-project evidence; it is not an unimplemente
- 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.11.0.
- Core, CLI, and MCP server: version 0.12.0.
Schema files describe the generic interchange contract. Runtime validation remains responsible for
path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@ -147,16 +147,19 @@ shortest-hop calculation places Nodes on distance rings; Flow uses left-to-right
with the destination on the right. Each role palette darkens progressively by distance, capped at
fifty percent.
Each invocation creates or reuses one persistent local worker for the validated snapshot. The worker
is detached from the short-lived MCP transport and has no browser inactivity or owner-process
expiry. A repeated invocation reuses its unguessable URL when the validated snapshot is unchanged.
If the index has changed, DocForge replaces the worker only after a fresh complete index check.
Each invocation creates or reuses one worker through the separately supervised, per-user viewer
manager. The manager is outside the short-lived MCP transport and owns all child workers as one OS
service unit. It accepts only authenticated loopback requests and a validated immutable snapshot.
A repeated invocation reuses its unguessable URL when the snapshot is unchanged. If the index has
changed, it replaces the worker only after a fresh complete index check.
`docforge_stop_visualization` is the only normal shutdown path. It stops the current project's
verified worker and removes its private registry record. The worker also ends if the operating
system terminates it. Project-specific integrations receive the same tools because the parent
validates and serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; the worker
does not discover projects or load canonical sources.
`docforge_visualization_status` reports the managed worker state. `docforge_stop_visualization`
explicitly stops the current project's worker. The manager applies a one-hour activity timeout to
genuinely abandoned workers. Browser activity renews that timeout, but normal MCP transaction or
host-process completion does not affect it. The manager itself is restarted by an OS-native,
per-user supervisor. Project-specific integrations receive the same tools because the parent
validates and serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; workers do
not discover projects or load canonical sources.
## Project adapter boundary