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

30
DEVELOPMENT_NOTES.md
View file

@ -241,6 +241,32 @@ will be recorded only from a clean committed revision. The historical Milestone
behaviorally unchanged as comparison evidence; it only exposes shared fixture and measurement
helpers to the Milestone 1 harness.
#### Visualization snapshot freshness
Visualization workers now receive a version-1 snapshot specification containing the exact
validated index publication signature: device, inode, size, modification time, and change time.
Both the manager and worker reject a launch if that publication changes before startup. The
transmitted project root, root fingerprint, source identity, adapter, counts, limits, and confined
index path are strictly validated before the worker may serve source or graph data.
Worker health reports index freshness through stat-only comparison. It does not open SQLite and
does not renew the browser activity lease. The version-2 viewer-manager protocol validates the
complete worker identity and distinguishes an unreachable worker from a live stale worker. A stale
worker stays lifecycle `running` for accurate diagnosis, but the next visualize request stops it
and launches a newly validated snapshot instead of reusing it.
Client status separately compares the worker's pinned source identity with
`IncrementalStateProject.incremental_state()`. The composite snapshot is stale if either proof is
stale, current only when both proofs are current, and unknown otherwise. A stopped worker has
unknown snapshot identity. MCP preserves this state at the top-level `staleness` field and disables
recovery synchronization and full-load error decoration.
Tests cover signature mutation before worker startup, malformed identity, missing and symlinked
indexes, stat-only health, unchanged activity, current/unknown/stale source states, live stale
workers, non-reuse, and zero-load status. The Milestone 1 benchmark now measures current, stale,
not-running, and unavailable visualization status separately with the same zero-work and 50 ms p95
gates as other receipt status operations.
### Initial design constraints
- Full rebuild remains the recovery and equivalence oracle.
@ -262,7 +288,7 @@ These are notes, not commitments:
- A durable telemetry exporter remains deliberately deferred. Request-local bounded aggregates are
enough to prove compiler work in Milestone 1 without adding persistence, cardinality, or privacy
risks.
- Visualization freshness needs a separate source/index snapshot contract. Lifecycle health alone
must not be relabeled as current documentation state.
- The stat identity is a cheap publication proof, not a cryptographic integrity scan. Full index
validation remains the launch and query oracle.
- Large context and changeset payloads may need cursor pagination or compact immutable receipts.
The choice should follow actual client workflows rather than generic pagination machinery.