bridgebench 3.1.0-alpha.0 → 3.1.0-alpha.2

package/tasks/debugging/public/regression-multipart-filesize-cap.yaml

@@ -0,0 +1,135 @@
+id: regression-multipart-filesize-cap
+version: 1.0.0
+category: debugging
+cluster: regression-introduction
+difficulty: expert
+title: Bisecting a Week of Commits for Why Mid-Size Uploads Started Failing
+summary: >-
+  Since midweek, assetsvc rejects uploads between 1 MB and the old 10 MB ceiling; small avatars still
+  work. A CI matrix that ran the same suite on every commit, seven commit diffs, a multer changelog
+  note, and the incident report are provided. A scary handler rewrite, a multer major-version bump,
+  and an error-status remap all look suspicious. Identify the exact commit that introduced the
+  regression, explain the defect, rule out the decoy commits, and give the fix that actually targets it.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (ci-matrix, c3-diff, c4-diff, c5-diff,
+  c6-diff, c7-note, incident). Cite the artifact id(s) for every claim.
+
+  1. CULPRIT COMMIT. Which commit introduced the regression? Cite the exact ci-matrix transition (the
+     first commit where the size canary flips PASS -> FAIL) and the diff that contains the defect.
+  2. THE DEFECT. State precisely what the culprit changed and why it lets 512 KB uploads through but
+     rejects 2 MB and 9 MB uploads. Cite the diff.
+  3. RULE OUT THE MULTER BUMP (c7). Explain why bumping multer 1.4.5 -> 2.0.1 is not the origin of the
+     regression, citing ci-matrix and c7-note.
+  4. RULE OUT THE 413 REMAP (c6). Explain why the commit that changed the rejection status from 400 to
+     413 is not the origin, even though the incident report quotes a 413. Cite ci-matrix and c6-diff.
+  5. RULE OUT THE HANDLER REWRITE (c3). Explain why the streaming-handler rewrite is not the culprit.
+  6. ADEQUATE FIX. Give the minimal change that removes the regression, and state why reverting c7 or
+     c6 would NOT fix it.
+
+  Exactly one resolution is defensible per deliverable; it is fully determined by the artifacts.
+artifacts:
+  - id: ci-matrix
+    type: table
+    label: CI results per commit (the same suite runs pre-merge on EVERY commit)
+    content: |
+      This suite runs on every commit before merge. Each cell is that test's own PASS/FAIL on that
+      commit. upload-2mb is the size-regression canary; reject-11mb asserts an over-limit file is
+      correctly rejected (so PASS = "was rejected as expected").
+
+      commit  date        title                                   upload-512kb  upload-2mb  upload-9mb  reject-11mb
+      c1      Mon 09:10   baseline                                PASS          PASS        PASS        PASS
+      c2      Mon 14:22   refactor: extract UploadModule          PASS          PASS        PASS        PASS
+      c3      Tue 09:05   rewrite: streaming upload handler       PASS          PASS        PASS        PASS
+      c4      Tue 11:40   chore: centralize upload constants      PASS          PASS        PASS        PASS
+      c5      Tue 15:12   feat: enforce per-file size limit       PASS          FAIL        FAIL        PASS
+      c6      Wed 10:30   map file-size rejection 400 -> 413      PASS          FAIL        FAIL        PASS
+      c7      Wed 16:45   chore: bump multer 1.4.5 -> 2.0.1       PASS          FAIL        FAIL        PASS
+      c8      Thu 08:20   feat: add structured request logging    PASS          FAIL        FAIL        PASS
+
+      The FIRST commit where upload-2mb and upload-9mb fail is c5. They passed on c4 and every prior
+      commit. No commit after c5 changes any cell in the upload-2mb / upload-9mb columns.
+  - id: c3-diff
+    type: diff
+    label: 'c3 — "rewrite: streaming upload handler" (large diff)'
+    content: |
+      # Replaces the buffered handler with a streaming one. ~180 lines changed. No size limit is set
+      # or removed here; multer is still constructed with no `limits` option after this commit.
+        -export function handleUpload(req, res) {
+        -  const buf = Buffer.concat(req.chunks);
+        -  return store.putBuffered(buf, req.file.originalname);
+        -}
+        +export function handleUpload(req, res) {
+        +  return req.file.stream.pipe(store.putStream(req.file.originalname))
+        +    .on('finish', () => res.status(201).json({ ok: true }))
+        +    .on('error', (e) => next(e));
+        +}
+      # multer construction after c3 (unchanged by this commit):
+        const upload = multer({ storage });   // no `limits` key -> multer default fileSize = unlimited
+  - id: c4-diff
+    type: diff
+    label: 'c4 — "chore: centralize upload constants"'
+    content: |
+      # Adds config/upload.ts and points the handler at it. Moves only MIME allow-list and the upload
+      # directory. It does NOT define or apply any size limit.
+        +// config/upload.ts
+        +export const UPLOAD = {
+        +  allowedMime: ['image/png', 'image/jpeg', 'application/pdf'],
+        +  uploadDir: '/var/data/uploads',
+        +};
+        -const allowed = ['image/png', 'image/jpeg', 'application/pdf'];
+        +import { UPLOAD } from '../config/upload';
+        -if (!allowed.includes(req.file.mimetype)) return res.status(415).end();
+        +if (!UPLOAD.allowedMime.includes(req.file.mimetype)) return res.status(415).end();
+      # multer construction after c4 (still unchanged): const upload = multer({ storage });
+  - id: c5-diff
+    type: diff
+    label: 'c5 — "feat: enforce per-file size limit"'
+    content: |
+      # Adds a multer fileSize limit. The intent (per the commit body) was a 10 MiB per-file cap to
+      # reject abuse, matching the historical body ceiling.
+        -const upload = multer({ storage });
+        +const upload = multer({
+        +  storage,
+        +  limits: {
+        +    fileSize: 1024 * 1024,   // intended 10 * 1024 * 1024 (10 MiB); the "10 *" was dropped
+        +  },
+        +});
+      # multer emits a LIMIT_FILE_SIZE error for any file exceeding limits.fileSize. Before c5 no
+      # fileSize limit existed (see c3-diff / c4-diff: multer had no `limits` key), so uploads up to
+      # the body ceiling (10 MiB) were accepted.
+  - id: c6-diff
+    type: diff
+    label: c6 — "map file-size rejection 400 -> 413"
+    content: |
+      # Changes ONLY the HTTP status returned when multer raises LIMIT_FILE_SIZE. It does not change
+      # which uploads are rejected — only the status code of an already-rejected upload.
+        function onUploadError(err, req, res, next) {
+          if (err.code === 'LIMIT_FILE_SIZE') {
+        -   return res.status(400).json({ error: 'file too large' });
+        +   return res.status(413).json({ error: 'file too large' });
+          }
+          return next(err);
+        }
+  - id: c7-note
+    type: note
+    label: c7 — "bump multer 1.4.5 -> 2.0.1" (changelog excerpt + behavior)
+    content: |
+      multer 2.0.1 changelog (relevant lines):
+        - Security: fix ReDoS in the multipart header parser.
+        - Internal: switch to busboy 1.x.
+        - No change to default limits. When `limits.fileSize` is UNSET, the default remains unlimited;
+          when set, the existing LIMIT_FILE_SIZE behavior is preserved byte-for-byte.
+      After c7, the multer construction is still the c5 code: limits.fileSize = 1024 * 1024. The bump
+      neither introduced nor altered the fileSize limit. ci-matrix shows upload-2mb already failing at
+      c5 and c6, before c7.
+  - id: incident
+    type: note
+    label: incident report INC-552 (as filed by support)
+    content: |
+      Users report: "uploading my 3 MB portfolio PDF fails with HTTP 413 Payload Too Large; my small
+      profile picture (about 400 KB) still uploads fine." First reports arrived Wednesday afternoon.
+      Support noted the 413 status and initially suspected "the multer upgrade that went out
+      Wednesday." Reproduced in staging: a 2 MB file returns 413; a 512 KB file returns 201. An 11 MB
+      file is also rejected (expected). Note: the visible 413 status began Wednesday, but staging
+      builds pinned to Tuesday-evening commits reject the same 2 MB file with a 400.
+tags: [debugging, regression-introduction, multer, uploads, bisect]

