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

Bind visualization status to snapshot freshness

Browse source
This commit is contained in:
Andraxion 2026-07-29 05:23:52 -04:00
parent 24bd13f9d9
commit 176b2d2784
9 changed files with 627 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

13
docs/MCP_CONTRACT.md
View file

@ -182,9 +182,16 @@ bridges its retained predecessors and successors with an explicit omitted path.
a project-bound worker owned by
the separately supervised per-user viewer manager. Standard-input transaction completion and MCP
host exit do not close the listener. Repeated visualization requests reuse the current worker while
its exact snapshot remains valid. `docforge_visualization_status` reports lifecycle state, and
`docforge_stop_visualization` explicitly stops the current project's worker. The manager reclaims a
worker only after one hour with no browser activity.
its exact snapshot remains valid. The version-2 manager protocol binds each worker to the exact
validated five-field index publication signature. Health checks compare that signature without
opening SQLite. A stale worker remains `state = running` but is never reused.
`docforge_visualization_status` reports lifecycle and freshness independently. `snapshot_state` and
top-level `staleness` are `stale` when either the index or cheap source identity is proven stale,
`current` only when both are proven current, and `unknown` otherwise. The `freshness` object exposes
the separate index and source states. Status never checks, synchronizes, or rebuilds the index and
never performs a complete project load. `docforge_stop_visualization` explicitly stops the current
project's worker. The manager reclaims a worker only after one hour with no browser activity.
## Excluded tools

11
docs/USER_MANUAL.md
View file

@ -254,6 +254,17 @@ docforge --project-root "$PROJECT" visualize --query persistence
The command opens the default browser. Add `--no-open` when a script only needs the returned JSON
URL. Use `visualization-status` and `visualization-stop` to inspect or stop the project viewer.
Status separates the worker lifecycle from snapshot freshness. A worker may remain `running` while
`snapshot_state` is `stale`; it will not be reused by the next `visualize` call. `freshness.index`
checks the exact pinned index publication with file identity only. `freshness.source` compares the
cheap project generation when the project can prove one. Unavailable proof is `unknown`, never
silently `current`. Status does not load project content, open SQLite, rebuild the index, or renew
browser activity.
The freshness protocol requires viewer manager version 2. After upgrading an already running
installation, rerun `docforge-viewer-manager install-user-service` or restart the foreground
manager before requesting status.
## Visualization usage
- Left-click a node for its compact descriptor.