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

Closes #953. GATE RECORD: review CLEAR at this exact head (author != reviewer, pre-registered diff-blind checks) + terminal-green CI at this exact head + queue guard clear. CI CAVEAT (#973): green on the wake suites is currently WEAKER THAN IT LOOKS, IN BOTH DIRECTIONS. grep error/spawn exit codes are read as absence across 257 assertion sites in six idiom forms; 36 inverted (&&-fail) sites — including 19 credential-security canaries — fail toward GREEN under load. These greens were obtained on solo reruns after load-correlated FALSE reds (2115/2116/2118; main itself was red). This merge's safety therefore rests on the CONTENT review, not on the green. Remediation charter fa551c2d0 is authored and in flight. Co-authored-by: mos-dt-0 <[email protected]>
2026-07-30 23:25:38 +00:00
parent 47f8689231
commit 76eef39a29
1 changed files with 13 additions and 0 deletions
@@ -488,6 +488,19 @@ _dlq_alarm_offhost() {
 # A dead-letter write failure is itself alarmed (both legs) but never aborts the
 # drain — the good entries MUST still deliver (availability is the whole point of
 # #920).
+#
+# RETENTION IS LOAD-BEARING (#953) — read BEFORE adding rotation/pruning/caps:
+# this ledger is append-only history AND the SOLE evidence base for
+# store.sh quarantine-audit's conviction predicate (#946): a false
+# consumed-hashes witness row is provable ONLY while its matching entry
+# survives HERE. Any rotation, pruning, or size cap — however locally correct
+# — silently converts provable rows into unprovable ones, and the audit's
+# clean sweep reads IDENTICALLY before and after the evidence disappears (no
+# signal at either end; the audit never guesses, by design). If retention
+# limits ever become genuinely necessary, they MUST ship with (a) a loud
+# signal at prune time naming what evidence is being given up, and (b) the
+# audit's residual-class reporting updated IN THE SAME CHANGE. Until then:
+# nothing prunes this file, and that is a recorded decision, not an omission.
 _quarantine_entry() {
  local line="$1" seq="$2" dlq="$STATE_DIR/dead-letter.jsonl"
  if [ ! -f "$dlq" ] || ! grep -qxF "$line" "$dlq" 2>/dev/null; then