mosaicstack/stack
1
0
Fork 1
Code Issues 105 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

wake: digests cannot date their snapshot — emit snapshot commit SHA/ts alongside observed_hash (adapter fd-3 metadata channel) #940

New Issue
Closed
opened 2026-07-30 10:08:12 +00:00 by mos-dt-0 · 0 comments
mos-dt-0 commented 2026-07-30 10:08:12 +00:00
Contributor
Copy Link
Copy Source

Filed from the pepper seat, following mos-dt's fw-wake-digest-snapshot-lag finding (SSOT: jarvis-brain data/tasks/work.json).

Problem (measured, live)

A digest's ACTIONABLE/ORIENTATION locator carries observed_hash (content hash) + emit_ts, but nothing that DATES the snapshot. Live measurement (mos-dt): digest seq 56's observed_hash matched board revision 95c38cd30 (04:45:45); the next revision d4cf1aff1 (04:48:55) landed ~5s BEFORE the digest was delivered and introduced a FLEET STOP block — the digest read as "(none) actionable" while the board already said otherwise. The fast path cannot tell a fresh snapshot from a stale one without a tool call.

Why the fix is NOT operator-adapter-only

The dragon-lin adapter already knows the snapshot commit at observe time (it rev-parses origin/main:<path>), but the W4 adapter contract has exactly one output channel — stdout — and EVERYTHING on stdout is hashed by the detector's delta gate. Embedding the tip commit SHA in the descriptor would advance observed_hash on every unrelated push to the repo → a spurious delta wake for every watched file. The metadata needs an out-of-band channel.

Proposed fix (additive, backward-compatible)

  1. detector.sh (A1): invoke the source adapter with fd 3 redirected to a temp file. The adapter MAY write a single JSON object there: {"snapshot_sha": "<git commit sha>", "snapshot_ts": <epoch>}. Validate strictly (sha ^[0-9a-f]{7,64}$, ts integer); malformed metadata is dropped with a LOUD stderr diagnostic but never gates/fails the poll (metadata is advisory — the wake obligation never depends on it). Valid fields merge into the enqueue locators. Old adapters write nothing to fd 3 → empty file → no fields → byte-identical behavior.
  2. digest.sh (A3): _locator_line renders snapshot_sha= / snapshot_ts= (scrubbed) alongside observed_hash=; when snapshot_sha + path are present the one-call re-verify hint upgrades to git show <snapshot_sha>:<path> (snapshot_sha IS a commit sha, unlike observed_hash, so it may feed the git hint).
  3. Tests: detector — metadata captured into locators; malformed metadata dropped loudly without failing the poll; no-fd3-write → no fields. digest — snapshot fields render; reverify hint upgrade.
  4. manifest.txt: 0.6.12 entry. Watch-list schema untouched ([1,1] unchanged — this is adapter-contract + locator vocabulary, not watch-list config).

With snapshot_ts + the existing emit_ts, snapshot age becomes local arithmetic and the digest-lag class above is self-evident to the consumer with zero round trips.

Operator side (not this repo): dragon-lin's source-adapter.sh gains a guarded fd-3 write (git rev-parse origin/main + committer ts for repo sources; mtime for local-file sources).

Filed from the pepper seat, following mos-dt's fw-wake-digest-snapshot-lag finding (SSOT: jarvis-brain data/tasks/work.json). ## Problem (measured, live) A digest's ACTIONABLE/ORIENTATION locator carries `observed_hash` (content hash) + `emit_ts`, but nothing that DATES the snapshot. Live measurement (mos-dt): digest seq 56's observed_hash matched board revision 95c38cd30 (04:45:45); the next revision d4cf1aff1 (04:48:55) landed ~5s BEFORE the digest was delivered and introduced a FLEET STOP block — the digest read as "(none) actionable" while the board already said otherwise. The fast path cannot tell a fresh snapshot from a stale one without a tool call. ## Why the fix is NOT operator-adapter-only The dragon-lin adapter already knows the snapshot commit at observe time (it rev-parses `origin/main:<path>`), but the W4 adapter contract has exactly one output channel — stdout — and EVERYTHING on stdout is hashed by the detector's delta gate. Embedding the tip commit SHA in the descriptor would advance observed_hash on every unrelated push to the repo → a spurious delta wake for every watched file. The metadata needs an out-of-band channel. ## Proposed fix (additive, backward-compatible) 1. **detector.sh (A1):** invoke the source adapter with **fd 3** redirected to a temp file. The adapter MAY write a single JSON object there: `{"snapshot_sha": "<git commit sha>", "snapshot_ts": <epoch>}`. Validate strictly (sha `^[0-9a-f]{7,64}$`, ts integer); malformed metadata is dropped with a LOUD stderr diagnostic but never gates/fails the poll (metadata is advisory — the wake obligation never depends on it). Valid fields merge into the enqueue locators. Old adapters write nothing to fd 3 → empty file → no fields → byte-identical behavior. 2. **digest.sh (A3):** `_locator_line` renders `snapshot_sha=` / `snapshot_ts=` (scrubbed) alongside `observed_hash=`; when `snapshot_sha` + `path` are present the one-call re-verify hint upgrades to `git show <snapshot_sha>:<path>` (snapshot_sha IS a commit sha, unlike observed_hash, so it may feed the git hint). 3. **Tests:** detector — metadata captured into locators; malformed metadata dropped loudly without failing the poll; no-fd3-write → no fields. digest — snapshot fields render; reverify hint upgrade. 4. **manifest.txt:** 0.6.12 entry. Watch-list schema untouched ([1,1] unchanged — this is adapter-contract + locator vocabulary, not watch-list config). With `snapshot_ts` + the existing `emit_ts`, snapshot age becomes local arithmetic and the digest-lag class above is self-evident to the consumer with zero round trips. Operator side (not this repo): dragon-lin's source-adapter.sh gains a guarded fd-3 write (`git rev-parse origin/main` + committer ts for repo sources; mtime for local-file sources).
Mos closed this issue 2026-07-30 10:55:20 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#940