P1–P7: extract the seams, get work off the request path, make verified mean something

[archdex-art]

52 commits. Each is independently green and carries its own reasoning; this is the map.

The single most important change: verified used to mean after.score >= before.score — a fix graded by the very metric it was built to move. Four real gates replace it, and codegraph fix --verify runs them where a developer's test suite actually lives.

What ships

P1 — enforceable seams. app/ becomes an npm-workspaces monorepo. 14 packages with a layering rule enforced in CI, not a diagram. Findings become rows with fingerprints.

P2 — work off the request path. apps/worker as a separate process with a child per job — the ADR-001 fix for web-tree-sitter's ever-growing WASM heap. Measured, not asserted: two concurrent index jobs at --memory=512m --cpus=0.5, both done, peak 341.8 MiB / 512 MB, no OOM, 2 children spawned and reaped.

P3 — make verified mean something.

Gate	Check	Skips when
1 · syntax	real TypeScript parse of each edited file	never
2 · types	tsc --noEmit	no type config
3 · tests	the repo's own suite, timeboxed, SIGKILLed	host cannot isolate
4 · re-analysis	the target finding's fingerprint is gone	never

Gate 4 checks a fingerprint, not the aggregate score. "The score went up" is not evidence that this finding was fixed.

apps/cli — gate 3 needs an isolated container, which Render cannot give, so a hosted instance can only ever report partial. On your machine it reports full. Source never modified; you get a diff proven to apply with git apply with the suite still green afterwards. Exit code is the verdict.

P4 — score credibility. Pillars split so defect risk is surfaced alone (maintainability was 22% of a number read as risk). Coverage published beside the score (ADR-008). Eight organisational signals from one git log pass.

P7 — surface honesty. Every README claim mapped to a test; ARCHITECTURE.md reconciled; feature status labels.

Review items closed

	Was	Now
C3	verified = after.score >= before.score	four gates + VerificationRecord
C1	one finding ran every fixer over every file — 27-file diff for a one-line fix	POST /api/findings/:id/fix; Fixer.handles: [ruleId]
C4	UI said "your source is never modified" while the executor pushed a branch	every remote mutation behind confirmed: true
C5	projectedScore a linear guess	re-runs the real scorer; refuses to project from a truncated list
C6	ARCHITECTURE.md described two architectures three paragraphs apart	reconciled, guarded by tests
B1	line-based edits behind a regex guard	AST decides — reproduced the regex silently rewriting a help string inside a template literal

Bugs found by running it, not by reading it

• 54% of CodeGraph's self-index was other repositories' code — cloned targets under data/workspaces/, contributing 77 of 200 reported issues.
• Only the root package.json was ever read — 3 dependencies found where 36 were declared.
• The worker exited on an idle queue — setTimeout(...).unref() meant nothing held the loop; every unit test bounds it with maxJobs, so none ever waited.
• getJob cast the raw column — queue says succeeded, dashboard polls for done. Finished jobs left clients polling forever.
• rev-list --before returned a commit from a different repository merged into socket.io's history — a 7-file tree. --first-parent is load-bearing.

Five gates that reported success while inspecting nothing

The recurring shape of this branch, and the reason for the meta-checks:

• npm run lint had never run. no-console: ["error", { allow: [] }] is invalid under ESLint 9 → exit 2 before linting a file. CI never invoked it. Both were needed to hide it.
• Three packages had no layer rule — absent from ALLOWED means unconstrained, while the gate printed "no violations".
• Three workspaces were never typechecked — --if-present skips silently. A deliberate error in apps/cli produced 0 errors.
• scripts/ was typechecked by nothing — not a workspace.
• /build/ had a leading space in .gitignore, so the pattern matched nothing — 478k lines of build output and runtime data were being committed.

Each now fails loudly, each verified to exit non-zero.

A negative result, kept

P4 §5.3's calibration failed its own gate and the weights are not adopted — k = 0.06 still stands, still labelled hand-picked. Model 0.673 mean-per-repo vs churn 0.718 and file size 0.717.

More importantly, ADR-009 retires the target. Cross-project AUC measures whether weights learned from other people's repositories transfer to yours — the question a product shipping one universal model must answer. CodeGraph indexes one repo deeply (HLD §2.2) and holds its whole history. The measured failure was base-rate non-transfer (socket.io: 78% defective, max prediction 0.269), which cannot occur within one repository.

Adopting a competitor's headline figure as an exit criterion is reactive positioning (IDENTITY.md §4.4) in methodology rather than in copy. The corpus, harness and leakage guard are retained and retargeted to within-repo validation.

Verification

typecheck    PASS (incl. scripts/)   lint      PASS (0 errors, pinned ceiling)
tests        902/902 · 66 files      desktop   35/35
depcruise    0 violations            boundaries 288 files, 0 violations
workspaces   18/18 gated             build     PASS
docker       512 MB / 0.5 vCPU, 2 concurrent jobs, peak 341.8 MiB, no OOM

npm run bench reproduces every published benchmark figure from a fresh clone.

Reviewing this

Mutation testing caught eight tests that passed for the wrong reason — an invented gate-4 target, a recordRun fingerprint test, two individually-redundant scoped-fix filters, an unexercised diff offset, a parent check, and a doc assertion matching prose instead of a table. Writing a test and watching it pass proved less than it appeared to, every time.

