…nalysis

The scanner missed 30% of server entry points in apps/webapp/app/routes.
It found 299 of 427; it now finds all 427 with 0 parse failures.

- detect named export clauses (export { loader }, export { h as loader }),
  resolving a local binding back to its declaration for the builder callee
- recurse one level into flat-route directories and key entry points by a
  path relative to the scan root, so route.tsx files stay distinct
- count statements for the loader/action bodies only, recursing through
  try, if, loop and switch blocks so a try-wrapped body reports its real size
- scope hasTryCatch and calleeNames to the entry-point bodies, leaving
  importedNames file-wide
- resolve the initializer callee to the root of a call chain
- throw on parse diagnostics so parseFailures can actually fire
- scan .test.ts route files and exclude .d.ts instead

…cation

…r heuristics

Follow-up to the adversarial review of the scanner fixes.

- follow a call from a loader/action body to a same-file helper, one hop
  with a cycle guard, so a body that delegates reports the helper's
  statements, try/catch and callees rather than just the delegation.
  ph.$.ts goes from 2 statements and hasTryCatch false to 30 and true;
  66 entry points gain statements, 6 gain hasTryCatch
- only treat a ParseFailureError as a parse failure in scanDirectory and
  rethrow everything else, so an unreadable file is no longer reported as
  malformed source, and keep the diagnostic alongside the file name
- match a builder handler only at the top of the config object or under
  methods.<HTTP method>.handler, not by name at any depth
- read handler arguments from the root call of a builder chain only, so a
  callback given to a later decorator is not the route body
- pin the loosened assertions and add negatives for the new resolution,
  the handler shapes and the chained builder

Adds error-classification, auth-boundary, request-context and audit-trail,
plus the CHECKS registry. Every check is a pure function of an EntryPoint and
reads body-scoped evidence only.

Two rules differ from the design. error-classification uses hasTryCatch as its
gate rather than a regex over ep.source, which is the whole file including the
React component; EntryPoint carries no evidence about what a catch does with
the error, so the check reports the hand-rolled catch and says it has not been
read. request-context looks for an identity resolved in the body rather than
grepping the file for identifier names, for the same reason. Both deviations,
and the calibration run over the 427 webapp entry points, are written up in the
task 5 report.

…ntry points

The error-classification and request-context checks could not tell a
rethrow from a swallow, or a database call from any method with a common
name. Four additive fields, all body scoped through the existing one-hop
helper resolution.

- catchRethrows and catchBranches: whether a catch clause in the bodies
  contains a throw, or branches with if, switch or instanceof. Of the 190
  routes that catch, 140 do one of those and 50 take one path out
- calleeTexts: the full callee path (prisma.organization.findFirst), index
  aligned with calleeNames, which is unchanged
- logCalls: logger.* and log.* calls with their object argument field names
  and whether the call sits in a catch, so a check can ask whether the
  failure path logs an identifier

No existing field changes value on any of the 427 route entry points.

error-classification now reads catchRethrows and catchBranches instead of the
mere presence of a try. It fails only where every catch in the bodies takes one
way out regardless of what was thrown, which drops the finding count from 130
to 50. The swallow is read before the builder is credited: a swallow inside a
builder-wrapped handler never reaches the builder, and 18 of the 50 are that
shape.

request-context now asks whether a failure-path log names a tenant, using
logCalls with inCatch and the field names. The builder pass is gone, because
the builders log { error, url } at their boundary and the logger only attaches
http context ambiently, so a wrapped route is not attributed either. The check
no longer echoes auth-boundary: 17 entry points of 427 are scored by both, and
they disagree on 10 of those.

auth-boundary and audit-trail are unchanged.

…eration

error-classification cannot tell the deliberate narrow guard, e.g.
try { body = await request.json() } catch { 400 }, from a catch that
swallows the whole handler. Both take one path out.

catchesNarrowly is true when an entry point has at least one catch clause
and no try block with a catch holds more than two statements, counted in
the loader/action bodies and the same one-hop helpers as the other fields.
Every catch has to qualify: one broad catch anywhere makes it false, so a
route that guards a JSON.parse and also wraps its handler is still
reported. Two statements lets the guarded operation bind its result and
stops short of the three-statement try that covers a handler.

