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

Keep visualization worker alive until explicit stop

Browse source
This commit is contained in:
Andraxion 2026-07-24 23:55:55 -04:00
parent 440ca7510f
commit eb48ba1a51
12 changed files with 410 additions and 150 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/CONTRACT.md
View file

@ -1,4 +1,4 @@
# DocForge 0.10 contract
# DocForge 0.11 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.10.0.
- Core, CLI, and MCP server: version 0.11.0.
Schema files describe the generic interchange contract. Runtime validation remains responsible for
path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@ -86,7 +86,7 @@ deployment, or publication.
## Project-bound graph visualization
The fixed `docforge_visualize` MCP tool starts one leased read-only graph browser for the
The fixed `docforge_visualize` MCP tool starts one persistent read-only graph browser for the
server's already-configured project. It accepts only an optional stable node ID, an optional lexical
query, and a bounded traversal depth. It does not accept a project root, database path, SQL,
template path, bind address, command, or renderer.
@ -102,10 +102,9 @@ random token is part of every accepted URL path. Only `GET` and `HEAD` are suppo
no-store caching, a restrictive content-security policy, frame denial, MIME sniffing protection,
and no-referrer policy. The built-in template uses only same-origin JSON endpoints for graph
overview, bounded search, exact descriptor-category filtering, exact node content, bounded
incoming-and-outgoing neighborhoods, and one lease heartbeat. Descriptor filtering accepts only
family, authority, status, or tag plus one exact value. The heartbeat changes no project or index
state. There is no write endpoint, arbitrary query endpoint, static filesystem handler, external
asset, or project-selection control.
incoming-and-outgoing neighborhoods. Descriptor filtering accepts only
family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
endpoint, static filesystem handler, external asset, or project-selection control.
The `graph-browser@8` template provides mouse-wheel zoom centered on the pointer, left-button drag
pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
@ -148,17 +147,16 @@ 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 launches the validated snapshot in a detached local worker. The worker is outside
the short-lived MCP transport process, so transport teardown cannot close an active browser. It
tracks the longer-lived MCP client host and closes when that owner process exits. A repeated
invocation in the same MCP process replaces its tracked worker after a fresh index check.
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.
The page renews a 180-second lease every 15 seconds and when it becomes visible; a link never opened
receives a 120-second startup grace. An abandoned page stops renewing and the detached worker closes
after the bounded lease. Explicit service shutdown closes the worker tracked by that service
immediately. Project-specific integrations receive the same tool because the parent validates and
serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; the detached worker does
not discover projects or load canonical sources.
`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.
## Project adapter boundary