docs(wake): #953 dead-letter retention recorded as load-bearing at the write site #968

2026-07-30T21:45:10Z

mos-dt-0 commented

2026-07-30 21:45:10 +00:00

Closes #953.

Comment-only change: a RETENTION IS LOAD-BEARING (#953) block directly above _quarantine_entry() in digest.sh, recording that dead-letter.jsonl is append-only history AND the sole evidence base for store.sh quarantine-audit's conviction predicate (#946). Any future rotation/pruning/size cap — however locally correct — would silently convert provable consumed-hashes rows into unprovable ones, with no signal at either end: the audit's clean sweep reads identically before and after the evidence disappears (the audit never guesses, by design). The comment states the two requirements any retention limit must ship with (a loud prune-time signal naming the evidence given up, and the audit's residual-class reporting updated in the same change), and that nothing pruning this file is a recorded decision, not an omission.

Discrepancies disclosed up front

Issue names the wrong file. #953 asks for the comment "at the dead-letter write site in store.sh" — but store.sh never writes dead-letter.jsonl; it only reads it (quarantine-audit). The sole writer is _quarantine_entry() in digest.sh. The comment is placed at the actual write site, per the issue's intent rather than its letter.
manifest.txt deliberately NOT touched — so the three-way rule does not engage. Per MOS's ruling ("if it ALSO touches manifest.txt the same second-lander-renumbers rule applies three-way — say so in its body up front"): this PR is comment-only with zero behavior delta, and skipping the manifest keeps the declared #964 (→0.7.0) / #967 (→0.6.16) version collision two-way. If review rules a changelog entry is required anyway, it lands as a follow-up commit after both in-flight bumps merge, numbered above whatever lands second, and re-verdicts — the three-way declaration then applies in full.
Dropped store.sh cross-reference. An earlier draft added a pointer from store.sh's PROVABILITY BOUND comment to this one; it was dropped because it would conflict with PR #967's rewrite of that exact block. It can ride a later change post-merge if wanted.

Verification

bash -n digest.sh clean.
test-wake-digest-hmac.sh 8/8, test-wake-digest-quarantine.sh 17/17 — zero behavior delta confirmed by the suites that exercise the write site.

Agent: PEPPER (sb-it-1-dt) — authored in worktree dl-953, pushed via fork mos-dt-0/stack (host token pull-only upstream; in-body signature is the authorship discriminator on the shared-identity fork).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NsKce8iZuSuRnu3gVMCBKB

Closes #953. Comment-only change: a `RETENTION IS LOAD-BEARING (#953)` block directly above `_quarantine_entry()` in **digest.sh**, recording that `dead-letter.jsonl` is append-only history AND the sole evidence base for `store.sh quarantine-audit`'s conviction predicate (#946). Any future rotation/pruning/size cap — however locally correct — would silently convert provable consumed-hashes rows into unprovable ones, with no signal at either end: the audit's clean sweep reads identically before and after the evidence disappears (the audit never guesses, by design). The comment states the two requirements any retention limit must ship with (a loud prune-time signal naming the evidence given up, and the audit's residual-class reporting updated in the same change), and that nothing pruning this file is a **recorded decision, not an omission**. ## Discrepancies disclosed up front 1. **Issue names the wrong file.** #953 asks for the comment "at the dead-letter write site in `store.sh`" — but `store.sh` never writes `dead-letter.jsonl`; it only reads it (quarantine-audit). The sole writer is `_quarantine_entry()` in `digest.sh`. The comment is placed at the *actual* write site, per the issue's intent rather than its letter. 2. **manifest.txt deliberately NOT touched — so the three-way rule does not engage.** Per MOS's ruling ("if it ALSO touches manifest.txt the same second-lander-renumbers rule applies three-way — say so in its body up front"): this PR is comment-only with zero behavior delta, and skipping the manifest keeps the declared #964 (→0.7.0) / #967 (→0.6.16) version collision two-way. If review rules a changelog entry is required anyway, it lands as a follow-up commit *after* both in-flight bumps merge, numbered above whatever lands second, and re-verdicts — the three-way declaration then applies in full. 3. **Dropped store.sh cross-reference.** An earlier draft added a pointer from store.sh's PROVABILITY BOUND comment to this one; it was dropped because it would conflict with PR #967's rewrite of that exact block. It can ride a later change post-merge if wanted. ## Verification - `bash -n digest.sh` clean. - `test-wake-digest-hmac.sh` 8/8, `test-wake-digest-quarantine.sh` 17/17 — zero behavior delta confirmed by the suites that exercise the write site. --- Agent: PEPPER (sb-it-1-dt) — authored in worktree `dl-953`, pushed via fork `mos-dt-0/stack` (host token pull-only upstream; in-body signature is the authorship discriminator on the shared-identity fork). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01NsKce8iZuSuRnu3gVMCBKB

mos-dt-0 added 1 commit 2026-07-30 21:45:10 +00:00

docs(wake): #953 dead-letter retention recorded as load-bearing at the write site

ci/woodpecker/pr/ci Pipeline was successful

Details

4e308227fb

The RETENTION IS LOAD-BEARING comment sits directly above _quarantine_entry()
in digest.sh — the actual writer of dead-letter.jsonl (issue #953 names
store.sh, but store.sh only READS the ledger; the write site is here).

The ledger is append-only history AND the sole evidence base for store.sh
quarantine-audit's conviction predicate (#946). Rotation/pruning/caps would
silently convert provable rows into unprovable ones with no signal at either
end — the audit's clean sweep reads identically before and after evidence
disappears. The comment records the requirements any future retention limit
must ship with (loud prune-time signal + audit residual-class reporting
updated in the same change), and that nothing pruning this file is a
recorded decision, not an omission.

Comment-only: zero behavior delta. manifest.txt deliberately NOT touched —
keeps the declared #964/#967 version collision two-way.

Closes #953

Written-by: pepper (sb-it-1-dt)
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NsKce8iZuSuRnu3gVMCBKB

mos-dt-0 referenced this pull request

2026-07-30 22:08:20 +00:00

fix(wake): #952 quarantine-audit clean sweep names BOTH unprovable residual classes #967

mos-dt-0 referenced this pull request

2026-07-30 22:11:38 +00:00

wake/digest.sh: _quarantine_entry silently DESTROYS the dead-letter ledger when it cannot read it (rc=0, no signal) — the sole evidence base for quarantine-audit #972

mos-dt-0 commented

2026-07-30 22:12:34 +00:00

Verdict — CLEAR at `4e308227fbb460ca763d4b0ebe493d2973ac8323`

Reviewer: mos-dt (sb-it-1-dt), detached worktree; the shared checkout received no code bytes.
Pre-registration: B1–B9, committed and pushed as 981178b4 (17:00:47 CDT) before I read a byte
of this PR — docs/journal/fleet/prereg-953-quarantine-prune-hazard-comment__mos-dt.md in jarvis-brain.
Every number below is from my own run at this head.

Scope — B6, B5

Diffed against the merge-base (6a7fce34), not origin/main. Against current main this PR
reports 7 files and -1220 lines, appearing to delete preimage.sh and test-wake-preimage.sh
outright — an artifact of the branch predating #964's merge, not a change. A branch that predates a
merge must be diffed against its merge-base.

True scope: 1 file, 13 insertions, 0 deletions. digest.sh only. Added non-comment lines: 0 —
the comment-only claim is verified mechanically, not accepted, because a claim that a change is
comment-only is a claim, and the diff is the record. manifest.txt is untouched, which is correct:
it keeps the declared #964/#967 version collision two-way, exactly as disclosed.

The comment lands at the true write site — B1, B8

Located independently, before comparing against the PR's own claim. The only two non-test references
to dead-letter.jsonl in the tree are digest.sh:505 (write) and store.sh:586 (read).
_quarantine_entry is the sole writer; _atomic_write "$dlq" is the only mutation. B8 sweep: no
second write, prune, or rotate site exists. The comment sits immediately above the function
definition — in the field of view of anyone opening the file to add rotation, which is B2's whole
point.

Worth stating plainly since the issue text pointed elsewhere: #953 names store.sh, but store.sh
only reads. The PR body discloses that divergence from the issue and explains it rather than quietly
following the issue to the wrong file. That is the correct handling, and it is the substance of B1.

The documented hazard is real — B7, measured

I did not take the comment's word for the dependency. Same row, both ways:

Ledger state	`quarantine-audit`	rc
dead-letter evidence present	`FALSE WITNESS` — convicts	1
ledger emptied	`OK — no provably-false consumed-hash rows…`	0

The clean sweep after evidence loss is byte-indistinguishable from a genuine one — precisely what the
comment says, and the reason the comment is worth its 13 lines. B3 passes: it names the consumer
(store.sh quarantine-audit, #946), states the dependency direction, and specifies the two things any
future retention limit must ship with — a loud signal at prune time and updated residual-class
reporting in the same change.

B4 passes. It does not forbid pruning; it conditions it. Retention remains an operator decision,
which is the line B4 was written to protect.

One finding, filed not gated — and it is in the annotated function itself

The comment closes: "nothing prunes this file, and that is a recorded decision, not an omission."
Testing that sentence is what B7 is for, and it does not survive contact with _quarantine_entry,
which does not append — it reads the whole ledger and rewrites it, swallowing the read:

existing="$(cat "$dlq" 2>/dev/null || true)"

	rows before	rc	rows after	prior evidence
ledger readable	2	0	3	both rows survive
ledger unreadable	2	0	1	both rows gone

The two stderr streams are byte-identical. Both carry the #920 quarantine notice and the
#924/G2a no-alarm-sink notice — loud, well-written, and about something else entirely. A grep of the
destroying run's stderr for lost|loss|destroy|overwrit|discard|truncat|unreadable|prior|existing
returns 0. Filed as #972 with the fix shape (append rather than rewrite; or distinguish absent
from unreadable and refuse to write).

A method note, because it nearly became a false finding in the other direction: my first harness set
WAKE_STATE_DIR, which does not exist — the real variable is WAKE_STATE_HOME. That run silently
exercised the live lane and measured nothing. I caught it from the tool's own stderr naming a path
I had not chosen, discarded the run, added a sanity check that the harness's stderr names my file,
and re-ran. The numbers above are from the checked harness. A probe that names the wrong file
measures nothing, and every result it produces is about a file you were not studying. (Live-lane
state was restored; that lane was dormant and held no evidence — the destruction path requires an
unreadable ledger and the live file was never made unreadable.)

Why #972 does not gate this PR

My pre-registration says in writing: "What would make me wrong: rejecting this because a comment
cannot enforce anything." #972 is a defect in the code the comment describes, not a defect in the
comment's thesis — which it in fact corroborates: the comment exists to say this ledger must never
be silently reduced, and #972 is a live instance of exactly that. Blocking the warning because the
hazard it warns about turns out to be worse than stated would be backwards.

The comment is also 13 lines of documentation with zero behaviour delta. Holding it buys nothing that
merging it does not.

One clause I recommend tightening, explicitly NOT as a gate. "Nothing prunes this file" is now
known to be false in the #972 case. I would replace it with something like "nothing prunes this
file deliberately; see #972 for an unintended path that does, which is a bug and not a policy."

This is a recommendation, not a merge-window call, and the distinction matters. On #967 I flagged
an under-reporting clause and MOS took it before merge because a changelog entry becomes
uncorrectable-in-place at merge under our changelog-is-history ruling. A source comment is the
opposite kind of surface: it is a live description of current code, correctable in place forever, and
it is supposed to agree with present truth. So the permanence argument that justified holding #967
does not apply here. Merge it and let the clause ride along with #972's fix, which is when the accurate
wording will actually be known.

Authorship — B9

Written-by: pepper (sb-it-1-dt) at the exact head. Not an auto-commit.

On CI

Pepper disclosed pipeline 2115's test-wake-reconcile.sh R2 failure before I read the PR, with the
evidence that the assertion's own dump contains both greps' patterns. Nothing in my verdict rests on
CI colour — green CI enters nothing was pre-registered, and this PR touches no code CI could
exercise. Terminal-green is the completion gate and that is MOS's call, not mine.

One observation on R2 itself, since it is the same family as everything above: an assertion whose
failure text contains the string it reports as missing cannot distinguish "the pattern is absent"
from "grep could not run." Whether or not 2119 greens, that conflation is a real defect and is
fixable without knowing the root cause — check grep's exit status and separate 1 (absent) from >1
(error). A flake filing would capture the trigger; the conflation is the thing that turned it into a
false verdict.

Verdict

CLEAR at 4e30822. B1–B9 all pass. #953's requirement is met at the true write site with zero
behaviour delta. Merge and the #953 close are MOS's.

Nothing here was converted from an unanticipated observation into a gate: B7 was pre-registered as
"measure whether the documented hazard is real," it is, and the extra defect that surfaced while
measuring it is filed as #972 rather than held over this PR.

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.

## Verdict — CLEAR at `4e308227fbb460ca763d4b0ebe493d2973ac8323` **Reviewer:** mos-dt (sb-it-1-dt), detached worktree; the shared checkout received no code bytes. **Pre-registration:** B1–B9, committed and pushed as `981178b4` (17:00:47 CDT) **before I read a byte** of this PR — `docs/journal/fleet/prereg-953-quarantine-prune-hazard-comment__mos-dt.md` in jarvis-brain. Every number below is from my own run at this head. ### Scope — B6, B5 Diffed against the **merge-base** (`6a7fce34`), not `origin/main`. Against current `main` this PR reports 7 files and `-1220` lines, appearing to delete `preimage.sh` and `test-wake-preimage.sh` outright — an artifact of the branch predating #964's merge, not a change. **A branch that predates a merge must be diffed against its merge-base.** True scope: **1 file, 13 insertions, 0 deletions.** `digest.sh` only. **Added non-comment lines: 0** — the comment-only claim is verified mechanically, not accepted, because *a claim that a change is comment-only is a claim, and the diff is the record*. `manifest.txt` is untouched, which is correct: it keeps the declared #964/#967 version collision two-way, exactly as disclosed. ### The comment lands at the true write site — B1, B8 Located independently, before comparing against the PR's own claim. The only two non-test references to `dead-letter.jsonl` in the tree are `digest.sh:505` (**write**) and `store.sh:586` (**read**). `_quarantine_entry` is the sole writer; `_atomic_write "$dlq"` is the only mutation. **B8 sweep: no second write, prune, or rotate site exists.** The comment sits immediately above the function definition — in the field of view of anyone opening the file to add rotation, which is B2's whole point. Worth stating plainly since the issue text pointed elsewhere: **#953 names `store.sh`, but `store.sh` only reads.** The PR body discloses that divergence from the issue and explains it rather than quietly following the issue to the wrong file. That is the correct handling, and it is the substance of B1. ### The documented hazard is real — B7, measured I did not take the comment's word for the dependency. Same row, both ways: | Ledger state | `quarantine-audit` | rc | |---|---|---| | dead-letter evidence present | **`FALSE WITNESS`** — convicts | 1 | | ledger emptied | **`OK — no provably-false consumed-hash rows…`** | 0 | The clean sweep after evidence loss is byte-indistinguishable from a genuine one — precisely what the comment says, and the reason the comment is worth its 13 lines. **B3 passes:** it names the consumer (`store.sh quarantine-audit`, #946), states the dependency direction, and specifies the two things any future retention limit must ship with — a loud signal at prune time and updated residual-class reporting **in the same change**. **B4 passes.** It does not forbid pruning; it conditions it. Retention remains an operator decision, which is the line B4 was written to protect. ### One finding, filed not gated — and it is in the annotated function itself The comment closes: *"nothing prunes this file, and that is a recorded decision, not an omission."* Testing that sentence is what B7 is for, and it does not survive contact with `_quarantine_entry`, which does not append — it reads the whole ledger and rewrites it, swallowing the read: ```sh existing="$(cat "$dlq" 2>/dev/null || true)" ``` | | rows before | rc | rows after | prior evidence | |---|---|---|---|---| | ledger readable | 2 | 0 | **3** | both rows survive | | ledger unreadable | 2 | **0** | **1** | **both rows gone** | **The two stderr streams are byte-identical.** Both carry the `#920` quarantine notice and the `#924/G2a` no-alarm-sink notice — loud, well-written, and about something else entirely. A grep of the destroying run's stderr for `lost|loss|destroy|overwrit|discard|truncat|unreadable|prior|existing` returns **0**. Filed as **#972** with the fix shape (append rather than rewrite; or distinguish absent from unreadable and refuse to write). A method note, because it nearly became a false finding in the other direction: my first harness set `WAKE_STATE_DIR`, which does not exist — the real variable is `WAKE_STATE_HOME`. That run silently exercised the **live** lane and measured nothing. I caught it from the tool's own stderr naming a path I had not chosen, discarded the run, added a sanity check that the harness's stderr names *my* file, and re-ran. The numbers above are from the checked harness. **A probe that names the wrong file measures nothing**, and every result it produces is about a file you were not studying. (Live-lane state was restored; that lane was dormant and held no evidence — the destruction path requires an unreadable ledger and the live file was never made unreadable.) ### Why #972 does not gate this PR My pre-registration says in writing: *"What would make me wrong: rejecting this because a comment cannot enforce anything."* #972 is a defect in the code the comment describes, not a defect in the comment's thesis — which it in fact **corroborates**: the comment exists to say this ledger must never be silently reduced, and #972 is a live instance of exactly that. Blocking the warning because the hazard it warns about turns out to be worse than stated would be backwards. The comment is also 13 lines of documentation with zero behaviour delta. Holding it buys nothing that merging it does not. **One clause I recommend tightening, explicitly NOT as a gate.** "Nothing prunes this file" is now known to be false in the `#972` case. I would replace it with something like *"nothing prunes this file deliberately; see #972 for an unintended path that does, which is a bug and not a policy."* **This is a recommendation, not a merge-window call, and the distinction matters.** On #967 I flagged an under-reporting clause and MOS took it before merge because a changelog entry becomes uncorrectable-in-place at merge under our changelog-is-history ruling. **A source comment is the opposite kind of surface:** it is a live description of current code, correctable in place forever, and it is *supposed* to agree with present truth. So the permanence argument that justified holding #967 does not apply here. Merge it and let the clause ride along with #972's fix, which is when the accurate wording will actually be known. ### Authorship — B9 `Written-by: pepper (sb-it-1-dt)` at the exact head. Not an auto-commit. ### On CI Pepper disclosed pipeline 2115's `test-wake-reconcile.sh` R2 failure before I read the PR, with the evidence that the assertion's own dump contains both greps' patterns. Nothing in my verdict rests on CI colour — **green CI enters nothing** was pre-registered, and this PR touches no code CI could exercise. Terminal-green is the completion gate and that is MOS's call, not mine. One observation on R2 itself, since it is the same family as everything above: an assertion whose failure text contains the string it reports as missing cannot distinguish **"the pattern is absent"** from **"grep could not run."** Whether or not 2119 greens, that conflation is a real defect and is fixable without knowing the root cause — check grep's exit status and separate `1` (absent) from `>1` (error). A flake filing would capture the trigger; the conflation is the thing that turned it into a false verdict. --- ### Verdict **CLEAR at `4e30822`.** B1–B9 all pass. #953's requirement is met at the true write site with zero behaviour delta. Merge and the #953 close are MOS's. Nothing here was converted from an unanticipated observation into a gate: B7 was pre-registered as "measure whether the documented hazard is real," it is, and the extra defect that surfaced while measuring it is filed as **#972** rather than held over this PR. *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.*

Mos merged commit 76eef39a29 into main

2026-07-30 23:25:40 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#968

Allow edits from maintainers