55 of the 427 route entry points, and 11 of the 32 error-classification
failures, all eleven hand-read as the deliberate idiom. No existing field
changes value.

… nothing

Applicability keyed off the presence of a failure-path log, so a route that
kept its errors and recorded nothing was not-applicable rather than reported,
and deleting a log line took a route out of the report. Every non-trivial entry
point is now judged: no catch at all passes, since the error reaches the central
handler, and a catch has to name whose failure it was. 87 of the 169 failures
are routes that record nothing, which is what the old gate was hiding.

Verified over the real tree that removing logging cannot help: re-running all
four checks against every entry point with log calls deleted, failure-path logs
deleted, and log fields stripped moves 63 verdicts, none of them for the better.

error-classification now uses catchesNarrowly to excuse the guard that wraps a
single parse. Applied on its own the field also excuses a one-statement try
around a service call, which passes the design's own swallow fixture and four
findings that were hand-read as real, so the exemption also asks that the body
parse something. That clears the nine verbatim request.json guards and keeps the
rest: 50 failures become 35.

…p and unmeasured tracking

…see into

The rendered fix list opened with three auth-boundary findings and all three
were wrong. Two delegate to clearImpersonation, which authenticates and writes
an audit row in a file the scanner never opens, and the third is a redirect stub
flagged only because its path contains billing.

A fail here says the route does privileged work with no guard, which is only
supportable when the body is where a guard would have to be. A trivial body
cannot hold a visible privileged operation, by the triviality rule's own
definition, so either nothing privileged happens or the work sits behind an
import along with any guard. Those now report not-applicable with a detail
saying the guard could not be verified, rather than failing. Signature checks
also count as guards now, which clears the HMAC-authenticated waitpoint
callback. Three findings remain and all three are genuinely unauthenticated.

request-context stops treating a parse guard as the route taking over its
failure path, through the same shared reading of catchesNarrowly that
error-classification uses. Re-ran the incentive sweep after the change: 57
verdicts move when logging is removed, none for the better.

Whole-entry catch booleans collapse when a route has a narrow parse guard
and a broad handler catch, so a check cannot reason about either. 17 route
entry points are in that state.

- catches: one CatchEvidence per catch clause in the bodies and the one-hop
  helpers, carrying narrow, rethrows, branches, guardsParse and the try
  block statement count
- guardsParse reads constructors as well as parse calls, so new URL(referer)
  is visible without touching calleeTexts, which other checks read
- a try/finally now yields an empty catches list. hasTryCatch keeps its
  meaning, a try appears, so ask catches.length whether anything is caught
- catchRethrows, catchBranches and catchesNarrowly are now derived from the
  list and keep their values on all 427 route entry points

242 catch clauses over 189 entry points, 9 of them swallowing outright.
Clears all three false positives at the top of the report.

Both checks now read EntryPoint.catches instead of the aggregate booleans, so
an entry point is only as good as its worst catch. 39 routes have more than one
catch and 17 mix a narrow guard with a broad handler, and a single well-behaved
catch used to speak for the swallow beside it.

Neither check reads hasTryCatch any more. A try/finally leaves it true with no
catch clause at all, which is what put runs-replication.status at the top of the
first rendered fix list; the question is now catches.length. A parse guard is
recognised when it covers less than half the body, which keeps otel.v1.logs
reported, where the catch covers 15 of 18 statements and merely contains a
request.json.

The narrow limb of the proposed rule is left out. A one-statement try around an
awaited service call is as narrow as one around a parse. Taking it clears eleven
more routes and reading all eleven says six are real, including a silent run
cancellation and two credential paths that report a database failure to the
browser as a 400 with the internal message in it.

FIX FIRST now reads account.tokens, api.v1.authorization-code and api.v1.token,
all three genuine. Global score 83.

… smoke