package/tasks/debugging/public/regression-pagination-tiebreak.yaml

@@ -0,0 +1,112 @@
+id: regression-pagination-tiebreak
+version: 1.0.0
+category: debugging
+cluster: regression-introduction
+difficulty: expert
+title: Bisecting Why a Feed Started Dropping and Duplicating Items Across Pages
+summary: >-
+  feedsvc's cursor pagination began skipping some items and repeating others across page boundaries.
+  A CI matrix that ran a determinism test on every commit, six commit diffs, a data-distribution
+  note, and the bug report are provided. An ORM major bump, a new index, and a page-size change all
+  look like plausible culprits. Identify the exact commit that introduced the regression, explain the
+  keyset mechanism that breaks, rule out the decoys, and give the fix that restores a total order.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (ci-matrix, c2-diff, c3-diff, c4-diff,
+  c5-diff, data-note, bug-report). Cite the artifact id(s) for every claim.
+
+  1. CULPRIT COMMIT. Which commit introduced the regression? Cite the exact ci-matrix transition (the
+     first commit where paginate-no-dupes flips PASS -> FAIL) and the diff that contains the defect.
+  2. THE MECHANISM. Explain precisely why the change causes items to be skipped and duplicated across
+     pages. Cite the diff and data-note. Name the specific condition in the data that triggers it.
+  3. RULE OUT THE ORM BUMP. Explain why the ORM major-version bump is not the origin. Cite ci-matrix.
+  4. RULE OUT THE INDEX AND PAGE-SIZE CHANGES. Explain why adding an index on created_at and raising
+     the page size do not cause (or fix) the skip/duplicate behavior. Cite ci-matrix and the diffs.
+  5. ADEQUATE FIX. Give the minimal change that removes the regression and state the invariant keyset
+     pagination requires. Explain why adding the index or reverting the ORM bump would not fix it.
+  6. BLAST RADIUS. State exactly which page requests can skip or duplicate items and which are
+     unaffected, tying it to data-note.
+
+  Exactly one resolution is defensible per deliverable; it is fully determined by the artifacts.
+artifacts:
+  - id: ci-matrix
+    type: table
+    label: CI results per commit (the same suite runs pre-merge on EVERY commit)
+    content: |
+      This suite runs on every commit before merge. paginate-no-dupes walks all pages over a fixture
+      containing duplicate created_at values and asserts every item appears exactly once (no skips,
+      no duplicates). paginate-count asserts the total item count returned equals the row count.
+
+      commit  date        title                                    paginate-no-dupes  paginate-count
+      c1      Mon 10:00   baseline keyset pagination               PASS               PASS
+      c2      Mon 16:20   chore: bump feed-orm 4.x -> 5.0          PASS               PASS
+      c3      Tue 11:15   perf: add index on events(created_at)    PASS               PASS
+      c4      Tue 15:40   simplify: drop redundant ORDER BY column PASS -> FAIL       PASS
+      c5      Wed 09:30   tune: raise page size 20 -> 50           FAIL               PASS
+      c6      Wed 14:10   docs: update pagination README           FAIL               PASS
+
+      The FIRST commit where paginate-no-dupes fails is c4. It passed on c3 and every prior commit.
+      paginate-count stays PASS throughout (the total number of returned rows is unchanged; only their
+      per-page assignment is wrong), which is why the bug is easy to miss.
+  - id: c2-diff
+    type: diff
+    label: 'c2 — "chore: bump feed-orm 4.x -> 5.0"'
+    content: |
+      # Major version bump of the query builder. The generated SQL for the feed query is byte-identical
+      # before and after (verified by the ORM's SQL-snapshot test, which did not change).
+        - "feed-orm": "4.7.2"
+        + "feed-orm": "5.0.0"
+      # feed-orm 5.0 notes: new typings, no change to ORDER BY / LIMIT emission. The pagination query
+      # after c2 still emits: ORDER BY created_at DESC, id DESC  with  WHERE (created_at, id) < ($1,$2).
+  - id: c3-diff
+    type: diff
+    label: 'c3 — "perf: add index on events(created_at)"'
+    content: |
+      # Adds a non-unique btree index to speed the scan. Indexes affect access path and speed, not the
+      # result-set ordering guarantees: without an ORDER BY tiebreaker, rows with equal created_at have
+      # no defined relative order regardless of which index is used.
+        + CREATE INDEX events_created_at_idx ON events (created_at);
+      # The query after c3 is unchanged: ORDER BY created_at DESC, id DESC  WHERE (created_at, id) < ($1,$2).
+  - id: c4-diff
+    type: diff
+    label: 'c4 — "simplify: drop redundant ORDER BY column"'
+    content: |
+      # Author's rationale in the commit body: "created_at is effectively unique, so the trailing id in
+      # the ORDER BY and the composite cursor are redundant; simplify to a single sort key."
+        function pageQuery(cursor, pageSize) {
+          return db.select('*').from('events')
+        -   .whereRaw('(created_at, id) < (?, ?)', [cursor.createdAt, cursor.id])
+        -   .orderBy([{ col: 'created_at', dir: 'desc' }, { col: 'id', dir: 'desc' }])
+        +   .where('created_at', '<', cursor.createdAt)
+        +   .orderBy('created_at', 'desc')
+            .limit(pageSize);
+        }
+        // cursor for the next page is taken from the LAST row of the current page:
+        // { createdAt: lastRow.created_at, id: lastRow.id }   (id is now unused by pageQuery)
+  - id: c5-diff
+    type: diff
+    label: 'c5 — "tune: raise page size 20 -> 50"'
+    content: |
+        - const PAGE_SIZE = 20;
+        + const PAGE_SIZE = 50;
+      # Changes how many rows each page returns. Does not touch ORDER BY, the WHERE cursor predicate,
+      # or the tiebreaker.
+  - id: data-note
+    type: note
+    label: events table — column and data distribution (verified)
+    content: |
+      events(id uuid PRIMARY KEY, created_at timestamptz, ...). created_at is NOT unique: bulk imports
+      insert many rows in one batch that share an identical created_at value to the millisecond. In the
+      current table ~4% of rows share their created_at with at least one other row; the largest such
+      group is 37 rows with the same created_at. id is unique (primary key). There is no unique
+      constraint or index on created_at alone. These are the complete uniqueness facts for the table.
+  - id: bug-report
+    type: note
+    label: bug report FEED-311 (as filed)
+    content: |
+      Reporter: "Scrolling the activity feed, some posts show up on two pages in a row, and a few
+      never appear at all. It seems to happen around big batch-imported blocks." QA reproduced on a
+      fixture with duplicate timestamps: paging with size 20 skips 6 items and repeats 5 across the
+      first three page boundaries. Reporter initially suspected "the ORM upgrade from Monday." The
+      total number of distinct items eventually reachable by fetching enough pages is correct; the
+      problem is which page each item lands on.
+tags: [debugging, regression-introduction, pagination, keyset, ordering]

