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

Add relationship-aware graph flow

Browse source
This commit is contained in:
Andraxion 2026-07-24 23:40:47 -04:00
parent 9bd41c5982
commit 440ca7510f
11 changed files with 567 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/CONTRACT.md
View file

@ -1,4 +1,4 @@
# DocForge 0.7 contract
# DocForge 0.10 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.9.0.
- Core, CLI, and MCP server: version 0.10.0.
Schema files describe the generic interchange contract. Runtime validation remains responsible for
path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@ -107,7 +107,7 @@ family, authority, status, or tag plus one exact value. The heartbeat changes no
state. There is no write endpoint, arbitrary query endpoint, static filesystem handler, external
asset, or project-selection control.
The `graph-browser@7` template provides mouse-wheel zoom centered on the pointer, left-button drag
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
four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks.
Loading another root node fits the viewport to the returned neighborhood, including a useful
@ -127,16 +127,26 @@ controls, and backdrop dismissal. Loading the inspected node as the new root req
Explore neighborhood action. Both side panels support pointer and keyboard resizing. The unblurred
full inspector supports native resizing and constrained title-bar dragging.
The header exposes a Nodes/Flow segmented selector. Both positions intentionally retain the node
graph in this contract version. Flow traversal and layout semantics remain unclaimed until relation
direction and eligibility are defined.
The header exposes a Nodes/Flow segmented selector. Nodes displays the complete bounded
neighborhood. Flow displays an upstream lineage ending at the current root. Calls, dispatches,
launches, activations, and writes retain their declared source-to-target direction. Reads, imports,
and dependencies reverse for lineage presentation because the declared target feeds the source.
Structural, evidence, and context relations remain available in Nodes but are excluded from Flow.
This is a presentation transform over the validated bounded snapshot; it does not add or change
project relationships.
The browser derives presentation roles only from the returned bounded graph. The current root is
the primary focus. Nodes reachable through outgoing edges are children. Remaining incoming and
cross-boundary nodes are edge/context nodes. These roles receive distinct palettes and navigation
sections. An undirected shortest-hop calculation places nodes on distance rings and darkens each
role palette progressively, capped at fifty percent. This presentation does not reinterpret,
replace, or add project relationships.
Both views color edges by relationship semantics and retain direction with visible SVG endpoint
symbols. Line patterns provide a non-color cue. A static canvas key shows the exact symbol, color,
label, and visible count for each displayed relation, including a deterministic fallback for
project-defined relations. Nodes and Flow use the same map.
The browser derives node presentation roles only from the returned bounded graph. The current root
is the focus. In Nodes, nodes reachable through outgoing edges are shown as outgoing paths; the
remaining visible nodes are incoming or lateral context. In Flow, lineage predecessors are shown as
upstream nodes. These roles receive distinct palettes and navigation sections. An undirected
shortest-hop calculation places Nodes on distance rings; Flow uses left-to-right distance layers
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