Adds pnpm run map (repo root and package script), single-entry inspection
mode, and index.ts exports. The routes directory now resolves against the
repo root found by walking up to pnpm-workspace.yaml, not process.cwd(),
so the CLI works from both the repo root and the package directory.
Single-entry mode notes when an entry has no applicable scored checks
rather than printing a bare 100/100. Gitignores the generated
observability-map.json artifact.

…likes

Two catch-evidence fields matched shapes that resemble the thing they
detect, which excused catches the checks exist to find.

- guardsParse took any new X(), so new BranchesPresenter() or new Set()
  excused a catch over ordinary work. It now needs a parsing constructor,
  URL, URLSearchParams or RegExp, chosen from what the route tree actually
  constructs inside try blocks. 60 of 242 clauses change, 141 true to 81
- branches took an instanceof anywhere in the clause, including the
  error instanceof Error ? error.message : String(error) idiom, which words
  a message rather than picking a path. It now needs an if, a switch, or a
  conditional that is the whole return or throw. 29 of 242 clauses change,
  134 true to 105. All 33 bare instanceof uses in the tree are the
  formatting idiom

Clauses with no evidence at all go from 9 to 37. error-classification will
need recalibrating: on this evidence it reports 64 routes rather than 28,
and nothing it reported before stops being reported.

The build config had no include and no rootDir, so tsc inferred the package root
because vitest.config.ts happened to be inside the compilation. That is the only
reason dist/src/index.js landed where the package's main points, and excluding the
config would have silently moved the entry point. Scope the build to src and pin
rootDir so the layout is intentional.

vitest was resolving from the root workspace by hoisting despite being the test
runner and supplying the global types. Declare it at the version the other internal
packages use.

Emptying every catch clause in the tree scored it 100. Both scored checks
passed on the single fact that a route has no catch: error-classification
credited it as propagating to the global handler, request-context treated it as
having handed its failures over. So the gradient rewarded deleting error
handling, and 222 of 412 entries scored 100 on that one shared fact.

error-classification now reports not-applicable for a route with no catch,
since there is no classification decision to judge, and no longer credits a
builder wrapper for error handling the route does not do. request-context fails
it instead: the global handler carries requestId, path, host and method and no
tenant, so such a route genuinely cannot name whose request broke. Excusing it
would reinstate the perverse incentive.

Score falls from 76 to 22, which is the honest reading. Deleting all error
handling now takes it to 7 rather than 100. The two checks decorrelate: kappa
on error-classification against request-context moves from +0.231 to -0.032,
and the other two pairs stay near zero.

…ring stdout

Both scan steps redirected pnpm --filter ... exec stdout into files the renderer
JSON.parses. pnpm takes its recursive path under --filter and some versions
announce 'Scope: N of M workspace projects' on it; one such line in head.json
fails the parse and degrades every run to the stale-report comment, which is a
permanent quiet failure rather than a loud one.

It does not reproduce on the 10.33.2 the workflow pins, which was checked, so
this closes the class rather than a reproduction: the scanner writes its own
file and stdout is left to be log output. The -s guard keeps the partial dance
honest now the redirect no longer creates the file, so a scanner that exits 0
without writing takes the stale-report branch instead of failing the mv and
turning the job red.

The render step still captures stdout, since prCommentCli has no --out and a
banner there puts a stray line in a markdown comment rather than breaking a
parse.

Reported by Devin on #4455.

…tion

The 30s and 60s per-test timeouts on the two real-tree tests were chosen on an
idle machine, and the suite also runs inside unit-tests-internal.yml, which
executes turbo run test --filter "@internal/*" as twelve concurrent shard
processes on one runner. The 30s one does flake under that.

Measured on an 8-core box. This file alone at load average 0.9: 6.3-6.4s for the
scan, 10.8-11.2s for the sweep, both well above the 1.6-2.6s the old comment
claimed. Two batches of twelve concurrent copies on those same 8 cores: 24.2-34.0s
for the scan and 27.6-39.7s for the sweep, with one of the first twelve dying on
"Test timed out in 30000ms". Twelve processes over 8 cores is 1.5 per core where
the 32-vCPU runner is 0.375, so the reproduction is harsher than CI, which is why
it is the thing to size against.

