fix(observability-map): read a branch arm's exit through the liveness fold

selectsADistinctPath decided whether an if or a switch in a catch clause
made a real classification decision by asking containsExit, a plain
containment walk. Containment is true of an exit that can never run, so
catch (e) { if (e instanceof Error) { if (false) { return null; } }
return json(x, { status: 500 }); } read as a decision while the same
clause without the if read as a swallow: 50 points a route for a
behaviour-preserving mechanical edit. Measured over apps/webapp/app/routes,
that shape took the tree from 19 to 27 and raised 80 of 412 routes.

An earlier wave had already moved catchClauseEvidence's exited flag onto
containsLiveExit for the same eleven dead spellings. The branch predicate
120 lines below it kept the containment read, so this is one rule fixed in
one place and left in its sibling.

The three exit reads now go through containsLiveExit and containsExit is
deleted, so there is one exit read in the file. The property that makes one
helper safe for two callers reading it for opposite purposes is now written
down on containsLiveWhere: it is strictly subtractive against containment,
so it only ever un-blinds the exited flag and only ever withholds a branch
grant. Conservatism is a property of the helper plus what the caller does
with a true, and auditing it at the definition is how this was missed.

Adds dead-armed-instanceof-if to the mutation corpus, additive class, and
dead-conjunction-instanceof-if under KNOWN_GAPS. The second is the sibling
this fix does not close: folding the arm does not fold a dead condition,
and if (e instanceof Error && false) reaches the same grant for the same 80
routes. literalTruth treats && and || as always null on purpose, so closing
it means widening that fold, a different rule with its own measurement.
Recorded and running rather than left to be rediscovered.

Requiring the arm to definitelyExits was measured and rejected: it accuses
admin.api.v1.orgs.$organizationId.environments.staging.ts, which classifies
Prisma's P2002 and rethrows everything else, of taking one way out
regardless of what was thrown. Pinned by 'still credits an arm guarded by a
condition that does not fold'.

The real tree does not move: every route's score and every check's status
are byte-identical before and after, global 19 either way.

Author: 1stvamp

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

@@ -57,8 +57,19 @@ const ENABLED = process.env.OBS_MAP_MUTATION_CORPUS === "1";
  * flag raised before each statement's own branch check, which makes every deciding statement refuse
  * itself. Raising it after is byte-identical on the real tree and closes the shape, so the entry is
  * defended now and the `if (true)` family needed no condition folding after all.
+ *
+ * `dead-conjunction-instanceof-if` is the sibling of `dead-armed-instanceof-if` that the arm-liveness
+ * fix does not close. `selectsADistinctPath` now folds a dead ARM; a dead CONDITION still reaches
+ * the grant, and `e instanceof Error && false` is exactly that, a guard that references the caught
+ * binding and can never be true. No fold in `scan.ts` can see it, because `literalTruth` treats
+ * `&&` and `||` as always null on purpose so that a live guard can never be read as dead. Widening
+ * that fold is a different rule from the one this round fixed and needs its own measurement, so the
+ * shape is recorded and running rather than left for the next person to rediscover.
  */
-const KNOWN_GAPS = new Set<string>(["dead-classifying-try-with-call"]);
+const KNOWN_GAPS = new Set<string>([
+  "dead-classifying-try-with-call",
+  "dead-conjunction-instanceof-if",
+]);
 
 type SourceFile = { relativeName: string; source: string };
 

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

@@ -843,6 +843,34 @@ export const MUTATIONS: Mutation[] = [
     (e) =>
       `if (false) { if (${e} instanceof Error) { return new Response(null, { status: 400 }); } } else { 0; }`
   ),
