fix(observability-map): judge refused callback catches on their evidence

callbackCatches was a bare count and error-classification failed any
route whose only catches were refused by the iteration boundary, on
placement alone: wrapping a body in a non-array .map or .filter turned a
passing route into a fail, a false accusation on 85 real routes per
entry. The owner asked for the trade to be revisited.

Refused catches now carry full CatchEvidence, built by the same
catchClauseEvidence machinery as an own catch, and the check reads two
arms off it: a refused swallow fails whenever nothing the route owns
decides (deliberately not conditioned on the route owning no catches, so
an own inert rethrow cannot lift a refused swallow out of the verdict,
which closes a latent rise in the old code), and a route whose only
catches are refused and none swallows sits out at not-applicable, never
a pass. The ceiling is pinned at tree scale by the new dead-deciding-map
corpus entry: any future crediting of refused catches raises ~261
catchless routes and turns it red.

Real tree: global 19 -> 19, zero score or verdict changes, exactly two
detail-only changes on the tree's two callback-catch routes, both
genuine per-item swallows that keep failing. Mirror measurement:
wrap-body-in-non-array-map and -filter at falls 77 rises 0 dropouts 0,
every fall error-classification pass -> not-applicable; dead-deciding-map
falls 0 rises 0.

Author: 1stvamp

internal-packages/observability-map/src/checks/errorClassification.ts