Worth reading in order: ADR-009 (why a phase's exit criterion was wrong), docs/LINT_DEBT.md (what turning a dead gate on revealed), benchmarks/calibration/scorecard.json (a published negative result).

Not done, stated plainly

• Fixers still rewrite line arrays. B1's complaint is closed; range-based edits end-to-end need P5's typed extraction.
• codegraph fix is the only CLI command — no index, no score. A test asserts they don't exist.
• Call resolution is still heuristic. CommonJS extraction took express from 11 to 37 resolved edges, but 155 of 174 symbols still have no inbound edge. That is P5, and P6's cache depends on it — invalidation walks resolved edges backward, so building it now would appear to work while serving stale findings.
• 7 react-hooks/refs violations are genuinely wrong, inventoried in docs/LINT_DEBT.md rather than suppressed.

---

Amendment: cross-repo calibration deleted (3462c6f)

ADR-009 retired the cross-project ROC AUC target but said the corpus and harness were "kept and
retargeted". That was half a decision. Nothing in the product imported @codegraph/calibrate,
and 784 KB of twelve other projects' git history sat in the tree as an invitation to re-run the
wrong experiment.

Deleted: packages/calibrate, benchmarks/calibration (13 datasets + scorecard),
scripts/calibrate.mts, scripts/fit.mts, both npm scripts.
Kept: ADR-009, amended — every measurement is quoted there. The reasoning is the durable
artefact, not the pipeline that produced it.

CodeGraph indexes one repository deeply (HLD §2.2). A universal learned model answers a question
this product does not ask.

Also recorded honestly: seven of the eight organisational signals are computed and unread —
they were built for the deleted calibration. They ride a git pass churn already requires, so
they cost ~0, but PLAN.md §5.2 now states the condition on which they stay (shown to a user), and
"already written" is not it.

---

P4 closed out: confidence enters the kernel (de667a9, 18d94a2)

PLAN.md §5.2 asked for "actually using the confidence the scorer stores and ignores". It stored
one on all 87 express findings and weighed a 0.7 guess exactly as heavily as a 0.95 eval().

penalty = severity × blast × volume × confidence

Multiplying is an expectation, not a tuned weight — so unlike §5.3 it needs no corpus and
ADR-009 does not apply. That the two axes are independent is established by the rule table, not
assumed: eval() and Possible hardcoded secret are both severity 5, so severity means
impact if real and multiplying doesn't double-count.

Express 74 → 77, security 45 → 52. k = 0.06 deliberately not rescaled to hold the old
headline. Also collapses a formula that scoreIssues and the issue ordering duplicated, kept in
step only by a comment saying they must agree.

The golden table was verified, not pasted. Uniform-0.9 fixture ⇒ every score moves to
100·(s/100)^0.9; hand-computed before editing (maintainability 100·0.11^0.9 = 13.7 → 14). The
law is now asserted so the semantics are locked, not just the outputs. Mutation-tested 4/4 — and
the first run reported "additive SURVIVED" because my harness was wrong (sed pattern spanning a
newline), not the test.

Not closed by this: HLD §8.3's ladder says lexical-tier findings are "marked low-confidence",
but nothing sets confidence from tier. Recorded in PLAN.md §5.2 rather than left implied.

---

P5 scoped by measurement, not assumption (7fe7322)

Before building P5 I measured its premise — the mistake ADR-009 records is aiming a phase at a
number that isn't the question.

Found a real bug on the way. Type-aware resolution was silently losing to the name-based
fallback. Two defects, neither of which matters without the other:

	type-aware hits	call edges
before	1,094	1,912
after	2,167	1,914

createProgram got relative rootNames while getCurrentDirectory() reported the real cwd; and
getSymbolAtLocation on an imported identifier returns an alias whose declaration is the
import line in the calling file. The ids named symbols that exist in no file, missed, and fell
through in silence.

It never produced wrong edges — it produced unusable ids. And the heuristic is good enough
that nothing looked broken.

How good, measured: across 2,159 calls where both resolvers answered, they disagreed on 35
(1.6%), checker right every time — all same-name shadowing. So: ~35 corrected edges, correct
provenance for ~1,000 more. Not a step change, and not described as one.

P5's exit criterion is already met and shouldn't be the target. For TypeScript the compiler
is ground truth for what a call refers to — no labelled corpus needed. Scored that way the
heuristic is at 98.4%, so "precision ≥ 0.85" would pass without doing any work. The real gap
is recall (47% of symbols here, 89% on express have no inbound edge), and the checker added
zero project targets the heuristic missed. PLAN.md now says so.

Two things I got wrong and corrected in-branch: a directoryExists override I was sure was
required measured exactly 0 and was deleted. And my three new tests all survive disabling
the typed path — the doc comment now says that outright instead of implying they prove it.

---

Recall: module scope is a caller (395183c)

The gap wasn't resolution — it was attribution. Call-site source was a partial function:
only a call lexically inside a named function produced an edge, and if (!caller) continue
discarded the rest. 2,313 of 5,025 resolved calls (46%) were thrown away after being
correctly resolved.

Visible symptom: rep in pillars.test.ts is called four times in its own file and the graph
showed zero callers — so it was reported as dead code.

Source is now total. Every call site has an enclosing execution context; at worst that's the
module body, which executes on import. Standard modelling — <module> in Python's profiler,
<clinit> on the JVM, LLVM module constructors.

	before	after
call edges (this repo)	1,914	2,529
symbols with no inbound edge	47%	32%
functions reported dead	276	146
call edges (express)	38	261
unreferenced (express)	89%	61%

Health Score unchanged at 77 — blast radius reads file-level import fan-in, not symbol
fan-in. Checked, not assumed.

Kept only what measured. constant in the caller kinds scored exactly 0 edges and was
removed — an arrow in a const is already extracted as function, and in const x = foo()
the initialiser runs at module scope, so naming x would be a confident wrong answer. class
stayed on evidence: 5 edges, 9 fewer synthetic nodes, and a field initialiser genuinely runs.

6 tests, mutation-verified 5/5 — and every mutation asserted to have applied before the
run, after a sed pattern silently matched nothing earlier in this branch and reported a false
SURVIVED.

Honest limit: ~38% of the remaining 411 unreferenced symbols still have real call sites.
Recall is improved, not finished. What's settled is the diagnosis: the bottleneck was
attribution, and typed extraction would not have moved either number.

---

Rendering is invoking (e1a2de0)

The extractor recorded only CallExpression, so a function used as a value produced no
reference. Measured with the checker: 372 function identifiers in value position vs 6,836 in
call position. Two classes are unambiguous — JSX tags (91) and callback arguments (41).

	before	after
components with no inbound edge	41 / 41	6 / 41
call edges (this repo)	2,529	2,599
functions reported dead	146	100
call edges (express)	261	299
unreferenced (express)	107 / 174	72 / 174

<AgentSwarm /> is a JsxSelfClosingElement, never a CallExpression. Every component in a
React codebase was an isolated node — the worst graph defect on this branch, in a product whose
thesis is that the graph is the product. The 6 remaining are Next.js page/layout entry points,
which genuinely have no in-repo caller.

Corrects a claim published two commits earlier. That commit said "~38% of the remaining
unreferenced set has real call sites" — from git grep counting matches inside strings and
comments. On the AST: 3 of 137 (2%). Recall was already essentially closed and I reported it
as a third open. The error inflated the remaining work, which is the flattering direction, so
README and PLAN.md are corrected in place.

Mutation-tested 5/5 — and the fifth found a vacuous test, not a code defect. The
"no speculative edges" case used export const limit = 5 as its decoy, which the extractor never
records as a symbol, so no edge could form whatever the code did and the assertion could never
fail. Decoy is now a class. Second test this branch has shipped that asserted nothing; second
time mutation testing was the only thing that noticed.

---

P5 item 1: rules fire only where they can be true (1ec6978)

Each rule now declares the syntactic context in which it can hold, checked against comment and
string ranges from the TypeScript scanner. Measured before writing anything: 35% of rule
matches on express, 64% on this repo, landed somewhere the rule cannot be true.

	before	after
issues (express)	87	66
security dimension	52	71
Health Score (express)	77	82

All 21 suppressed findings were verified by reading them — eval( and innerHTML inside an
XSS test fixture string in test/res.redirect.js, and 16 http://localhost:3000 URLs inside
// example: comments. No true positive lost.

Per-rule, not blanket comment/string stripping: a TODO belongs in a comment, @ts-ignore
can only be a comment, a hardcoded localhost URL is necessarily a string. Blanket stripping
would have deleted three rules' true positives.

Python deliberately unchanged — syntacticSpans returns [] outside the TS family. A
hand-rolled lexer would be wrong at the edges, and a wrong span suppresses a real finding.

Mutation-tested 6/6 — two exposed weak tests, not weak code. The Python case had no quotes,
so the scanner emitted no spans either way; the offset case sat on line 1, where the +1 for the
newline cannot matter (and 12 lines was still too few — the drift landed exactly on the string's
opening quote). Both would have passed review and CI forever.

Recorded limit: this is the position class, not yet a graph-shape query. eval( in code is
accepted without confirming it's a CallExpression resolving to global eval.

---

P5 item 2: taint analysis — and it found a real vulnerability (d9ecd8a)

eslint-plugin-security flags any non-literal sink argument and never asks where the value came
from. Measured here: 170 sink findings, all at one confidence.

verdict	count
tainted	2	reaches a sink from user-controlled input
sanitized	26	a source, then a transform or dominating guard
untraced	142	no source found in this function

The 2 were a genuine hole in our own code. FileSystemService.readFile/writeFile passed
request.path from an Electron IPC message straight into fs. The fs:read/fs:write
permissions answer "may the renderer touch the disk", never "which file" — so any renderer
holding one could read or write everything the user could.

Fixed with FsGrants: a directory is reachable because the user picked it in the OS dialog,
the capability model @codegraph/fsx already uses server-side. Symlink escapes defeated via
realpath of the nearest existing ancestor. The analysis now reports both sinks sanitized —
detector finds it, fix lands, same detector confirms it.

Taint modulates confidence, never deletes. An incomplete source list would otherwise become
silent false negatives. Since confidence already multiplies into expectedHarm, the two
changes compose with no new machinery. Express 82 → 85, security 71 → 78.

Guard recognition is where the CFG value was. JS validates far more than it transforms —
check, return early, use the original value — so no assignment happens and def-use sees
nothing. Guards took tainted 6 → 2; the four dropped were api/browse/route.ts, guarded one
line above each sink.

Two things measured and thrown away: a per-path seen set (30ms vs 29ms — it prunes within
a path, never across branches, so the depth cap already did the work) and a live differential
test against fsx.resolveSafe (making tsc accept it drags fsx's whole tree into the desktop
program). The differential earned its place first: it found the two contracts genuinely
diverge on absolute paths, now pinned as its own test.

Mutation-tested 10/10. All three first-round survivors were missing tests, not weak code.

---

P5 item 7: HLD §8.3's degradation ladder was documentation only (66f75ab)

The architecture document described a per-file analysis tier, an "% of LOC at tier ≥ ast"
coverage figure, and lexical findings "marked low-confidence". None of it existed — the only
tier in the codebase was an unrelated module-layout depth. CLAUDE.md §5 says don't claim what
the code doesn't do, and this was a claim in the architecture doc itself.

Now real: tierForExt assigns the tier, ScanCoverage.tierLoc reports LOC per tier, and a
lexical finding's confidence is scaled by 0.45 — which reaches the score, since confidence already
multiplies into expectedHarm. 56.7% of this repo's LOC is tier full; the rest is Python,
regex-scanned, and now says so. Express is unchanged at 85 — correctly, it's all JavaScript.

The tier boundary is deliberately the same one syntacticSpans uses: files that get no context
gating are exactly the files whose findings can't be trusted as far. One source of truth rather
than two extension lists drifting.

ast is defined and never produced, and the type says so. Every AST-path language here is
TypeScript-family and reaches full; Python's extractor is regex-based. The rung is real in the
design and empty in the code — recorded, not quietly dropped.

Removed a duplicated type found on the way. ScanCoverage was declared in both
analysis-model and indexer.ts; adding a field to one failed to typecheck against the other.
The drift wasn't hypothetical — it happened inside this commit.

Mutation-tested 5/5, and one survivor was another vacuous assertion: "does not zero a finding
out of existence" checked confidence > 0, but scaleConfidence has a 0.05 floor — so it passed
with the factor set to zero. Replaced with a ratio between two rules of different base
confidence, which pins proportionality without hard-coding the constant.

---

Correction: context gating was suppressing real findings (7e90ef3)

The gate I shipped two commits earlier drove ts.createScanner in a bare while (scan()) loop.
That loop cannot rescanTemplateToken after a TemplateHead, nor reScanSlashToken to settle
regex-versus-division — so it desyncs at the first ${…} or / and mis-tokenises the rest.

Validated against the parser over 4,783 sampled positions:

	count
scanner says NOT code, parser says code	1,125 (23.5%)	findings suppressed
scanner says code, parser says not	140	noise leaked

process.exitCode = 1; was being classified as a string. Suppression is the failure direction
that module's own comment claimed to avoid — and the one nobody notices.

The measurement that justified this work was parser-based all along; only the implementation
wasn't. Rewritten on createSourceFile: false negatives 1,125 → 7, false positives 0,
index cost +13%. Template substitutions are now code, so rules can still see ${userInput}.

Also fixes trailing comments — TS classifies a comment before the first newline as the
previous token's trailing comment, which getLeadingCommentRanges deliberately skips, so
const a = 1; // note was invisible.

Mutation-tested 5/5 after two rounds of fixing the tests, not the code. An explicit EOF pass
turned out to be dead (forEachChild already visits endOfFileToken) and was deleted. The
out-of-order case needed the comment on the same line as the closing brace — on its own line
the spans come out already sorted and a missing sort before a binary search is invisible.

Item 4 measured and deferred: only 30 of 148 untraced sinks derive from a parameter — the
ceiling for caller-side propagation — and the examples are build scripts. Recorded in PLAN.md.

---

Synthetic module nodes leaked into enumeration (c5d0da8)

Adding <module> nodes was right; letting them into every query that lists symbols was not.
Measured right after they landed:

search("module")	21 of 30 results synthetic
hubs()	ranked a module node in the top three
symbolAt(file, 1)	returned <module> instead of a function starting on line 1

The symbolAt one is a real regression: it picks the smallest enclosing span, and a module
node is zero-width — so nothing is ever smaller. A finding on line 1 attributed to <module>
rather than the function containing it, and that method feeds file:line → symbol mapping for
taint reachability and UI navigation.

The rule, now stated in code: a node the user didn't write is a legitimate answer about the
graph and never an item in a list of their code. search/symbolAt/hubs filter;
callers/callees/impact/members deliberately don't — "called from module scope" is the
whole reason the node exists.

Verified the fix actually reaches the UI rather than assuming. The API route imports
QueryEngine from @/lib/codeintel/query, which looked like a second implementation that would
have made this invisible — it's a two-line re-export shim. Every intel op then checked:
cycles can't contain a module node, buildContext seeds from the filtered search.

Mutation-tested 5/5, including one that strips the filter from callers — the tests fail if
the exclusion goes too far as well as not far enough.

---

P6 first increment: content-addressed memo (06ea1d0)

Exit criterion corrected before building, not after. The stated exit is "warm re-index ≤ 5%
of cold". Profiled first (303 TS files, ~2.1s):

phase	ms	memoisable per file?
eslint security	624	yes
ts.createProgram	567	no
symbol extraction	420	no — see below
getTypeChecker	199	no
syntacticSpans	104	yes

5% is unreachable while a TS program is built. oldProgram reuse was measured, not assumed:
751ms cold → 734ms with one file changed → 682ms with nothing changed. Parsing is reused;
binding and checker construction are not. ~766ms is a hard floor.

Delivered: 2,205ms → 1,220ms (55% of cold), 614 hits and no new misses on the second pass.

Symbol extraction excluded deliberately despite being the third-largest cost: a reference's
resolvedTargetId names a declaration in another file, so a content-keyed hit can serve a
stale edge once that file moves. It needs a dependency key, not a content key — the unsound
version trades visible slowness for invisible wrong answers.

Where re-indexing actually happens isn't users re-opening a repo: executor.ts indexes
twice per remediation to measure the score delta, and the Timeline indexes one snapshot per
commit. Both index near-identical trees in one process.

PLAN.md now proposes a checkable exit — warm ≤ 60% of cold with a documented reason for the
remainder. Below that needs an incremental graph, a much larger piece of work.

Mutation-tested 5/5, including dropping version from the key — the failure that silently
serves findings from a previous implementation for the life of the process.

---

P5 item 5: SARIF 2.1.0 export (d6d162f)

HLD §3 named a "SARIF 2.1.0 export adapter at the boundary" as the mechanism satisfying the
interoperability requirement, and LLD §13 specified the route. Neither existed — the same
shape of claim as HLD §8.3's tier ladder.

toSarif in @codegraph/analysis-model, served by GET /api/repos/:id/sarif behind the same
repoAccessDenied + viewerId pair as every other repo route. A download endpoint is exactly
where tenant isolation gets forgotten.

One direction, enforced by layering rather than discipline: this module imports from the
model, no SARIF type appears in any signature the rest of the codebase uses. Written from the
spec's shape rather than pulling a SARIF library — zero new dependencies, and the mapping
decisions are visible instead of inherited.

Two fields deliberately not emitted, both pinned by tests:

• rank — SARIF's 0-100 priority field. Filling it exports a second ranking that can
  disagree with the Health Score. The inputs are all in properties instead.
• partialFingerprints — core-domain has a real fingerprint keyed on a normalised
  snippet; Issue doesn't carry one. A weaker hash under the standard name would silently
  disagree with the product's own identity for a finding.

Severity 1-5 → three levels is lossy, so the original number always rides in properties. An
export that loses information the API already gives you is worse than none.

Mutation-tested 5/5 real mutations. A sixth was provably inert (rules is a Map keyed by
ruleId, so re-setting the same key changes nothing) — reported as inert, not counted. A seventh
reported SURVIVED and had never applied: shell escaping mangled the backslashes. Third time
this branch a harness bug masqueraded as a passing mutation.

---

Tenant isolation enforced structurally (a5c760c)

tenant-isolation.test.ts covered named routes by hand — so a route added tomorrow is
covered only if someone remembers. Same shape as the gates this branch already fixed: a check
that cannot tell you what it skipped is not a check.

Concretely: the SARIF download route from the previous commit is guarded because I thought to
guard it. Nothing would have failed if I hadn't — and a download endpoint serving another
tenant's findings is exactly where this gets missed.

Now enumerated from disk: every route.ts under repos/[id]/ must call repoAccessDenied or
requireWorkspace. 11 routes today, and any new one is checked the moment it exists.

Two meta-assertions, because a structural test is precisely the kind that passes while
inspecting nothing: the enumeration must find >8 routes (a wrong path can't make it vacuous),
and a file that imports a guard without calling it fails.

The audit found no vulnerability, and that's worth stating. Three routes — fs, search,
timeline — looked unguarded because they use requireWorkspace rather than repoAccessDenied
directly. Reading requireWorkspace showed it calls repoAccessDenied on line 65. The grep
was incomplete, not the routes.

Mutation-tested 3/3 against real code, not fixtures: removing the guard from the SARIF
route, stubbing out requireWorkspace while leaving its import, and pointing the scan at a
nonexistent directory.

---

Dogfood pass: CodeGraph run on CodeGraph (d45e33a)

Self score was 68 with the security dimension at 12, and the top of our own findings was one
rule firing wrongly over and over. Two false-positive classes, both real code here:

site	value	why it isn't a secret
settings.ts:71	anthropicApiKey: "assistant.anthropicApiKey"	a settings path
redact.test.ts	anthropicApiKey: "sk-ant-BAD-KEY"	a test fixture

Entropy was tried and rejected on evidence. The fixture sk-ant-SCOPED-BUT-VALID-KEY scores
H=4.18 — above AKIAIOSFODNN7EXAMPLE (3.68) and a 40-char hex digest (3.83). Across ten
samples the separating signal was a digit. Applied as a confidence multiplier, never a
reject, because correcthorsebatterystaple is a real secret with no digits.

detect-unsafe-regex downgraded 0.85 → 0.5. Both instances it reports here were measured
and neither backtracks — sub-millisecond at n=16,000 — while the control /^(a+)+$/ takes 258ms
at n=26. It's a static over-approximation that flags a shape without proving the alternatives
overlap. One of the two regexes it flagged is one I wrote in this commit.

Self 68 → 71, security 12 → 22. Express 85 → 89, security 79 → 91 — and its six
downgraded "secrets" were read before publishing a better number: 'keyboard cat',
'manny is cool', 'some secret here', all placeholders in examples/.

Mutation-tested 5/5 after two rounds. Two survivors were harness bugs (shell escaping ate
\d — fourth time). Two were real gaps: CONFIG_PATH_RE looked dead but isn't (a dotted path
with a digit needs it), and "does not delete a downgraded finding" asserted > 0 against a
0.05 floor — so it passed with the factor set to zero.

Recorded, not fixed: Large file (1259 LOC) on indexer.ts is a true positive about work in
this branch. Extracting rules removes ~180 lines against a 600 threshold — a reduction that
doesn't clear it. Clearing it is the detect-engine/score-engine split LLD §13 specifies.

---

score-engine extracted (d6d816b, c805353)

First slice of LLD §13's five-way split of indexer.ts, prompted by CodeGraph's own output:
Large file (1259 LOC) was the top self-finding, naming the file this branch kept growing.

Chosen because it removes a real coupling, not just lines. agents/orchestrator.ts computes
the swarm's projected score by re-running the real scorer (review C5) — which meant importing
scoreIssues from the indexer, so scoring a hypothetical list of findings dragged in the file
walker, the ESLint layer, the TypeScript program builder and the taint analysis. The score model
depends on none of it.

The swarm now imports @codegraph/score-engine, whose only dependency is analysis-model, and
dependency-cruiser enforces it rather than a comment asking nicely.

HITS_PER_RULE_PER_FILE moved with the scorer — it's what volumeMultiplier measures excess
against, so two copies would let the cap and the scale disagree silently.

indexer.ts 1,259 → 1,131. The finding does not clear — predicted and recorded before
starting, since the threshold is 600 and one ~130-line slice was never going to reach it. The
remaining slices (pipeline/enumerate, lang-*, detect-engine, viz) are what get there.
Reporting a reduction as a reduction.

Every published number identical: express 89, projected 89 → 90, remediation 89 → 95, and the
24-case golden score table moved with the code it locks.

ARCHITECTURE.md's package table was caught by its own guard the moment the package existed —
updated from the failure, not from memory. And a follow-up commit records the outcome in
PLAN.md: the first attempt's doc edit silently failed on an anchor mismatch while the code
landed, leaving the plan with the problem statement and no result.

---

viz extracted + the shared contract (768ab9e)

Second slice of LLD §13. The prerequisite mattered more than the slice: ScannedFile lived
inside indexer.ts, and every stage the split extracts takes one — so each new package would
import the file it was extracted from, which is the coupling the split exists to remove. It's
now the shared input contract in analysis-model, with LANG_BY_EXT (two copies would let the
graph disagree with the language table beside it).

viz separates because it answers a different question: the symbol graph is what the product
reasons over; this is what a person looks at, and its node cap has nothing to do with
detection being correct.

indexer.ts 1,259 → 1,001 across both slices. Still above 600 — reported as a reduction,
not a fix. detect-engine (~415 lines) is next and more entangled: it needs PipelineContext,
so the abort contract moves first.

Numbers unchanged again: express 89, projected 89 → 90, remediation 89 → 95, 920/920. The
benchmark proves behaviour preservation rather than the diff looking safe.

---

detect-engine extracted — indexer.ts 1,259 → 703 (36b6c7b)

Third and largest slice (407 lines). The rule table, context gate, taint verdict, tier ladder and
secret value-shape signal now sit together — because they compose. A finding in a Python file
from a rule whose value doesn't look generated is discounted twice, and both multiply into
expectedHarm. Reading that product in one place is the only way to see it.

Scoring is deliberately elsewhere: keeping them apart is what stops a rule being tuned to move a
number.

The layering gate caught a wrong slice boundary. analyzeDependencies moved with the other
rules and dependency-cruiser failed instantly — raw-fs-only-in-io-packages. It reads
package.json from disk, so it's I/O and belongs with the pipeline. The gate found a mistake I
had already made and typechecked.

resetIssueIds() replaces indexRepo assigning a module-level counter across a package
boundary — ids are a per-run sequence and executor.ts indexes twice per remediation.

Detection's tests stay in analysis on purpose: they drive indexRepo, so moving them would
make detect-engine depend on the pipeline it was extracted from.

104 lines from clearing the 600 threshold. Numbers unchanged for the third refactor running:
express 89, projected 89 → 90, remediation 89 → 95, 920/920.

---

LLD §13 split complete — indexer.ts 1,259 → 478 (29b719d)

Two final moves: buildModuleGraph → viz (display structure, same category as buildVizGraph
and buildTree), and import extraction/resolution → @codegraph/imports.

The gate corrected the package name. It was created as lang-imports and
lang-packages-are-leaves rejected it instantly — a lang-* package "knows its own syntax and
nothing about detection, scoring, or storage", which is what makes adding a language additive.
This stage needs ScannedFile and PipelineContext, so it's a pipeline stage containing
per-language syntax, not a language plugin. The rule was right; the name was wrong.

The Large file finding clears — as a consequence of splitting on cohesion, not as the
target. What remains is walk, scan, dependency hygiene (reads package.json, so it stays with
the I/O) and indexRepo orchestrating. Splitting further would be ceremony.

Five packages out of one file over four commits — score-engine, viz, detect-engine,
imports — plus shared contracts in analysis-model. Dependency-cruiser polices every edge.

The layering gates caught two structural mistakes that typechecking and 920 tests did not:
analyzeDependencies placed in a package forbidden raw fs, and this package's name. Both
invisible to the compiler.

Express 89, projected 89 → 90, remediation 89 → 95, 920/920 — identical through all four
refactoring commits.

---

Detection precision measured: 72% [58–83%] — P5.3 not met (a226b36, 18032de, ac6033e)

Protocol pre-registered and committed before any finding was sampled — the commit order is
the evidence. Fixed the stride, three labels, six decision rules, and that unclear counts
against.

corpus	precision	95% CI
express	22/25 = 88%	70–96%
self	14/25 = 56%	37–73%
total	36/50 = 72%	58–83%

The aggregate misleads; the breakdown is the point. 35 of 50 findings come from rules right
every time (debug 16/16, fs paths 7/7, large files 5/5, localhost 3/3, any 3/3). Four rules
carry all the failure — and two of them, secrets 0/7 and TODO 0/4, account for 11 of 14
false positives.

TODO and Suppressed checker fail identically: the rule matches text that describes the
thing rather than is it. Every false TODO was prose about TODO handling. This repo discusses
its own rules constantly, which is why self (56%) trails express (88%) — unrepresentative, as
§5 said before the numbers existed.

The one true ReDoS led somewhere unexpected. IMPORT_RE was genuinely superlinear
(5,583ms at n=3200) — and unreachable: astTsExtractor took the regex extractor as a
fallback and never called it. That dead branch had already cost this branch real time (a
CommonJS fix written into code that never ran). 95 lines deleted; the live path
(@codegraph/imports) was measured instead and guarded there.

Two process failures worth recording. The first guard was vacuous — it called
extractorFor(".ts"), which returns the AST extractor, so restoring the vulnerable pattern left
it green (sixth such test caught by mutation). And verifying the replacement hung the run for 15
minutes, leaving the source mutated because the restore never executed — caught by checking the
file rather than trusting the harness.

---

Precision 72% → 88% by acting on the breakdown (7df585f)

Same protocol, same corpora, same stride. Sample redrawn each pass because fixing a rule changes
the finding list — which is why the per-rule table matters more than the total.

pass	change	express	self	total	95% CI
1	baseline	88%	56%	72%	58–83%
2	markers must follow a comment opener, unquoted	88%	76%	82%	69–90%
3	placeholder tokens + synthetic runs	100%	76%	88%	76–94%

Pass 2 — mention vs occurrence. TODO 0/4 and Suppressed 0/1 were 11 of 14 false positives.
Comment-context was necessary and not sufficient: a comment discussing markers is still a
comment. A real marker directly follows //, /*, * or #; a mention sits mid-sentence. Plus:
a marker in backticks is a quoted example, and every match is scanned, since one comment can
quote an example and leave a real marker.

Pass 3 — placeholders. Secrets 0/8, all fixtures. Placeholder words as whole tokens plus runs
no generator emits. The token boundary is load-bearing: AKIAIOSFODNN7EXAMPLE contains "EXAMPLE"
preceded by 7, so it isn't a token and stays reported.

Is 0.85 met? The point estimate is, at 88%. The interval is not settled — lower bound 76%,
and n=50 can't resolve it. Reported as both, not whichever reads better.

One fix deliberately not made. Suppressing secrets in *.test.*/examples/ would clear the
last three outright. A real credential committed to a test file is exactly what's worth catching,
and path suppression silences it. That's a recall decision, not an oversight.

Two more weak tests caught by mutation, plus an existing fixture the new rule correctly
suppressed — abcdefghij… isn't what a generator emits, so the rule was right and the fixture
was unrealistic.

---

Held-out validation: 87% — the fixes generalise (012a41a, 81d4f65)

Passes 2 and 3 were fitted to false positives I had already read — the placeholder token list
contains words taken from the failures it fixes. That's legitimate rule design and also how a
number stops generalising, so criteria and a falsifiable prediction were committed before
cloning anything.

Three repos never analysed for findings: axios@c3f553c, flask@6a2f545, got@e3924aa.

corpus	precision	95% CI
got	15/15 = 100%	80–100%
axios	13/15 = 87%	62–96%
flask	11/15 = 73%	48–89%
held-out	39/45 = 87%	74–94%

Prediction held: below express's post-fix 100%, above 0.85 — 87% vs 88% on the tuned pair.

Strongest evidence: Suppressed checker 16/16. Pass 2 was written against JavaScript //
comments; the held-out corpus exercised it almost entirely on Python # type: ignore[...] forms
it had never seen. A rule fitted to its own examples doesn't transfer like that.

A new failure, exactly where the criteria aimed. debugger statement scored 0/4, all in
flask — Python has no debugger keyword, so every match was docstring prose or the CLI string
"--debugger/--no-debugger", and Python is lexical tier with no context gate. Criterion 4
demanded a Python repo because that tier had never been precision-tested. Fixed via statement
form + JS/TS restriction; flask 92 → 97.

Mutation testing then showed my first four tests were each satisfied by a different mechanism
— word boundary, extension gate, context gate — so none pinned the statement form.

---

HLD §14 metrics: two implemented, the third corrected (322a3d0)

HLD §14 names six metrics. Three existed — checked rather than assumed, the same way the
§8.3 tier ladder and the SARIF adapter turned out to be documentation only.

metric	before
cg_run_total, cg_findings_total, cg_verification_total	present
cg_cache_hit_ratio	missing — data source built two commits ago
cg_queue_depth	missing — one COUNT away
cg_stage_duration_seconds	missing — nothing captures the timings

Added gauge support and the two with real sources. Gauges are sampled at scrape, not stored —
a stored gauge serves whatever was true when some process last wrote it, which for "how full is
the queue" is worse than no answer. They're read in the route, not inside renderPrometheus,
because their sources sit above persistence in the layering.

queueDepth() counts queued only: a running job isn't backlog, and including in-flight work
makes a healthy queue with one busy worker look identical to a stalled one.

Found while reading the renderer: formatValue was
Number.isInteger(v) ? String(v) : String(v) — both arms identical. Worse, it emitted
Infinity, which the format rejects. Unreachable with only counters; reachable the instant a
ratio gauge divides by zero.

Then mutation testing showed my own NaN branch was inert — String(NaN) is already "NaN".
Only the infinities need translating. Removed; 5/5 after that.

HLD §14 now states what exists and what doesn't, and records cg_stage_duration_seconds plus
the Run record's stage timings as one piece of missing work — nothing instruments stage
boundaries, so neither can exist without that.

---

Stage instrumentation — the last HLD §14 gap (a393246)

The previous commit recorded cg_stage_duration_seconds and the Run record's stage timings as
one piece of missing work. This closes it.

timeStage lives in analysis-model beside PipelineContext — same seam. It records in a
finally, so a stage that threw still reports the time it burned; losing that is how a slow
stage that eventually errors becomes invisible.

Stages are named for the packages LLD §13 split out — scan, imports, dependencies,
detect, score, symbol-graph — so a slow run points at a package, not at "indexing".
That the split makes the metric legible is an argument for the split I hadn't anticipated.

stage	ms
symbol-graph	1,233
detect	822
scan	35
imports / dependencies / score	1 each

Sum 2,093ms against a 2.1s total — and these independently reproduce the manual profiling
from earlier in this branch (buildSymbolGraph ~1.35s, eslint ~624ms). Two methods, one answer.

Timings are returned, not pushed: analysis sits below persistence, so the worker that
owns the run row records them. Same reasoning as gauges being sampled in the route.

Real work in the renderer: _sum/_count are stored as counters — they're monotonic — but
they are two series of one family, and Prometheus rejects a duplicate # TYPE line per
family. Two counters is a malformed scrape, not a cosmetic slip.

No buckets, so no percentiles. Boundaries would have to come from evidence nobody has, and
arbitrary ones produce confident wrong quantiles. Said in the HELP text, where an operator
reading the scrape will actually see it.

4/4 mutants caught. HLD §14 is now fully implemented.

---

Two optimisations killed by measuring them (0f161cf)

Stage timings said symbol-graph is 59% of a run, so I went to optimise it. Both candidates
are dead, and the measurements are worth more than the code would have been.

phase	cost
symbol-graph stage	1,233ms (59% of 2,093ms)
├ TS program	~802ms
└ parsing all 329 TS files	58ms

1. Cache extracted symbols per content hash. Symbols are a pure function of file text —
content-cache.ts even says so. But parsing is 58ms; it was never the expense. Ceiling: ~58ms
of 2,093ms.

2. Make the typed program optional. ~923ms for 6 edges out of 2,549 (0.24%). Every number
says delete it. Deleting it is wrong: those 6 are method calls through a receiver, where the
fallback doesn't lose the edge — it emits a confidently wrong one. For Timeline, the
caller that would benefit most, that's the worst possible failure: an edge flipping between two
same-named functions across snapshots is phantom churn, a diff showing a change that never
happened.

What's actually new. typed-resolution.test.ts already recorded that no discriminating test
could be found — four candidates built, all four passed with the typed path disabled, left as
"an honest gap rather than a test that looks like proof and is not."

That gap is now closed. The missed shape is a method call through a receiver — the name never
appears in an import, so the fallback's import table has nothing to offer. Found by diffing
real-path against synthetic-base builds and reading the six edges that differed, not by
inventing candidates. That's why it worked where inventing four didn't.

Two process failures, both caught by tooling rather than by me:

• My first tests used an imported free function and survived deleting the whole program —
  the exact vacuity that file's comment warns about, reproduced while fixing it.
• I wrote them with cat > onto a path I hadn't read, destroying the existing file and its
  three tests. Caught only because the total dropped 955 → 954 while the file count held.

---

Program reuse: it works, it doesn't fit in 512MB (75f40c6)

The surviving incremental-graph idea — hold the ts.Program, pass it as oldProgram. Measured
both halves before building.

It works. With a persistent host returning identical SourceFile objects,
structureIsReused reaches Completely. Checker fully exercised, 12,643 resolutions, identical
answers every run:

run	program	checker	total
cold	558ms	567ms	1,125ms
reuse, 0 changed	6ms	312ms	318ms
reuse, 27/327 changed	15ms	356ms	371ms

~67% off the warm path — independently reproducing the ~26%-of-run ceiling estimated earlier by
a different method.

It doesn't fit.

	RSS	heap
baseline	213 MB	46 MB
program held + exercised	842 MB	528 MB

Target is a 512MB host (ADR-001, the --memory 512m gate, the constraint web-tree-sitter
already broke once). A real run peaks at 341.8 MiB. This doesn't overshoot the budget, it
multiplies it.

The distinction that decides it: a cold run allocates comparable memory transiently and
gives it back. Reuse never gives it back.

Status changes from "large" to "measured; blocked by the memory budget." Not deferred for
size — it's about a day's work. It's the one optimisation whose benefit is proven and whose cost
the product can't pay.

Two wrong measurements first. structureIsReused=0 on every run — a fresh host each time,
so reuse never engaged. Concluding "reuse doesn't help" from that is the same vacuity as the
four non-discriminating tests in the previous commit. Checking the flag caught it.

And because a documented verdict stops nobody: CI now reports peak memory as a number and
gates at 85%. The existing check enforced 512MB as a cliff — OOM death — which catches a
catastrophe and is blind to erosion. Verified locally both directions: 341.8 MiB → 66.8% passes
with 170 MiB headroom; 470 MiB → 91.8% fails.

---

CI had been red for 12 runs while I reported green (84a5e1a, d7f5bac, 949fa90)

I checked the actual CI status for the first time. main is green; this branch had failed
every run since it began. The Desktop (Electron) job — which this branch introduced along with
the desktop app — had never once passed, while every summary said "desktop 43/43". That figure
is the vitest unit suite. The Playwright E2E job is separate and no local gate ran it.

Three real defects behind it:

1. fs.pathExists test asserted the security boundary was broken. It expected true for the
runner's cwd. The service returns ok(false) for any ungranted path on purpose — "existence is
information too: probing outside the grant leaks the filesystem layout" — and at boot nothing is
granted. The app was right; the test required it to be wrong. Rewritten to assert the
boundary holds, which tests strictly more.

2. The Electron bundle and container image shipped the web test suite. Found only because a
doc guard failed for an unrelated reason: readme-claims counts test files by walking the tree,
and after building locally it counted 42 instead of 9. The extra 33 were
build/standalone/apps/web/tests — 292 KB riding into the .dmg, and into the image by the same
route. Next's standalone writer copies the app directory wholesale; the exclusion lists only ever
named data/. Fixed in both packaging paths, and the bundle verifier now fails the build if
a test suite reaches it — verified by removing the exclusion: FATAL: test suite leaked into the bundle.

3. The boot-screen test could not be deterministic in e2e — and my first fix was wrong about
why. I assumed polling was the problem and switched to recording navigations. CI answered:
no boot screen in navigations: ["http://127.0.0.1:45717/"]. The splash was gone before
Playwright's launch handshake handed over the window; the assertion was racing Playwright's
attach latency, not the app. Moved to window-manager.test.ts where the ordering is exact,
mutation-tested 4/4 — including a case that exists only because a mutant survived my first
version (a fresh window is the one state where a broken showLoading still looks correct).

E2E keeps what e2e can prove: the window is never left blank, true on either side of the swap.

All three jobs now green. The lesson isn't the defects — it's that a local gate list
assembled by the person being gated is not the gates the project runs, and I trusted mine for
twelve commits.