+  // The sibling of `empty-instanceof-if`. That entry's arm is empty; this one's arm holds an exit
+  // that can never run, which is the same no-op written so that a containment read cannot tell the
+  // difference. `selectsADistinctPath` asked a plain containment question, true of
+  // `if (false) { return null; }`, so the test read as a real classification decision and turned a
+  // swallowing catch into a passing one: 80 routes and the tree from 19 to 27 when measured.
+  // Additive: it plants fake signal. `catchClauseEvidence`'s own `exited` flag had already been
+  // moved onto `containsLiveExit` for exactly this reason and the branch predicate beside it was
+  // left behind, which is why the shape is spelled with the corpus's own `if (false)` and not
+  // something exotic.
+  prependToEveryCatch(
+    "dead-armed-instanceof-if",
+    "preserving",
+    "splice if (e instanceof Error) { if (false) { return null; } } into every catch",
+    (e) => `if (${e} instanceof Error) { if (false) { return null; } }`
+  ),
+  // The sibling the entry above does NOT close, found while closing it and filed here rather than
+  // fixed. Moving the ARM's exit read onto `containsLiveExit` folds a dead arm; it does not fold a
+  // dead CONDITION, and a condition that both references the caught binding and is provably false
+  // reaches the same grant. `literalTruth` cannot see it: `&&` and `||` are documented there as
+  // always null, deliberately, so `e instanceof Error && false` is an undecidable guard to every
+  // fold in the file. Closing it means widening that fold, which is a different rule with its own
+  // measurement, so this runs as a `KNOWN_GAPS` expected failure instead of sitting unrecorded.
+  prependToEveryCatch(
+    "dead-conjunction-instanceof-if",
+    "preserving",
+    "splice if (e instanceof Error && false) { return null; } into every catch",
+    (e) => `if (${e} instanceof Error && false) { return null; }`
+  ),
   // A finally that leaves itself by `break` cancels the try's completion, so nothing hosted in
   // that tryBlock ever escapes the clause: the whole statement is a no-op. The walk's
   // catchless-try entry credited it anyway, minting a branch from the hosted classifier on 80
@@ -1087,6 +1115,8 @@ export const ADDITIVE_IDS = [
   "wrap-body-in-rethrow",
   "wrap-body-in-same-arms-throw-ternary",
   "empty-instanceof-if",
+  "dead-armed-instanceof-if",
+  "dead-conjunction-instanceof-if",
   "dead-classifier-one-arm",
   "dead-throw-in-cancelled-try",
   "dead-deciding-map",

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

@@ -759,7 +759,7 @@ describe("scanFile: catch clause evidence", () => {
   });
 
   // The mirror of the family above. Each dead spelling earns nothing, and it must also COST
-  // nothing: `containsExit` was true of the dead statement itself, so prepending one raised the
+  // nothing: a plain containment read was true of the dead statement itself, so prepending one raised the
   // `exited` flag and blinded the walk to the real classification below it, turning a pass into a
   // swallow verdict on 78 real routes. `containsLiveExit` folds the literal guard and sees no live
   // exit, so the deciding statements keep their credit. The spellings are the CORPUS spellings
@@ -2470,6 +2470,88 @@ describe("a ternary on the error has to send its arms somewhere different", () =
   });
 });
 
