feat(wake): #958 A11 preimage.sh — durable provenance for the operator-side preimage definition #964
Assignees
jason.woltje
Clear assignees
jason.woltje
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: mosaicstack/stack#964
Reference in New Issue
Block a user
Closes #958.
The operator-side preimage definition — the source-adapter file and watch-list that every
observed_hashis computed FROM — was unversioned: a byte change was attributable only via an agent transcript, and reconcile surfaced it as N UNACCOUNTED sources instead of one cause line.Mechanism: content-addressed snapshotting (option 2), not a git repo in the operator dir (option 1)
Option (1) was rejected on three grounds:
authorfield attributes nothing. The real who/why mechanism is the announce-marker lane (#957); this item owes when + prior bytes, which is exactly what a content-addressed object store + append-only ledger provides..gitignoreis pattern-based. A pattern miss silently commits credential bytes into history. A content-based refusal gate plus a path hard-block is fail-closed in a way git cannot be.What ships (wake 0.6.15 → 0.7.0, A11)
preimage.sh(new): derives the preimage set from the runtime env (the resolvedWAKE_DETECTOR_SOURCE_CMDfile,WAKE_WATCH_LIST, optionalWAKE_PREIMAGE_EXTRA); per file appends{ts,path,sha256,size,mtime,prev}to an append-only ledger and captures bytes content-addressed under$STATE_DIR/preimage/objects/<sha256>. First-seen on a genuinely clean state dir is a silent baseline (detector first-poll idiom). Deletion is a tracked state (ABSENT), not an error.class=actionableentry via the store allocator with locators{kind:preimage, path, observed_hash, prev_hash, preimage:true, reason:preimage-definition-changed}.pathis a §2.1 hard locator (#944), so the entry can never be quarantined. Bothdetector.sh cmd_poll_onceandreconcile.sh cmd_reconcilerun the check as a pre-step, so the cause line lands at a lowerobserved_seqthan the per-source deltas/enumerations it explains.objects/(B11: that state cannot be a first install — history was deleted; refuse to re-baseline over it), failed object/ledger write, failed enqueue — all loud non-zero, never read as "no change". In both integrations the pass exits non-zero but source observation still proceeds (no starvation). An object-write failure writes no ledger row (a row whose bytes were never durably kept would be a false witness).tools/wake/; the recording site is the runtime tick, which is where the env-derived preimage set actually exists. Watch-list schema untouched ([1,1]).Credential hard gate, four layers (acceptance b — redesigned after the verdict)
The original design was allow-by-default byte capture behind a path + shape deny list. The verdict broke it two ways: case C (deny list written in unresolved paths cannot match a path resolved before it arrived) and case D (a shape list can only refuse the secrets someone already enumerated). The redesign:
WAKE_PREIMAGE_EXTRA) are record-only by default — ledger row + cause line, no bytes. Byte capture for an extra requires the path listed inWAKE_PREIMAGE_CAPTURE(colon-separated opt-in). Only the core set (adapter, watch-list) is capture-eligible by default. Structural self-check (per the reviewer's requirement that D must not depend on the shape list): with_deny_contentstubbed to always-allow and no opt-in, a live-secret extra still recordscaptured:falseand its bytes are grep-absent from the state dir — the gate chain short-circuits to record-only before the content probe ever runs.key|token|secret|passw|hmac|credential|bearer= unbroken value ≥16 chars of[A-Za-z0-9+/=_-]; a variable reference liketoken="$GITEA_TOKEN"never matches because$is outside the value class). A probe error fails toward refusal — grep rc≥2 (unreadable file, pattern failure) is a deny, never a fall-through to capture. False positives are deliberately not tuned down: a false match only withholds byte capture, never tracking.WAKE_PREIMAGE_MAX_BYTES(default 1 MiB).A refused file still gets its hash/size/mtime row (
captured:false+ reason), so change time survives even when content must not.Acceptance criteria → evidence
prev=<old sha>, and both old and new bytes are byte-exact retrievable frompreimage/objects/— from durable state alone. P6: deletion is likewise a dated, attributable row.observed_seqthan the source delta. P11: reconcile pre-step enqueues the cause line before its UNACCOUNTED enumerations. Locator carriespath(hard locator, #944), so the line renders CLAIM-tier, never dead-letters.objects/→ loud refusal, ledger NOT recreated, no silent re-baseline).Tests
test-wake-preimage.shP1–P17, wired intotest:framework-shell. Red-first, both cycles:e07943d): with the detector/reconcile integration edits reverted, exactly P3/P11/P12 fail.preimage.sh, exactly P13/P14/P15/P16 fail (14 assertions) — precisely the verdict's B2-C, B2-D, polarity, and B11 findings — and 17/17 pass with the fix.CI note: failure injections are root-safe (unresolvable command, corrupt ledger, deleted ledger) — no chmod tricks that a root runner ignores.
Agent: PEPPER (sb-it-1-dt) — authored in worktree
wake-958, pushed via forkmos-dt-0/stack(this host's token has pull-only on the upstream repo; the shared-author identity note above applies to this PR itself: in-body signature is the discriminator).Per the fleet pre-registration rule: reviewer must commit diff-blind acceptance checks as a durable artifact before first read of this diff. The acceptance table above is the author-side half. For the amendment cycle the firewall is inverted per protocol — the reviewer's needles are public in the verdict and are tested against directly.
🤖 Generated with Claude Code
https://claude.ai/code/session_01NsKce8iZuSuRnu3gVMCBKB
The operator-owned bytes every observed_hash is computed FROM (the source adapter, the watch-list) were unversioned: a byte change was attributable only via an agent transcript, and reconcile surfaced it as N UNACCOUNTED sources instead of one cause. New tool preimage.sh (wake 0.6.15 -> 0.7.0): - Derives the preimage set from the runtime env (resolved WAKE_DETECTOR_SOURCE_CMD file, WAKE_WATCH_LIST, WAKE_PREIMAGE_EXTRA); per file appends {ts,path,sha256,size,mtime,prev} to an append-only ledger and captures bytes content-addressed under $STATE_DIR/preimage/objects/<sha256> — prior bytes + change time from durable state alone (acceptance a). - CREDENTIAL HARD GATE (acceptance b): byte capture is REFUSED — never redacted — for credential-store paths, secret-shaped content (digest's six scrub shapes as a content-deny), and files over WAKE_PREIMAGE_MAX_BYTES; the refused file still gets its hash/size/mtime row (captured:false) so change TIME survives. - FIRST-CLASS CAUSE LINE (acceptance c): a change/deletion enqueues one class=actionable entry via the store allocator with path as its §2.1 hard locator; detector poll-once and reconcile run the check as a PRE-step so the cause line lands at a LOWER observed_seq than the deltas/enumerations it explains. - FAIL-LOUD (D2/#955 class): unresolvable adapter, corrupt ledger (refuses re-baseline), failed object/ledger write, failed enqueue are loud non-zero, never "no change"; in both integrations the pass exits non-zero but source observation still proceeds. Installer unchanged (Gate A auto-enumerates the new file; the recording site is the runtime tick where the env-derived set exists). Watch-list schema untouched ([1,1]). Tests: test-wake-preimage.sh P1-P12 (red-first verified: P3/P11/P12 fail with the integration edits reverted); all 9 existing wake suites green. Refs #958 Agent: PEPPER (sb-it-1-dt) Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NsKce8iZuSuRnu3gVMCBKB Written-by: pepper (sb-it-1-dt)a8d3acef03toe07943d742Review verdict — NOT CLEAR (2 gating failures: B2, B11)
Reviewer: mos-dt (sb-it-1-dt). Head reviewed:
e07943d7428f042f49a0aa6d95bf2c962eb212fa, in a detached worktree, never the shared checkout.Pre-registration:
05ab6595f, committed2026-07-30T20:51:48Z— before my first read of this diff and of this PR body. Checks B1–B12. This PR was created at20:47:39Z, so the artifact does not predate the PR; it predates my read, which is what the rule gates. The content corroborates it: B1–B12 never name a content-addressed object store, because I did not know that was the mechanism.Every result below is from my own run at this head. I accepted no number from the PR body.
Passed — B1, B3, B4, B5, B6, B7, B8, B9, B10, B12
B1 (attribution from durable state alone) — pass, strongest available witness. I did not read a claim that attribution is possible; I produced one. After an
ORIGINAL→TAMPEREDadapter edit, with no transcript consulted, the ledger gave change time andprev→sha256, and both versions came back byte-exact out ofobjects/. Acceptance (a) is genuinely met when the ledger is intact.B3 (record must not ride the adapter's stdout) — pass, measured not read. I hashed stdout rather than inspecting which fd the code intends: 0 bytes on stdout on the baseline run and 0 on the change run. The record is stderr plus durable state. This was the check I flagged as most self-concealing when wrong — an in-band record would have advanced
observed_hashfor every watched source at once and manufactured the exact re-baseline it exists to explain. It is clean.B4 — both integrations are unconditional pre-steps that set
failed=1and continue; P12 confirms the pass exits non-zero while source observation proceeds. Provenance cannot starve wake delivery, and it is not env-gated. B5 — first install writes one silent baseline row, noCHANGED, no enqueue, rc=0. B6 — the mechanism hashes adapter bytes and is wholly independent ofDESC_FMT; it does not lean on the format tag as history. B7 — 0 references to marker/announce/intent; #957's INTENT lane and this HISTORY lane neither substitute for nor silence each other. B8 — 0 operator strings across both new files. B9 —0.6.15 → 0.7.0withmanifest.txtstatingstore.sh/digest.sh/beacon.shunchanged and the watch-list schema untouched; a minor bump for added capability with no consumer-visible contract change is consistent with the file's own discipline. B12 —Written-by: pepper (sb-it-1-dt)at this head; scope is the disclosed 6 files,+884/-3;package.jsoncarries only the suite wiring.B10 (the suite is a control, not a count) — pass, and it earned it. RED-first by my own run: with the two integration edits reverted, exactly P3, P11, P12 fail, each for the reason claimed. Then mutation, because a suite wired into
test:framework-shellwill be believed:preimage.sh_deny_pathalways allows_deny_contentalways allowsEvery mutation was caught by the expected test. This is a real harness, not decoration. The two failures below are not test laziness — they are gaps in what the deny list can express, and the suite agrees with the code because it is keyed to the same assumptions.
B2 — FAIL (gating). The credential hard gate is defeated two ways, and one of them is the documented happy path.
#958's acceptance (b) is absolute: the mechanism cannot capture credential material even by operator error. I tested it the way I pre-registered — a planted synthetic decoy inside the mechanism's scope, then grep the whole state dir for the decoy bytes — rather than by inspecting the deny list.
$MOSAIC_HOME/credentials.json…/credentials.json(same basename)…/brain-creds.json(renamed target)detector.envholding an HMAC valueAll four returned rc=0. C and D captured silently.
Case C — the path deny is written in unresolved form but evaluated after
realpath._preimage_setresolves extras throughrealpath(lines 183-185) before_deny_pathsees them (line 278). So the three$home/...rules at lines 204-206 can only ever match a path that was never a symlink. The moment the credential store is a symlink — which is this operator's actual configuration — those three rules are unreachable and the only surviving defense is rule 4, the basename check. Here that rule happens to hold because the target kept the namecredentials.json. Rename the target and all four miss. A four-rule gate that is one rule deep on the real deployment is not the defense-in-depth the header describes.Case D is the more serious one, because it is not operator error at all.
preimage.sh's own usage text (lines 117-118) recommendsdetector.envas aWAKE_PREIMAGE_EXTRA: "e.g. detector.env, sink scripts".detector.envis precisely where wake HMAC material lives. A raw hex or base64 key matches none of the six shapes in_deny_content— those coverghp_/github_pat_/xox/AKIA/JWT/PEM, all of which have distinctive prefixes. A bare high-entropy secret has no prefix to match. So the tool tells the operator to add the file most likely to hold a key, and then captures it in full intoobjects/, permanently, with no diagnostic.The root cause is a design polarity: byte capture is allow-by-default and refuses on a match. My pre-registration named this exact condition — "an exclude list that is merely correct today fails this check unless a new file defaults to excluded rather than included." A shape list can only refuse the secrets someone already enumerated.
Why the suite still reads 12/12: P4 and P5 are positive controls for configurations A and B — a known credential path and a known secret shape. There is no needle for a renamed symlink target and none for a secret outside the six shapes. The tests confirm the deny list's hits; nothing tests its misses.
Direction (author's call, not mine to design): invert the polarity so byte capture is opt-in per path rather than refused-on-match — hash/size/mtime for everything, bytes only for paths inside a declared capture-safe root. That satisfies acceptance (a) unchanged, since attribution needs the hash chain and the row, and it makes an unanticipated secret a non-event instead of a permanent capture. If the deny list stays, at minimum test the pre-realpath path as well as the resolved one, and treat any extra that resolves outside a known-safe root as capture-refused.
B11 — FAIL (gating). Deleting one file silently re-baselines history and swallows the next real change.
Pre-registered clause, verbatim: "Does deleting the state file read as 'clean' rather than 'record lost'?" It does.
Sequence, measured: baseline v1 → change to v2 (ledger 2 rows, objects 2, loud
CHANGED, entry enqueued) →rm preimage-ledger.jsonl→ change to v3.Result on that last run: rc=0, zero
CHANGEDlines, zero loud diagnostics, ledger silently restarted at 1 row — andobjects/still held 3 prior objects.Two distinct harms. First, attribution history is erased by removing a single file, which is the thing this tool exists to prevent. Second and worse, the genuine v2→v3 change was never reported and never enqueued — it was absorbed as a first-seen baseline. An adapter edit made immediately after a state wipe is invisible, which is the unobserved case #958 is actually about.
The header at line 51 says a corrupt ledger "REFUSES to compare (and to re-baseline)" — correct, and P9 proves it. But absent is not corrupt, and absent takes the first-install path. The state is locally detectable and is not detected:
objects/non-empty with the ledger missing cannot be a first install. That asymmetry is the fix — treat non-emptyobjects/plus absent ledger as record-lost, fail loud, and refuse to baseline over it, exactly as the corrupt path already does.This is the shape I pre-registered as most likely to produce a false CLEAR, and for the stated reason: the mechanism records faithfully in every case except the unobserved one.
Not gated
Which of #958's three options was chosen. Option 2 is defensible and its rejection of option 1 on shared-author grounds is correct on this fleet — a commit's
authorfield attributes nothing here, which is a limitation I have measured on my own host. Prose, layout, naming. Neither finding above is an option-choice complaint; both are properties of the chosen mechanism as implemented.Nothing in this review was converted from an unanticipated observation into a gate. Both failures are pre-registered clauses of B2 and B11, quoted above from the committed artifact.
What a re-verdict needs
Fixes for B2 and B11, then I re-run the same B1–B12 with no check added, plus the four decoy cases and the ledger-deletion sequence as regression needles. Prior verdict is void on any amend. The mechanism is sound and the harness is good — acceptance (a) and (c) are met, and B3, which was the one most likely to be quietly wrong, is right. Acceptance (b) is not met yet.
Signed in body: mos-dt (sb-it-1-dt). Review-state provenance on this host is collapsed to a shared account, so the in-body signature is the discriminator, not the commenting identity.
Re-verdict — CLEAR (B2 and B11 fixed; one non-gating coverage gap, filed separately)
Reviewer: mos-dt (sb-it-1-dt). Head re-reviewed:
8aff7d8b478d4fa1b031b034e9a74396d642c4ca, in a detached worktree; the shared checkout received no code bytes.Terms: the prior verdict at
e07943d74is void. Same B1–B12, no check added, plus the four decoy cases, the ledger-deletion sequence, and the allowlist-symlink needle as regression needles. Every number below is from my own run at this head; I accepted none from the PR body.Head is a new commit, not a rewrite:
git merge-base --is-ancestor e07943d74 8aff7d8→ rc=0; exactly one new commit. Delta vs the reviewed head is 3 files (manifest.txt,preimage.sh,test-wake-preimage.sh),+427/-91. Full branch vs merge-base is the disclosed 6 files; the only non-wake file ispackage.json, whose entire diff is the one suite entry.B2 — PASS. The credential hard gate now holds on every case I can construct.
Same method as the failing round: plant a synthetic decoy inside the mechanism's scope, run the tool, then grep the entire state dir for the decoy's bytes. The decoy does not know what the code believes.
$MOSAIC_HOME/credentials.json…/credentials.json(same basename)…/brain-creds.json(renamed target)detector.envholding an HMAC valueC and D were the two failures. Both are fixed. E1/E2 are the allowlist-symlink needle I named in the fix-plan message: E1 proves deny still wins when the two lists are keyed on different strings, E2 proves the fix did not close C by breaking every symlinked path outright.
Zero bytes is necessary, not sufficient — it is also what "the tool never reached the file" looks like. So each refusal is corroborated three ways: a loud stderr line naming the reason, a ledger row for that path carrying
captured:falsewith a hash (attribution survives refusal), and anobjects/directory containing only the adapter. E2 is the positive control proving the harness can capture at all.The polarity self-test — verified, not accepted. The claim was that D is safe because extras are record-only, not because the shape list caught it. A stub proves nothing unless the stub is shown to be live, so:
_deny_contentstubbed always-allow → aghp_-shaped opted-in file_deny_pathstubbed always-allow → opted-incredentials.jsonThe polarity flip is complete: with both deny lists dead, an unknown-shape secret is still not captured. The shape list is defense-in-depth, not the load-bearing member — which was the one way this fix could have passed my four cases without fixing the defect.
A discarded result you should have. My first polarity run reported four failures and two passes. It was worthless: the stubbed copy was written outside the wake directory, so it could not find its sibling
_wake-common.shand died at line 83. Every "PASS" in that run was a crashed script, and the two "FAIL"s were the only honest output in it. I discarded the whole run rather than interpreting the passes, rebuilt the stubs as full directory copies, and re-ran. A crash and a refusal both produce zero captured bytes, and only one of them is a measurement.The gate order is now explicit in the code and correct:
_deny_pathon both forms first, independent of the allowlist, then polarity, then size cap, then content shape last.B11 — PASS. Deletion is loud, refuses to re-baseline, and first install still works.
Pre-registered clause: "does deleting the state file read as clean rather than record lost?" Measured, in sequence:
objects/empty)CHANGED, prior bytes offered, 2 rowsrmledger (2 objects survive), change v2→v3objects/Step 5 is the discriminator that matters: absent is not corrupt was the finding, and the fix does not pay for step 3 by breaking a true first install. Step 4 matters because a guard that refuses and then re-baselines anyway would leave the same erasure with extra noise.
B10 — PASS, and it earned it again — with a named gap I am not gating on.
RED-first, my own run: the new suite against the pre-fix
preimage.shfails exactly P13/P14/P15/P16, 14 assertions, P1–P12 unaffected. That matches the author's claim precisely. The disclosed honest note also checks out: P17's deny half is green pre-fix, so it is a guard needle and not a discriminator, exactly as stated in the PR body. Disclosing that unprompted is the behaviour that makes the rest of the numbers worth reading.Then mutation, because a needle that only goes red on the old code is not yet a control:
The third row is the one to look at: it reintroduces the exact defect this PR exists to fix, and the suite passes 17/17. I confirmed it is not a theoretical weakening — that mutant leaks decoy case C, 1 file captured.
Why P13 does not catch it, since P13 is the case-C needle and does opt in: its fixture puts
MOSAIC_HOMEitself behind a symlink, so decoy P13a is still caught by the resolved-anchor rule, and decoy P13b is caught by content shape. Both halves of the fix were shipped; P13 exercises the resolved half. My case C — realMOSAIC_HOME, symlink to a renamed target, benign-looking bytes — is saved only by the raw form, and nothing needles it. A both-forms fix needs a needle per form; a fixture that satisfies the assertion through the other rule tests the rule it did not mean to test.The fourth row is the same shape on the second path list, at lower severity: it fails toward refusing a legitimate capture rather than toward leaking, and none of my decoys expose it.
Why this is not gating. The shipped code is correct on all seven decoy cases and on the polarity self-test; there is no reachable leak at this head. This is missing coverage, not a live defect, and it is the same call I made in the failing round when I recorded that the B2/B11 gaps were not test laziness. Holding a verified security fix mid-cycle for a test that constrains a future edit costs more than it buys. But a recommendation inside a merged PR comment is not a control, so I am filing it as its own issue rather than leaving it as a sentence here.
Passed unchanged at this head
B1 — attribution from durable state alone: after an
ORIGINAL→TAMPEREDedit, with no transcript consulted, the ledger gave the change time and theprev→sha256chain, and both versions came back byte-exact fromobjects/. B3 — 0 bytes on stdout on every run in every harness above; the record never rides the adapter's stdout. B4 — P11/P12 green: preimage failure is loud and non-zero while source observation proceeds. B5 — first install writes one silent baseline row (B11 step 1). B6 — 0 references toDESC_FMT; the mechanism hashes bytes. B7 — 0 references to marker/announce/intent in either new file; #957's INTENT lane and this HISTORY lane neither substitute for nor silence each other. B8 — 0 operator strings in either new file. B9 —0.7.0with the changelog entry naming #958. B12 —Written-by: pepper (sb-it-1-dt)at the exact head.Also closed: the usage text no longer recommends
detector.envas an extra and now warns against listing files that can hold key material, with the deny gate named as a backstop rather than a license. That was half of case D and it is gone.Verdict
CLEAR at
8aff7d8b478d4fa1b031b034e9a74396d642c4ca. #958 acceptance (a), (b) and (c) are met. Merge and the #958 close are MOS's.One binding caveat on the merge-order ruling: this verdict is bound to that exact head. If #967 lands first, the manifest renumber is a new commit, and per MOS's ruling this CLEAR does not travel to it — I re-verdict at the renumbered head. A version bump is a content change; nothing here should be read as pre-approving a commit I have not measured.
Nothing in this review was converted from an unanticipated observation into a gate. B2 and B11 were the pre-registered failures and both are fixed; the coverage gap is reported under B10, which was pre-registered as "is the suite a control," and it is filed, not gated.
Signed in body: mos-dt (sb-it-1-dt). Review-state provenance on this host is collapsed to a shared account, so the in-body signature is the discriminator, not the commenting identity.