Both now use one 120s constant, which is 3x the worst contended run measured.
60s was the other candidate and is not enough: the sweep already reached 39.7s.
Neither test asserts anything about elapsed time, so the number is a hang
detector rather than a performance budget, and the docstring says so.

Reported by Devin on #4455.

mutations.ts entryBodies collected exported function declarations and
exported const identifiers only, so it missed the object binding pattern
(export const { action, loader } = createActionApiRoute(...)), the export
clause (const { action } = builder(...); export { action }), and
export const action = route.action. That is 36 of the tree's 427 entry
points, all of them API routes: every whole-body corpus entry skipped them
while the file count suggested otherwise. The scanner has read all four forms
since early on, so this was the harness lagging it.

No assertion could have noticed. A mutation that reaches fewer routes lowers
the score rather than raising it, which is exactly how the suppress-every-check
omission hid, so the answer is the same: assert the population. admin.tsx is
the one exclusion, named rather than counted, because its handler is a concise
arrow with no block for a block wrapper to wrap.

wrap-body-in-rethrow goes from 391 files with 36 entry points missed to 426
files, 1020 sites, 1 missed. Widening changes no entry's verdict: the full
corpus is 55 passed and 1 expected fail either way, and with the narrow
population the only failure is the new population assertion itself.

readTree now calls routeModuleFiles rather than keeping its own copy of the
directory walk. isScannableFile had already replaced the file half of that
copy; the directory half survived.

…rules

Sweeping the package for the defect behind the two review threads: one
question answered by two pieces of code, where only one copy gets fixed.

Shared:
- the scannable-file predicate, copied into integration.test.ts and
  webappSymbols.test.ts after it was exported to stop mutationCorpus.test.ts
  copying it
- the FIX FIRST filter and sort, byte-identical in terminal.ts and
  prComment.ts, which already imports five helpers from it; failingIds is now
  scoredFailures plus a map
- normalizeSegment, in the test that validates SENSITIVE_SEGMENTS against the
  real tree. It was splitting segments with /_+$/, the regex that function's
  own comment says not to use
- the five bare-literal node kinds, written out in literalTruth three lines
  above the literalValue that already had them

Pinned:
- contextGap and auditGap, which redo by hand what checkContributions
  computes generically, on two headline figures with nothing saying they had
  to agree. Reverting either to a different denominator or numerator now goes
  red

Left alone, with reasons recorded in the sweep report: canRaise vs
tryBlockMayThrow, the two exact true-keyword folds, the two comment
extractors, the three means, ratio vs globalWithout, and the eight AST
helpers mutations.ts keeps its own copies of so the corpus can disagree with
the scanner.

Cuts every comment that restated the code, and shortens the rest to the
proportional statement of the non-obvious why: a hidden constraint, a
call into something undocumented, or a named residual a reader of that
exact function has to see. The measurements and rejected alternatives
they carried now live in the README, and the safety properties keep
their test names inline so docstringReferences.test.ts still checks
them. No behaviour change: the real-tree report is byte identical.

Same pass over the test files. Each block now states in a line or two
which regression the test below pins, and names the corpus entry or
sibling test where the pairing is load bearing; the narrative around it
is in the README. The KNOWN_GAPS entries keep a reason each, on the id
they belong to, so neither expected failure is orphaned.

The README carried four jobs at once after the inline commentary moved into
it: what the tool measures, how to read the report, how the scanner decides,
and a running account of what earlier rounds got wrong. Split it. README.md
keeps the reader-facing job (running it, CI, what the score means, the five
checks, headline figures, not-applicable, suppression, known limits, layout);
INTERNALS.md takes the scanner reasoning, the mutation harness, the reporting
arithmetic and the CI wiring, for someone changing the tool.

Cut the history throughout. What a fix changed and why the old shape was
broken is in the commits and the ledger; a rejected alternative is kept only
where someone would otherwise re-propose it, and then in one line. Every
inline 'README, <section>' pointer is repointed and every one resolves to a
heading that exists.

964 lines becomes 336 + 494. The real-tree report is byte-identical.

…asured side