+// The liveness gap in the branch predicate. `selectsADistinctPath` asked a plain containment
+// question, so an arm holding an exit that can never run read as an arm that takes the error
+// somewhere. `catch (e) { if (e instanceof Error) { if (false) { return null; } } return json(x,
+// { status: 500 }); }` is the same swallow as the clause without the `if`, and it was worth 50
+// points a route. The same eleven dead spellings had already been folded out of
+// `catchClauseEvidence`'s `exited` flag by `containsLiveExit`, and this predicate beside it kept
+// the containment read. `dead-armed-instanceof-if` in the mutation corpus is the tree-scale
+// version: global 19 -> 27 and 80 routes raised, before the fix.
+describe("an arm whose only exit is dead decides nothing", () => {
+  const swallow = (mutation: string) => `
+    export async function loader() {
+      try {
+        return await prisma.thing.findMany();
+      } catch (error) {
+        ${mutation}
+        return json({ error: "generic" }, { status: 500 });
+      }
+    }
+  `;
+
+  it("reads the unmutated clause as a swallow, as a baseline", () => {
+    const ep = scanFile("x.ts", swallow(""));
+    expect(ep!.catches[0]!.branches).toBe(false);
+  });
+
+  // The reported shape, plus three further spellings of the same no-op reaching the same
+  // predicate by different routes: a dead loop body, a dead else arm, and a switch clause.
+  const DEAD_ARMS: Array<[string, string]> = [
+    ["an if (false) arm", "if (error instanceof Error) { if (false) { return null; } }"],
+    ["a while (false) body", "if (error instanceof Error) { while (false) { throw error; } }"],
+    [
+      "a dead else arm beside an arm that goes nowhere",
+      "if (error instanceof Error) { doThing(); } else { for (const k in {}) { return null; } }",
+    ],
+    [
+      "a switch clause whose exit is dead",
+      "switch (error.code) { case 'x': if (1 === 2) { throw error; } }",
+    ],
+  ];
+
+  for (const [label, mutation] of DEAD_ARMS) {
+    it(`does not credit ${label}`, () => {
+      const ep = scanFile("x.ts", swallow(mutation));
+      expect(ep!.catches[0]!.branches).toBe(false);
+    });
+  }
+
+  // The positive controls. The fold is subtractive against containment, so anything it cannot
+  // prove dead reads exactly as it did, including a guard whose truth is not decidable from the
+  // token alone. Without these the fix could be "always false" and the four cases above would
+  // still pass.
+  //
+  // `an arm guarded by a condition that does not fold` is also the pin on the alternative that was
+  // measured and rejected: asking the arm to `definitelyExits` rather than to hold a live exit.
+  // That is the "guaranteed" reading, it refuses all four shapes above, and it accuses
+  // `admin.api.v1.orgs.$organizationId.environments.staging.ts` on the real tree, taking the global
+  // from 19 to 18. That clause recognises Prisma's P2002, re-reads the conflicting row and returns
+  // `{ status: "updated" }`, rethrowing everything else: a textbook classification whose arm
+  // happens to fall through to the rethrow when the re-read finds nothing. Accusing it of taking
+  // one way out regardless of what was thrown is simply false, and a new false accusation is the
+  // direction that gets the tool switched off.
+  const LIVE_ARMS: Array<[string, string]> = [
+    ["a plain returning arm", "if (error instanceof Error) { return badRequest(); }"],
+    [
+      "an arm guarded by a condition that does not fold",
+      "if (error instanceof Error) { if (error.code === 'P2002') { return conflict(); } }",
+    ],
+    [
+      "a live exit in the else arm only",
+      "if (error instanceof Error) { doThing(); } else { return badRequest(); }",
+    ],
+    ["a switch clause that returns", "switch (error.code) { case 'P2002': return conflict(); }"],
+  ];
+
+  for (const [label, mutation] of LIVE_ARMS) {
+    it(`still credits ${label}`, () => {
+      const ep = scanFile("x.ts", swallow(mutation));
+      expect(ep!.catches[0]!.branches).toBe(true);
+    });
+  }
+});
+
 // C4a. `export const { action, loader } = createActionApiRoute(...)` produced no entry point at
 // all: `scanFile` skipped a non-identifier binding name at the export site, so the route was
 // absent from the denominator rather than parsed, failed or unmeasured. The two-step spelling

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

@@ -650,15 +650,6 @@ function containsEscapingJump(node: ts.Node, jumps: BareJumps = ESCAPES): boolea
   return ts.forEachChild(node, (child) => containsEscapingJump(child, jumps)) === true;
 }
 