package/tasks/debugging/public/state-corruption-index-ghost.yaml

@@ -0,0 +1,160 @@
+id: state-corruption-index-ghost
+version: 1.0.0
+category: debugging
+cluster: state-corruption
+difficulty: expert
+title: Notevault Search Returns a Ghost Note That 404s When Opened
+summary: A note-taking app's search returns a note id that no longer exists, so opening the result 404s. Search looks guilty because it surfaces the bad id, the loader looks guilty because it 404s, and a full rebuild makes the problem vanish. Find the one writer whose ordering first leaves an orphaned index posting, separate it from the readers that only observe the corrupt index, and state the adequate versus the shallow fix.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (index-invariant, store-code,
+  writers-code, delete-order-diff, event-trace, bug-report). Cite the artifact id(s) for
+  every claim. Use this vocabulary for verdicts: root-cause, red-herring, adequate-fix,
+  shallow-fix.
+
+  In the "notevault" service, searching for the term "mars" returns note n-7, but opening
+  n-7 returns 404. Do not stop at where the ghost is observed; trace to the writer where
+  the index invariant is FIRST violated.
+
+  1. State the index invariant precisely, and list the COMPLETE set of functions permitted
+     to write the in-memory inverted index, per the artifacts.
+
+  2. ROOT CAUSE. Name the single function whose execution first leaves a posting in the
+     index that points at a note absent from the store, and cite the exact ordering of
+     operations and the trace point where the orphan is created. Explain why that ordering
+     violates the invariant.
+
+  3. RED HERRINGS. Classify search() and the note loader. For each, explain whether it
+     corrupts the index or only reads / reports state that was already corrupt.
+
+  4. Explain whether indexNote's remove-then-add sequence on an update is the defect or is
+     invariant-preserving, and justify with the trace.
+
+  5. FIX ADEQUACY. Two fixes are on the table: (a) run rebuildIndex on a timer to
+     rebuild the whole index from the store periodically; (b) restore the ordering so the
+     note's terms are read and its postings removed BEFORE the note is deleted from the
+     store. Classify each as adequate-fix or shallow-fix and justify which durably restores
+     the invariant.
+
+  6. BLAST RADIUS. State exactly which notes leave ghost postings and which operations are
+     unaffected, tying it to delete-order-diff.
+artifacts:
+  - id: index-invariant
+    type: spec
+    label: notevault index invariant and the complete writer set
+    content: |
+      notevault search index model (authoritative).
+
+      INVARIANT (I1): the in-memory inverted index must stay consistent with the note
+      store. Formally: for every term t and every note id n in index.postings[t], the store
+      must contain a live note n AND that note's terms must include t. Equivalently, a
+      posting may exist only while its note exists and still contains the term. When a note
+      is deleted, all of its postings must be gone before or atomically with the store
+      deletion; a posting outliving its note is a ghost and violates I1.
+
+      COMPLETE WRITER SET: exactly three functions may mutate index.postings — indexNote
+      (on create/update), removeFromIndex (on delete), and rebuildIndex (full rebuild).
+      There are no other index mutators; nothing writes index.postings directly. This is
+      the complete and exhaustive list.
+
+      READERS (never mutate the index): search() reads index.postings to resolve a query.
+      The note loader reads the store by id. Neither writes the index.
+  - id: store-code
+    type: code
+    label: note store and index structures
+    content: |
+      // notevault/store.ts
+      // In-memory note store: id -> note. A note carries its tokenized terms.
+      //   type Note = { id: string; title: string; body: string; terms: string[] }
+      const notes = new Map<string, Note>();
+
+      export const store = {
+        get: (id: string): Note | undefined => notes.get(id),
+        put: (n: Note) => notes.set(n.id, n),
+        delete: (id: string) => notes.delete(id),
+        has: (id: string) => notes.has(id),
+      };
+
+      // Inverted index: term -> set of note ids that contain it.
+      export const index = { postings: new Map<string, Set<string>>() };
+  - id: writers-code
+    type: code
+    label: the three index writers and the delete path
+    content: |
+      // notevault/indexing.ts — the only functions that mutate index.postings.
+
+      export function indexNote(prev: Note | undefined, next: Note) {
+        // create or update: drop the old terms' postings (using prev, which still exists),
+        // then add the new terms' postings. On create, prev is undefined and only adds run.
+        for (const t of prev?.terms ?? []) index.postings.get(t)?.delete(next.id);
+        for (const t of next.terms) {
+          (index.postings.get(t) ?? index.postings.set(t, new Set()).get(t)!).add(next.id);
+        }
+      }
+
+      export function removeFromIndex(id: string) {
+        // reads the note to learn which posting lists to clean, then removes id from each.
+        const note = store.get(id);
+        for (const t of note?.terms ?? []) index.postings.get(t)?.delete(id);
+      }
+
+      export function rebuildIndex() {
+        // full rebuild from the store; O(all notes). Restores I1 for whatever is in the store now.
+        index.postings.clear();
+        for (const n of store.allLive()) for (const t of n.terms) {
+          (index.postings.get(t) ?? index.postings.set(t, new Set()).get(t)!).add(n.id);
+        }
+      }
+
+      export async function deleteNote(id: string) {
+        await store.delete(id);        // (see delete-order-diff for how this line moved)
+        removeFromIndex(id);
+      }
+  - id: delete-order-diff
+    type: diff
+    label: change to deleteNote shipped on 2026-07-02
+    content: |
+      # commit "make deletes durable by removing from the store first"
+      # notevault/indexing.ts  deleteNote
+
+        export async function deleteNote(id: string) {
+      -   // v2: clean the index while the note still exists, THEN delete it.
+      -   removeFromIndex(id);
+      -   await store.delete(id);
+      +   // v3: delete from the durable store first, then clean the index.
+      +   await store.delete(id);
+      +   removeFromIndex(id);
+        }
+      # removeFromIndex was left unchanged. It still calls store.get(id) to learn the note's
+      # terms — but after v3, by the time it runs the note is already gone from the store.
+  - id: event-trace
+    type: log
+    label: lifecycle trace for note n-7 (term "mars")
+    content: |
+      # index.postings["mars"] shown after each step.
+      t0 create n-7 terms=[mars,rover]  indexNote(undefined, n-7)   postings[mars]={n-7}      # I1 holds
+      t1 search "mars"                   -> returns [n-7]; store.get(n-7)=present -> opens OK   # I1 holds
+      t2 deleteNote(n-7)  step A: store.delete(n-7)                 store has no n-7
+      t2 deleteNote(n-7)  step B: removeFromIndex(n-7): store.get(n-7)=undefined -> terms=[] -> loops 0x
+                                   postings[mars]={n-7}  # ORPHAN CREATED: posting survives its note -> I1 FIRST BROKEN
+      t3 search "mars"                   -> returns [n-7]  (reads the orphaned posting)
+      t3 loader open n-7                 -> store.has(n-7)=false -> 404  (note is correctly gone)
+      t4 rebuildIndex()                  postings[mars]={}          # rebuild drops the orphan; masks it until the next delete
+  - id: bug-report
+    type: note
+    label: bug report and triage guesses
+    content: |
+      Report: search result "mars" -> n-7 opens to a 404. Triage guesses (record only):
+      - "search() is returning stale results; fix the search reader." — search() only reads
+        index.postings (index-invariant READERS); it faithfully returns what the index holds,
+        which is an orphaned posting. It does not create the orphan.
+      - "the loader is buggy for returning 404 on a real note." — the loader is correct: the
+        store genuinely no longer has n-7 (event-trace t3), so 404 is the right response.
+      - "indexNote's remove-then-add on updates is dropping/duplicating postings." — on an
+        update indexNote reads prev (which still exists) to remove old postings, so it is
+        consistent; the ghost arises only on the delete path.
+      - "rebuildIndex fixes it, so schedule it every 10 minutes and we are done." — rebuild
+        clears the orphan for whatever is currently in the store, but the very next
+        deleteNote re-creates an orphan (event-trace t2), so it drifts back.
+      Reminder: the only index writers are the three in index-invariant; look for the one
+      whose ordering leaves a posting pointing at a note the store no longer has.
+tags: [state-corruption, search-index, invariant, debugging, ordering]