@@ -146,11 +146,19 @@ export function usesBuilder(ep: EntryPoint): boolean {
  * `admin.api.v1.runs-replication.status.ts` at the top of the first rendered fix list.
  *
  * `callbackCatches` is the third case, and it is what stops "no catch is not-applicable" from being
- * a payout. A route whose catches all sat inside a callback the scanner refused to attribute has
- * error handling, the scanner just could not read it as the route's; excusing that is worth 50
- * points to anyone who wraps a body in something the boundary rule refuses, which
- * `Promise.all([0].map(async () => { ... }))` did. It fails instead. The precision cost is a route
- * that genuinely only handles errors per item, which now fails rather than sitting out.
+ * a payout. A refused catch is judged on its evidence, never on its placement: the same
+ * `catchClauseEvidence` an own catch gets, with two arms reading it. A refused swallow fails the
+ * route whenever nothing the route owns decides, and that arm is deliberately not conditioned on
+ * the route owning no catches, so an own inert rethrow catch cannot lift a refused swallow out of
+ * the verdict (`fails a per-item swallow even when the route owns an inert rethrow catch`). A
+ * route whose only catches are refused and none of them swallows sits out, and never passes: the
+ * not-applicable ceiling is what keeps a prepended dead deciding `.map` from minting a pass on the
+ * 261 catchless routes, which `dead-deciding-map` in the mutation corpus holds at tree scale and
+ * `sits out a catchless route with a prepended dead deciding map` pins on a fixture. What the old
+ * blanket placement rule blocked, relocating a swallow behind the boundary, still fails
+ * (`still fails a swallow wrapped in a non-array receiver's .map(...)`); what it wrongly accused,
+ * a route whose only error handling genuinely is per item, now sits out instead of failing
+ * (`sits out a route whose only catch is a deciding per-item boundary`).
  *
  * A clause whose try block holds nothing that could raise is read as no clause at all,
  * `guardCanRaise` on the evidence. Prepending `try { 0; } catch (e) { if (e instanceof Error) {
@@ -195,14 +203,35 @@ export const errorClassification = {
           : `catches its errors and chooses what to do without looking at what was thrown${which}`,
       };
     }
-    // Read off `ep.catches`, not `reachable`: a route that owns a catch owns one, whether or not
-    // `canRaise` could see what it guarded. Ordering this off `reachable` turned every `canRaise`
-    // miss on a route that also has a per-item catch into an accusation that was flatly false.
-    if (ep.catches.length === 0 && ep.callbackCatches > 0) {
+    // A refused (iteration-callback) catch is judged on its evidence, never on its placement.
+    // The fail arm first: a refused swallow fails whenever nothing the route owns decides.
+    // Deliberately NOT conditioned on `ep.catches.length === 0`: an own inert catch, which
+    // `wrap-body-in-rethrow` adds to every route, must not lift a refused swallow out of the
+    // verdict, or wrapping a per-item-swallow route in try/rethrow reads "every catch rethrows".
+    // `fails a per-item swallow even when the route owns an inert rethrow catch` pins that.
+    const reachableCb = ep.callbackCatches.filter((c) => c.guardCanRaise);
+    if (!reachable.some(decides) && reachableCb.some(swallows)) {
       return {
         id: ID,
         status: "fail",
-        detail: "its only error handling sits in a callback the route does not own",
+        detail:
+          "a catch inside an iteration callback swallows what it caught, and nothing the route owns decides",
+      };
+    }
+    // The ceiling: refused catches never reach the pass arm, so a route whose only catches are
+    // refused and none of them swallows sits out of the denominator rather than collecting
+    // anything. Read off `ep.catches`, not `reachable`: a route that owns a catch owns one,
+    // whether or not `canRaise` could see what it guarded; ordering this off `reachable` turned
+    // every `canRaise` miss on a route that also has a per-item catch into an accusation that was
+    // flatly false. The detail asserts nothing about ownership or per-item-ness the scanner
+    // cannot know: a once-invoked Result-style wrapper with a deciding inner catch reads the same
+    // as its inline equivalent would.
+    if (ep.catches.length === 0 && ep.callbackCatches.length > 0) {
+      return {
+        id: ID,
+        status: "not-applicable",
+        detail:
+          "its only catches sit in iteration callbacks and none swallows, so the route itself classifies nothing",
       };
     }
     if (!reachable.some(decides)) {

internal-packages/observability-map/src/checks/index.test.ts

@@ -507,11 +507,11 @@ describe("error-classification", () => {
     expect(r.status).toBe("not-applicable");
   });
 
-  // A7 as revised. A per-item error boundary inside a `.map()` callback is still not judged as the
-  // route's own catch, so it never sets `catches` and never speaks for the route's `tryStatementCount`.
-  // It is no longer excused either. Reading "no catch of its own" as not-applicable was worth 50
-  // points to anything that could get the boundary rule to refuse the route's real catch, which
-  // `[0].map(...)` did, so a refused catch now fails instead of sitting out.
+  // A7 as revised twice. A per-item error boundary inside a `.map()` callback is still not judged
+  // as the route's own catch, so it never sets `catches` and never speaks for the route's
+  // `tryStatementCount`. This catch SWALLOWS what it caught, and nothing the route owns decides,
+  // so the route still fails: judging refused catches on their evidence must not stop failing the
+  // relocated swallow, which is the anti-laundering half of the rule.
   it("fails a route whose only catch is inside a Promise.all(items.map(...)) callback", () => {
     const source = `import { prisma } from "~/db.server";
        export async function action({ request }) {
@@ -529,10 +529,108 @@ describe("error-classification", () => {
        }`;
     const ep = scanFile("batch.process.ts", source)!;
     expect(ep.catches).toEqual([]);
-    expect(ep.callbackCatches).toBe(1);
+    expect(ep.callbackCatches).toHaveLength(1);
     const r = run("error-classification", "batch.process.ts", source);
     expect(r.status).toBe("fail");
-    expect(r.detail).toContain("callback the route does not own");
+    expect(r.detail).toContain("a catch inside an iteration callback swallows");
+  });
+
+  // The evidence half of the mechanism-C rule: a refused catch that DECIDES caps at not-applicable
+  // rather than failing (the old placement rule) or passing (the crediting rule `dead-deciding-map`
+  // exists to refuse). The route's error handling is real and per item; the route itself decides
+  // nothing, so out of the denominator is the honest place for it.
+  it("sits out a route whose only catch is a deciding per-item boundary", () => {
+    const r = run(
+      "error-classification",
+      "batch.decide.ts",
+      `import { prisma } from "~/db.server";
+       export async function action({ request }) {
+         const results = await stream.map(async (item) => {
+           try {
+             await service.call(item);
+           } catch (e) {
+             if (e instanceof KnownError) { return new Response(e.code, { status: 400 }); }
+             throw e;
+           }
+         });
+         return json({ results });
+       }`
+    );
+    expect(r.status).toBe("not-applicable");
+    expect(r.detail).toContain("its only catches sit in iteration callbacks");
+  });
+
+  // Same shape with an inert per-item rethrow: not a swallow, so it sits out too.
+  it("sits out a route whose only catch is an inert per-item rethrow", () => {
+    const r = run(
+      "error-classification",
+      "batch.rethrow.ts",
+      `import { prisma } from "~/db.server";
+       export async function action({ request }) {
+         const results = await stream.map(async (item) => {
+           try {
+             await service.call(item);
+           } catch (e) {
+             throw e;
+           }
+         });
+         return json({ results });
+       }`
+    );
+    expect(r.status).toBe("not-applicable");
+    expect(r.detail).toContain("its only catches sit in iteration callbacks");
+  });
+
+  // The refused-swallow arm is deliberately not conditioned on the route owning no catches. An
+  // own inert catch is what `wrap-body-in-rethrow`, a preserving corpus entry, adds to every
+  // route: were the arm gated on `catches.length === 0`, wrapping a per-item-swallow route in
+  // try/rethrow would read "every catch rethrows" and lift the fail to not-applicable, a rise
+  // that existed in the pre-evidence code and was masked only by the affected routes scoring 0 on
+  // every other check.
+  it("fails a per-item swallow even when the route owns an inert rethrow catch", () => {
+    const r = run(
+      "error-classification",
+      "batch.wrapped.ts",
+      `import { prisma } from "~/db.server";
+       export async function action({ request }) {
+         try {
+           const items = await prisma.item.findMany();
+           await Promise.all(
+             items.map(async (item) => {
+               try {
+                 await processItem(item);
+               } catch {
+                 return null;
+               }
+             })
+           );
+           return json({ ok: true });
+         } catch (e) {
+           throw e;
+         }
+       }`
+    );
+    expect(r.status).toBe("fail");
+    expect(r.detail).toContain("a catch inside an iteration callback swallows");
+  });
+
+  // The no-pass ceiling at the fixture scale: a catchless route with a prepended dead deciding
+  // map sits out. A crediting rule would read pass here, which is 50 free points on the tree's
+  // 261 catchless routes; the old placement rule read fail, a false accusation on a preserving
+  // prepend. `dead-deciding-map` in the mutation corpus is the tree-scale version.
+  it("sits out a catchless route with a prepended dead deciding map", () => {
+    const r = run(
+      "error-classification",
+      "prepended-map.ts",
+      `import { prisma } from "~/db.server";
+       export async function action({ request }) {
+         [0, 1].map((v) => { try { JSON.parse("0"); } catch (e) { if (e instanceof SyntaxError) { return null; } throw e; } return v; });
+         const rows = await prisma.thing.findMany();
+         return json({ rows });
+       }`
+    );
+    expect(r.status).toBe("not-applicable");
+    expect(r.detail).toContain("its only catches sit in iteration callbacks");
   });
 
   // The same route with nothing caught anywhere stays not-applicable, so the fail above is

internal-packages/observability-map/src/mutations.ts

@@ -828,6 +828,19 @@ export const MUTATIONS: Mutation[] = [
     },
   },
 
+  // The no-pass ceiling on refused (iteration-callback) catches, at tree scale. A two-element
+  // array literal iterates, so the boundary rule refuses this catch; it decides and cannot run
+  // its deciding arm (JSON.parse("0") never throws). Under any future rule that CREDITS refused
+  // catches, the ~261 catchless routes rise from not-applicable to pass and this entry goes red.
+  wrapEveryBody(
+    "dead-deciding-map",
+    "prepend a dead deciding per-item catch inside a two-element .map to every route body",
+    '[0, 1].map((obsMapV) => { try { JSON.parse("0"); } catch (obsMapDead) {' +
+      " if (obsMapDead instanceof SyntaxError) { return null; } throw obsMapDead; }" +
+      " return obsMapV; });",
+    ""
+  ),
+
   {
     id: "merge-declarations",
     kind: "preserving",
@@ -917,6 +930,7 @@ export const ADDITIVE_IDS = [
   "wrap-body-in-same-arms-throw-ternary",
   "empty-instanceof-if",
   "dead-classifier-one-arm",
+  "dead-deciding-map",
   "registered-throw",
   "fake-require-guard",
   "fake-authenticated-lookup",

internal-packages/observability-map/src/scan.test.ts

@@ -1567,6 +1567,52 @@ describe("scanFile: catch clause evidence", () => {
       );
       expect(ep!.catches).toEqual([]);
     });
+
+    // A refused catch keeps its evidence, built by the same machinery as an own catch, so
+    // `error-classification` can judge what it does rather than where it sits. Both flavours are
+    // pinned: the deciding per-item catch and the inert one.
+    it("populates evidence for a refused per-item catch that decides", () => {
+      const ep = scanFile(
+        "x.ts",
+        `
+        export async function action({ request }) {
+          const items = await load(request);
+          return items.map(async (item) => {
+            try {
+              return await process(item);
+            } catch (e) {
+              if (e instanceof KnownError) { return new Response(e.code, { status: 400 }); }
+              throw e;
+            }
+          });
+        }
+        `
+      );
+      expect(ep!.catches).toEqual([]);
+      expect(ep!.callbackCatches).toHaveLength(1);
+      expect(ep!.callbackCatches[0]).toMatchObject({ branches: true, guardCanRaise: true });
+    });
+
+    it("populates evidence for a refused per-item catch that only rethrows", () => {
+      const ep = scanFile(
+        "x.ts",
+        `
+        export async function action({ request }) {
+          const items = await load(request);
+          return items.map(async (item) => {
+            try {
+              return await process(item);
+            } catch (e) {
+              throw e;
+            }
+          });
+        }
+        `
+      );
+      expect(ep!.catches).toEqual([]);
+      expect(ep!.callbackCatches).toHaveLength(1);
+      expect(ep!.callbackCatches[0]).toMatchObject({ rethrows: true, branches: false });
+    });
   });
 });
 

internal-packages/observability-map/src/scan.ts

@@ -1026,11 +1026,13 @@ function isAtMostSingletonArray(expr: ts.Expression): boolean {
  * whole body })` collected it.
  *
  * Two things changed. A receiver that is an array literal of one element or none is refused here,
- * because it cannot iterate. And the direction that used to pay no longer pays: `walkBody` counts
- * the catches it refuses, and `error-classification` fails a route whose only catches were refused
- * rather than excusing it. That is what makes the name list survivable, and it is why
+ * because it cannot iterate. And the direction that used to pay no longer pays: `walkBody` keeps
+ * the catches it refuses, evidence and all, and `error-classification` fails a route with a
+ * refused swallow when nothing the route owns decides, while a refused catch that decides caps at
+ * not-applicable and never a pass. That is what makes the name list survivable, and it is why
  * `Result.map(...)`, which no name list can tell from `users.map(...)`, is a corpus entry that
- * passes rather than a hole.
+ * passes rather than a hole: relocating a swallow behind the boundary still fails, and relocating
+ * a decision earns at most the route's exit from the denominator.
  *
  * The other direction still costs points and the earlier version of this comment said otherwise.
  * A per-item callback under a callee the name list does not know, `pMap(items, cb)` or
@@ -1509,7 +1511,7 @@ export function scanFile(fileName: string, source: string): EntryPoint | null {
 
   let statementCount = 0;
   let hasTryCatch = false;
-  let callbackCatches = 0;
+  const callbackCatches: CatchEvidence[] = [];
   const catches: CatchEvidence[] = [];
   const calleeNames: string[] = [];
   const logCalls: LogCall[] = [];
@@ -1540,8 +1542,9 @@ export function scanFile(fileName: string, source: string): EntryPoint | null {
     // not: a per-item catch is not part of this body's own statement list, and `countStatement`
     // already stops at a nested function boundary, so counting it here let `tryStatementCount`
     // exceed the entry point's whole `statementCount` and judged a per-item error boundary as
-    // though it were the route's own. What is refused is counted in `callbackCatches` instead of
-    // dropped, so a route whose only error handling was refused is failed rather than excused.
+    // though it were the route's own. What is refused is kept in `callbackCatches` with its
+    // evidence instead of dropped, so `error-classification` can fail a refused swallow and sit
+    // out a refused catch that decides, without ever crediting either as the route's own.
     //
     // Only an iteration callback is a boundary, not every function-like node: a route's own body
     // wrapped in `trace(async () => {...})`, `mutateWithFallback({ pgMutation: async (t) => {...} })`
@@ -1562,11 +1565,13 @@ export function scanFile(fileName: string, source: string): EntryPoint | null {
       }
       if (ts.isTryStatement(node)) {
         hasTryCatch = true;
-        if (node.catchClause && inCallback) callbackCatches++;
-        if (node.catchClause && !inCallback) {
+        if (node.catchClause) {
+          // Built the same way for a refused catch as for an own one, so the dead-code defence
+          // and the walk's guaranteed-execution rules apply to both. Which list it lands in is
+          // walkBody's attribution decision alone.
           const tryStatementCount = countStatements(node.tryBlock.statements);
           const clause = catchClauseEvidence(node.catchClause);
-          catches.push({
+          (inCallback ? callbackCatches : catches).push({
             rethrows: clause.rethrows,
             throws: clause.throws,
             branches: clause.branches,

internal-packages/observability-map/src/types.ts

@@ -146,11 +146,15 @@ export type EntryPoint = {
   catches: CatchEvidence[];
   /**
    * Catch clauses the scan found but refused to attribute to the route, because they sit inside a
-   * per-item iteration callback. Kept rather than dropped so `error-classification` can tell "this
-   * route catches nothing" from "this route's only error handling was refused", which are 50 points
-   * apart and used to read the same.
+   * per-item iteration callback. Still refused for attribution: they never join `catches`, never
+   * speak for the route's `tryStatementCount`, and never reach a pass. Kept WITH their evidence,
+   * built by the same `catchClauseEvidence` machinery as an own catch, so `error-classification`
+   * can judge what a refused catch does rather than where it sits: a refused swallow fails the
+   * route (`fails a per-item swallow even when the route owns an inert rethrow catch`), a refused
+   * catch that decides or rethrows caps at not-applicable (`sits out a route whose only catch is a
+   * deciding per-item boundary`). The count the old field carried is `.length`.
    */
-  callbackCatches: number;
+  callbackCatches: CatchEvidence[];
   /** Calls to a `logger.*` or `log.*` callee in those bodies, in source order. */
   logCalls: LogCall[];
   /**