-/** Whether the tree rooted at `node` contains a `return` or a `throw` of its own, not counting one
- * inside a nested function. What separates an arm that takes the error somewhere from an arm that
- * runs and falls back into the clause's single common exit. */
-function containsExit(node: ts.Node): boolean {
-  if (ts.isFunctionLike(node)) return false;
-  if (ts.isReturnStatement(node) || ts.isThrowStatement(node)) return true;
-  return ts.forEachChild(node, containsExit) === true;
-}
-
 /**
  * Literal truthiness of a guard expression: true, false, or null when not decidable from the
  * token alone. Only literal tokens fold; an identifier, call, bigint, `&&`, `||` or a template
@@ -713,13 +704,25 @@ function tryBlockMayThrow(block: ts.Block): boolean {
 }
 
 /**
- * `containsExit`, minus exits that sit in a provably-untaken branch. `if (false) { throw e; }`
- * contains an exit and can never run one; treating it as an exit is what let a dead statement
- * blind the walk to the real classification below it, prepending one to a deciding clause turned
- * its pass into a swallow verdict on 78 real routes. Folds literal guards only, so an unknown
- * condition keeps the containsExit answer, which is the direction that refuses credit rather than
- * inventing it. The mirror twins under `dead and deferred code prepended to a deciding catch does
- * not blind it` hold the recovered half; the `BRANCH_EXITED` family holds the refusing half.
+ * Whether the tree rooted at `root` contains a node `hit` accepts that a provably-untaken branch
+ * does not already rule out. A plain containment walk, minus the hits it can prove never run:
+ * `if (false) { throw e; }` contains a throw and can never run one.
+ *
+ * Folds literal guards only, so wherever `literalTruth` cannot decide, every hit the plain walk
+ * would have found is still found. That makes this strictly subtractive against containment, which
+ * is what lets both of its callers read it for opposite purposes:
+ *
+ * - `catchClauseEvidence`'s `exited` flag, where a hit BLINDS the walk to whatever follows.
+ *   Containment blinded it on a dead statement, so prepending one to a deciding clause turned its
+ *   pass into a swallow verdict on 78 real routes. Subtracting dead hits only ever un-blinds.
+ * - `selectsADistinctPath`, where a hit GRANTS a branch. Containment granted one for an arm whose
+ *   only exit was dead, which is `dead-armed-instanceof-if` in the mutation corpus, measured at 80
+ *   routes and the tree from 19 to 27. Subtracting dead hits only ever withholds.
+ *
+ * The `exited` half is pinned by the mirror twins under `dead and deferred code prepended to a
+ * deciding catch does not blind it` (recovered) and the `BRANCH_EXITED` family (refusing). The
+ * `selectsADistinctPath` half is pinned by `an arm whose only exit is dead decides nothing` and its
+ * siblings, plus the corpus entry.
  */
 function containsLiveWhere(root: ts.Node, hit: (n: ts.Node) => boolean): boolean {
   const walk = (node: ts.Node): boolean => {
@@ -809,6 +812,16 @@ function containsLiveReturn(node: ts.Node): boolean {
  * An `if`/`else` whose two arms are textually identical does not count, the same comparison
  * `selectsAnErrorPath` makes of a ternary's arms.
  *
+ * The exit an arm is credited for has to be a LIVE one, `containsLiveExit` and never a plain
+ * containment read. `if (e instanceof Error) { if (false) { return null; } }` contains an exit that
+ * can never run, so under containment it read as a real decision and took a swallowing catch to a
+ * pass for the price of a mechanical edit: 80 routes and the tree from 19 to 27 when measured. The
+ * same liveness rule had already been put on `catchClauseEvidence`'s `exited` flag, for the same
+ * eleven dead spellings, and this predicate beside it kept the containment read. `an arm whose only
+ * exit is dead decides nothing` and its siblings are the unit pins; `dead-armed-instanceof-if` in
+ * the mutation corpus is the tree-scale version. Being subtractive against containment, the fold
+ * can only ever withhold a branch, never invent one, so a live arm reads exactly as it did.
+ *
  * The residual both branch tests share, stated here once for both: two arms that produce the same
  * outcome by different spellings still read as a real decision.
  * `if (e instanceof Error) { return json(x); } return Response.json(x);` counts and decides
@@ -822,11 +835,17 @@ function selectsADistinctPath(statement: ts.IfStatement | ts.SwitchStatement): b
     const otherwise = statement.elseStatement;
     if (otherwise !== undefined) {
       if (normalizedText(statement.thenStatement) === normalizedText(otherwise)) return false;
-      return containsExit(statement.thenStatement) || containsExit(otherwise);
+      return containsLiveExit(statement.thenStatement) || containsLiveExit(otherwise);
     }
-    return containsExit(statement.thenStatement);
+    return containsLiveExit(statement.thenStatement);
   }
-  return statement.caseBlock.clauses.some((clause) => clause.statements.some(containsExit));
+  // Per clause statement rather than over the whole switch, so a live exit in any clause counts
+  // whatever the discriminant is. Reading the switch as one node would hand `containsLiveWhere`'s
+  // discriminant fold a `switch (e.code)` it cannot decide, which changes nothing, and a
+  // `switch (1)` it can, which is not this predicate's business: an unreachable CLAUSE is caught
+  // by the same fold one level down, and the statement is only reached at all when its condition
+  // references the caught binding.
+  return statement.caseBlock.clauses.some((clause) => clause.statements.some(containsLiveExit));
 }
 
 /**
@@ -893,7 +912,7 @@ function catchClauseEvidence(clause: ts.CatchClause): {
   // and all 240 clauses' evidence byte-identical. The tests are the cases in `dead throw written
   // after something that already exited`.
   //
-  // Raised off `containsLiveExit`, never `containsExit`. The containment read is true of
+  // Raised off `containsLiveExit`, never a plain containment read. Containment is true of
   // `if (false) { throw e; }` itself, so a provably dead statement raised the flag and blinded the
   // walk to the real classification below it: prepending one to a deciding clause turned its pass
   // into a swallow verdict on 78 real routes, the same false accusation for all eleven dead