package/tasks/debugging/public/state-corruption-ledger-balance.yaml

@@ -0,0 +1,170 @@
+id: state-corruption-ledger-balance
+version: 1.0.0
+category: debugging
+cluster: state-corruption
+difficulty: expert
+title: Coinpurse Wallet Shows a Cached Balance Higher Than Its Ledger Sum
+summary: A wallet account reports a cached balance that exceeds the sum of its ledger entries. A reconciliation job flags the drift, a transfer-out path let a payment through on the inflated number, and a statement job printed it. Find the one writer that first breaks the balance invariant, separate it from the downstream observers that only saw already-bad state, and state the adequate versus the shallow fix.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (invariant-spec,
+  ledger-schema, writers-code, interest-diff, event-trace, recon-report, oncall-note).
+  Cite the artifact id(s) for every claim. Use this vocabulary for verdicts:
+  root-cause, red-herring, adequate-fix, shallow-fix.
+
+  Account A-42 in the "coinpurse" wallet service shows cached_balance = 61.50 while the
+  sum of its ledger_entries is 60.00. Do not stop at where the drift is reported; trace
+  to the writer where the invariant is FIRST violated.
+
+  1. State the balance invariant precisely, and list the COMPLETE set of functions that
+     are permitted to write accounts.cached_balance, per the artifacts.
+
+  2. ROOT CAUSE. Name the single writer whose execution first makes cached_balance
+     disagree with SUM(ledger_entries.amount) for A-42, and cite the exact expression and
+     the trace point where the two quantities first diverge. Explain why that write
+     violates the invariant.
+
+  3. RED HERRINGS. Classify the reconciliation job, the transfer-out path, and the
+     statement builder. For each, explain whether it corrupts state or only observes and
+     propagates state that was already corrupt, citing the trace.
+
+  4. Explain whether reverseEntry's `cachedBalance += -original.amount` is the defect or
+     is invariant-preserving, and justify with the trace numbers.
+
+  5. FIX ADEQUACY. Two fixes are on the table: (a) a nightly job recomputes cached_balance
+     from SUM(ledger_entries) for every account; (b) the offending writer records its
+     amount in ledger_entries like every other balance-changing writer. Classify each as
+     adequate-fix or shallow-fix and justify which durably restores the invariant.
+
+  6. BLAST RADIUS. State exactly which accounts can be corrupted and by how much, tying it
+     to the change in interest-diff.
+artifacts:
+  - id: invariant-spec
+    type: spec
+    label: coinpurse balance invariant and the complete writer set
+    content: |
+      coinpurse balance model (authoritative).
+
+      INVARIANT (B1): for every account, accounts.cached_balance MUST always equal
+      SUM(ledger_entries.amount) over that account's rows. ledger_entries is the source of
+      truth; cached_balance is a denormalized running total kept in step with it. Every
+      function that changes cached_balance MUST, in the same operation, insert a matching
+      row into ledger_entries carrying the same signed amount. A function that moves
+      cached_balance without an equal ledger_entries row breaks B1.
+
+      COMPLETE WRITER SET: exactly four functions may write accounts.cached_balance —
+      postEntry, reverseEntry, applyInterest, and applyHold. There are no other writers of
+      cached_balance anywhere in the service; triggers and raw SQL updates are prohibited by
+      policy. This is the complete and exhaustive list.
+
+      READERS (never write cached_balance): the reconciliation job, transferOut's
+      sufficiency check, and the statement builder read cached_balance but MUST NOT modify
+      it. applyHold records holds in a separate holds table and does not change
+      cached_balance at all.
+  - id: ledger-schema
+    type: config
+    label: coinpurse tables (excerpt)
+    content: |
+      -- accounts: one row per wallet.
+      --   account_id text primary key
+      --   cached_balance numeric(12,2) not null   -- denormalized running total (B1)
+      -- ledger_entries: append-only source of truth for balance.
+      --   entry_id uuid primary key
+      --   account_id text not null
+      --   amount numeric(12,2) not null            -- signed; credit > 0, debit < 0
+      --   kind text not null                        -- deposit|purchase|reversal|transfer
+      -- interest_log: monthly interest audit rows. NOT summed into the balance invariant;
+      --   this table is outside SUM(ledger_entries.amount).
+      --   log_id uuid primary key
+      --   account_id text not null
+      --   credited numeric(12,2) not null
+      -- holds: pending authorizations; separate from cached_balance entirely.
+  - id: writers-code
+    type: code
+    label: the four cached_balance writers
+    content: |
+      // coinpurse/balance.ts — the only functions permitted to write cached_balance.
+
+      export async function postEntry(acct, amount, kind) {
+        // normal path: debit or credit. Writes ledger row AND moves cached_balance by the
+        // same signed amount, so B1 is preserved.
+        await db.ledger_entries.insert({ account_id: acct, amount, kind });
+        await db.accounts.update(acct, { cached_balance: sql`cached_balance + ${amount}` });
+      }
+
+      export async function reverseEntry(acct, original) {
+        // refund/undo: inserts a compensating ledger row of the opposite sign and moves
+        // cached_balance by that same opposite amount.
+        const comp = -original.amount;                // e.g. original -30.00 -> comp +30.00
+        await db.ledger_entries.insert({ account_id: acct, amount: comp, kind: 'reversal' });
+        await db.accounts.update(acct, { cached_balance: sql`cached_balance + ${-original.amount}` });
+      }
+
+      export async function applyInterest(acct, credited) {
+        // monthly interest. Moves cached_balance up by `credited`.
+        await db.interest_log.insert({ account_id: acct, credited });
+        await db.accounts.update(acct, { cached_balance: sql`cached_balance + ${credited}` });
+      }
+
+      export async function applyHold(acct, amount) {
+        // authorization hold. Recorded in holds; does NOT touch cached_balance.
+        await db.holds.insert({ account_id: acct, amount, state: 'active' });
+      }
+  - id: interest-diff
+    type: diff
+    label: change to applyInterest shipped on 2026-06-30
+    content: |
+      # commit "move interest into its own audit table for finance reporting"
+      # coinpurse/balance.ts  applyInterest
+
+        export async function applyInterest(acct, credited) {
+      -   // v3: interest is a normal ledger credit, summed into the balance.
+      -   await db.ledger_entries.insert({ account_id: acct, amount: credited, kind: 'interest' });
+      +   // v4: interest now audited in interest_log for the finance team.
+      +   await db.interest_log.insert({ account_id: acct, credited });
+          await db.accounts.update(acct, { cached_balance: sql`cached_balance + ${credited}` });
+        }
+      # Only the destination table changed (ledger_entries -> interest_log). The
+      # cached_balance += credited line was left unchanged.
+  - id: event-trace
+    type: log
+    label: account A-42 operation trace with running quantities
+    content: |
+      # columns: time | op | ledger_sum(after) | cached_balance(after) | note
+      09:00 postEntry(+100.00 deposit)   ledger_sum=100.00 cached=100.00  # B1 holds
+      09:05 postEntry(-30.00 purchase)   ledger_sum= 70.00 cached= 70.00  # B1 holds
+      09:10 reverseEntry(original -30.00) ledger_sum=100.00 cached=100.00 # comp +30.00 both sides; B1 holds
+      09:20 applyInterest(+1.50)         ledger_sum=100.00 cached=101.50  # interest_log row written; NO ledger row -> B1 FIRST BROKEN here (+1.50)
+      09:40 transferOut(-40.00)          ledger_sum= 60.00 cached= 61.50  # sufficiency check read cached=101.50, allowed it; postEntry(-40) consistent on both sides
+      10:00 reconciliation run           ledger_sum= 60.00 cached= 61.50  # FLAGS mismatch of +1.50 (first observation, not first cause)
+      10:05 statement build              prints balance 61.50             # read-only; prints the already-wrong number
+  - id: recon-report
+    type: table
+    label: nightly reconciliation output
+    content: |
+      account | cached_balance | sum_ledger_entries | drift  | first_flagged
+      --------|----------------|--------------------|--------|--------------
+      A-42    | 61.50          | 60.00              | +1.50  | 2026-07-01
+      A-19    | 250.00         | 250.00             |  0.00  | -
+      A-88    | 18.25          | 15.25              | +3.00  | 2026-07-01
+      # drift = cached_balance - sum_ledger_entries. Positive drift = cached is too high.
+      # A-42 drift 1.50 equals one interest credit; A-88 drift 3.00 equals two interest
+      # credits since 2026-06-30. Accounts with no interest since then show zero drift.
+  - id: oncall-note
+    type: note
+    label: on-call triage thread
+    content: |
+      Triage guesses during the incident (record only; not all correct):
+      - "The reconciliation job is double-reading and inventing 1.50." — But reconciliation
+        only computes SUM(ledger_entries) and compares; it never writes cached_balance
+        (invariant-spec READERS). It reports the drift; it does not create it.
+      - "transferOut corrupted A-42 when it moved 40.00 out." — transferOut's postEntry
+        wrote -40.00 to BOTH ledger_entries and cached_balance (event-trace 09:40), so it is
+        invariant-preserving; it merely read an already-inflated cached_balance to approve
+        the transfer.
+      - "reverseEntry's double-negative `+= -original.amount` is obviously the bug." — the
+        trace at 09:10 shows both sides moved by +30.00 and B1 still held afterward.
+      - "cached_balance is the real balance; the ledger rows are just stale history." —
+        inverts the invariant; invariant-spec makes ledger_entries the source of truth.
+      Reminder: the only writers of cached_balance are the four in invariant-spec; look for
+      the one that moved cached_balance without an equal ledger_entries row.
+tags: [state-corruption, ledger, invariant, debugging, wallet]