spexcode 0.2.8 → 0.4.0

package/README.md

@@ -9,6 +9,13 @@
   <a href="https://spexcode.net"><img alt="docs" src="https://img.shields.io/badge/docs-spexcode.net-8957e5"></a>
 </p>
 
+<p>
+  <img alt="Linux" src="https://img.shields.io/badge/Linux-supported-success?logo=linux&logoColor=white">
+  <img alt="macOS" src="https://img.shields.io/badge/macOS-supported-success?logo=apple&logoColor=white">
+  <img alt="Windows: via WSL2" src="https://img.shields.io/badge/Windows-WSL2-success">
+  <img alt="database: git" src="https://img.shields.io/badge/database-git-f05032?logo=git&logoColor=white">
+</p>
+
 </div>
 
 Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
@@ -23,16 +30,17 @@ implementation from drifting apart.
 English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
 Quick links: [the model](#the-model) · [quick start](#quick-start) ·
-[agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)
+[agents](#working-with-agents) · [eval](#measuring-behavior-eval) · [config](#configuration)
 
 ## The model
 
 <div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
 
 A spec node is a directory under `.spec/` containing a `spec.md`: frontmatter (title, status, a
-`code:` list of the files it governs) plus a prose body stating what that part of the system is
-supposed to do, right now. Nodes nest, so the tree mirrors how you think about the project rather
-than the file layout. The body has two parts. The short **raw source** states the intent; changing it takes explicit
+`code:` pointer to the file it governs, a `related:` list for files it references) plus a prose
+body stating what that part of the system is supposed to do, right now. Nodes nest, so the tree
+mirrors how you think about the project rather than the file layout. The body can split into two
+labelled parts. The short **raw source** states the intent; changing it takes explicit
 human approval (an agent can draft it, a human signs off). The **expanded spec** is the agent's
 detailed reading of that intent; it iterates freely but must always match the raw source.
 
@@ -41,7 +49,7 @@ detailed reading of that intent; it iterates freely but must always match the ra
 Two rules make this workable:
 
 1. **Git is the database.** There is no separate store. A node's version count is the number of
-   commits that touched its `spec.md`, its history view is `git log` on that file, and each version
+   commits that changed its `spec.md`, its history view is `git log` on that file, and each version
    is attributed to an agent session through a `Session:` commit trailer. This is also why a spec
    body always describes present intent and gets rewritten in place: changelog headings inside the
    body are banned (the linter enforces it), because git already keeps the history.
@@ -49,23 +57,23 @@ Two rules make this workable:
    code it justifies. When code moves without its spec, the linter flags it,
 
    ```
-   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   drift: spec-cli/src/graph.ts is 1 commit(s) ahead of spec 'graph-lean' (v12) — may be stale
    ```
 
    and keeps flagging until the spec catches up.
 
 ## The optimization loop
 
-Specs, commits, and yatsu readings compose into one loop. The spec is the loss function: it states what you want, and
-it's the half a human signs off on. Commits are the optimizer. **yatsu**, the measurement
-subsystem, is the eval: it scores how far live behavior currently sits from the spec, and the
+Specs, commits, and evals compose into one loop. The spec is the loss function: it states what you
+want, and it's the half a human signs off on. Commits are the optimizer. **eval**, the measurement
+subsystem, scores how far live behavior currently sits from the spec, and the
 score's history lives in git like everything else.
 
 <img src="docs/readme-loop.png" alt="the spec/code optimization loop">
 
 It also settles where the human stands day to day: nobody reads a neural net by staring at its
 weights, and between merge gates you don't have to stare at agent diffs either. Attention goes to
-the spec and the eval readings; the diff gets read once, at merge time.
+the spec and the evals; the diff gets read once, at merge time.
 
 ## Quick start
 
@@ -76,20 +84,20 @@ npm i -g spexcode        # installs the `spex` command
 cd your-repo
 spex init                # seeds .spec/, installs git hooks, materializes the agent contract
 spex serve               # API backend on :8787
-spex dashboard           # board UI on :5173, proxying to the backend
+spex serve ui            # dashboard on :5173, proxying to the backend
 ```
 
 `spex init` is additive. It works on any existing git repo and never overwrites your files: it
-creates a root `.spec/project/spec.md` and a starter `spexcode.json`, installs the pre-commit
-hooks, and writes a managed block into `CLAUDE.md`/`AGENTS.md` so any agent working in the repo
+creates a root `.spec/project/spec.md` and a starter `spexcode.json`, installs the git hooks, and
+writes a managed block into `CLAUDE.md`/`AGENTS.md` so any agent working in the repo
 discovers the workflow on its own.
 
 Then grow the tree:
 
 1. Edit `.spec/project/spec.md` to describe the project.
-2. Add child nodes for the parts you want governed, each with a `code:` list pointing at existing
-   files.
-3. Run `spex lint`. Coverage warnings list the source files no spec claims yet; that list is your
+2. Add child nodes for the parts you want governed, each with a `code:` entry pointing at an
+   existing file (`related:` for the files it touches but doesn't own).
+3. Run `spex spec lint`. Coverage warnings list the source files no spec claims yet; that list is your
    adoption TODO.
 
 You are not expected to hand-author all of this. The intended workflow is to have an agent do most
@@ -97,7 +105,7 @@ of the spec writing; `spex guide spec` prints the exact file format it needs.
 [Getting started](https://spexcode.net/getting-started/) on the docs site walks the setup end to
 end.
 
-<img src="docs/readme-board.png" alt="dashboard screenshot">
+<img src="docs/readme-graph.png" alt="dashboard screenshot">
 
 *SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
 
@@ -107,7 +115,7 @@ This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/cla
 on the machine.
 
 ```sh
-spex new "make the settings page remember the last tab" --node settings
+spex session new "make the settings page remember the last tab" --node settings
 ```
 
 launches a worker session in its own worktree on branch `node/settings-…`. The `--node` flag (or a
@@ -123,9 +131,9 @@ themselves use when they delegate.
 You supervise from outside — on the board, or with the same commands your agent uses:
 
 ```sh
-spex watch              # stream session transitions: launched / review / done / needs-input ...
-spex review settings    # commits ahead of trunk, merge-base diff, typecheck/lint gates
-spex merge settings     # gated merge into the trunk
+spex session watch              # stream session transitions: launched / review / done / needs-input ...
+spex session review settings    # commits ahead of trunk, merge-base diff, merge-conflict/lint gates
+spex session merge settings     # gated merge into the trunk
 spex session close settings
 ```
 
@@ -138,28 +146,29 @@ hook stamps the attribution; the materialized contract block carries the rest, s
 prompt stays task-only. More on this mode of working:
 [working with agents](https://spexcode.net/working-with-agents/).
 
-## Measuring behavior: yatsu
+## Measuring behavior: eval
 
-yatsu — short for **You As The Stupid User** — is the measuring half of
-[the loop](#the-optimization-loop): you measure behavior from the product's real surface, the way a
-clueless real end user would touch it, not through an internal helper or shortcut that makes the
-proof easy. A spec says what a part should do; a
-`yatsu.md` beside it says how to check. Each scenario is a plain description plus an expected
-result. yatsu itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
+eval is the measuring half of
+[the loop](#the-optimization-loop), built on the YATU discipline (**You As The User**): you measure
+behavior from the product's real surface, the way a real end user would touch it, not through an
+internal helper or shortcut that makes the
+proof easy. A spec says what a part should do; an
+`eval.md` beside it says how to check. Each scenario is a plain description plus an expected
+result. eval itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
 a test file, a real browser, or just clicking through by hand and screenshotting. It compares
-actual to expected and files the reading with evidence:
+actual to expected and files the eval with evidence:
 
 ```sh
-spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
+spex eval add settings --scenario remembers-tab --pass --image evidence.png
 ```
 
-Readings live in a git-tracked ndjson next to the spec, so measurements get the same attribution
-and history as spec versions. Bug fixes are expected to bracket: file a failing reading that
-reproduces the bug, fix, then file a passing reading on the same scenario.
+Evals live in a git-tracked ndjson next to the spec, so measurements get the same attribution
+and history as spec versions. Bug fixes are expected to bracket: file a failing eval that
+reproduces the bug, fix, then file a passing eval on the same scenario.
 
 <img src="docs/readme-eval.png" alt="eval view screenshot">
 
-*The eval view: scenario readings on the left; the selected reading's expected result, staleness,
+*The eval view: scenario evals on the left; the selected eval's expected result, staleness,
 and recorded video evidence in the middle.*
 
 ## What's in the repo
@@ -168,14 +177,14 @@ and recorded video evidence in the middle.*
 |---|---|
 | `spec-cli` | The `spex` CLI and the HTTP backend (Hono, runs via tsx, no build step). Reads `.spec` and git live; owns the session state machine and the linter. |
 | `spec-dashboard` | React board: the node graph, per-node spec/history/issues panes, and a real terminal onto each live agent session. |
-| `spec-yatsu` | Scenario definitions, readings, evidence blobs. |
-| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
+| `spec-eval` | Scenario definitions, evals, evidence. |
+| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub and GitLab drivers today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
 
 ## The linter
 
-`spex lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
+`spex spec lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
 
-- **integrity** (error): a `code:` path that doesn't exist
+- **integrity** (error): a `code:` or `related:` path that doesn't exist
 - **living** (error): a changelog heading in a spec body
 - **altitude** (warn): a body that slid from contract prose into an implementation dump. The usual
   smell is a numbered step list or a wall of function names; this rule is why spec bodies stay
@@ -183,20 +192,23 @@ and recorded video evidence in the middle.*
 - **coverage** (warn): unclaimed source files
 - **drift** (warn): governed code changed after its spec's last version, derived live from git
 
+plus naming and ownership rules (`one-govern`, `id-format`, `mention` as errors; `breadth`,
+`related-drift`, `owners`, `confusable-id` as warns) — `spex guide spec` lists them all.
+
 ## Configuration
 
 `spexcode.json` (committed, portable: layout, lint budgets, dashboard identity, launcher names) and
-`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, plus a `private: true`
-overlay for repos you use but don't own) cover every setting. No `spex config set` yet: you edit the two files by hand (or ask your agent
-to), and `spex guide config` documents every field. The other
-manuals are `spex guide` (the workflow), `spex guide spec`, and `spex guide yatsu`; `spex help`
-maps the commands.
+`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, cert paths) cover every
+setting. There is no imperative settings verb: you edit the two files by hand (or ask your agent
+to), and `spex guide settings` documents every field. The other
+manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, and
+`spex guide footprint`; `spex help` maps the commands.
 
 ## Contributing
 
 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) gets you from a clone to a first merged change.
 [`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) has the full mechanics of the node model and the
-reflexive config system.
+reflexive plugin system.
 
 ## Credit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.8",
+  "version": "0.4.0",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -13,8 +13,8 @@
     "spec-cli/bin",
     "spec-cli/templates",
     "spec-cli/hooks",
-    "spec-yatsu/src",
-    "!spec-yatsu/src/**/*.test.ts",
+    "spec-eval/src",
+    "!spec-eval/src/**/*.test.ts",
     "spec-forge/src",
     "!spec-forge/src/**/*.test.ts",
     "spec-dashboard/dist",

package/spec-cli/bin/spex.mjs

@@ -17,9 +17,9 @@ const cli = join(pkg, 'src', 'cli.ts')
 // while a merge conflict is being resolved in the checkout that hosts it, the source holds conflict
 // markers and tsx dies with a raw esbuild stacktrace — on EVERY call, including the Stop hook and an
 // agent's `spex session done`. Catch that one transient state up front: scan the source trees the CLI
-// imports (spec-cli ←→ spec-yatsu ←→ spec-forge), and if any file carries a marker, print one actionable
+// imports (spec-cli ←→ spec-eval ←→ spec-forge), and if any file carries a marker, print one actionable
 // line and exit 75 (EX_TEMPFAIL: transient, retry) instead of spawning tsx into the stacktrace.
-const srcRoots = [join(pkg, 'src'), join(pkg, '..', 'spec-yatsu', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+const srcRoots = [join(pkg, 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
 const conflicted = srcRoots.flatMap((root) => {
   if (!existsSync(root)) return []
   return readdirSync(root, { recursive: true })

package/spec-cli/hooks/dispatch.sh

@@ -13,7 +13,7 @@
 #
 # The old (1) GATE — an auto-materialize when the config content-hash moved — is RETIRED ([[commit-surgery]]):
 # a harness event is never a materialize trigger; the materialize anchors are git-native only (spex verbs,
-# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .config edits are
+# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .plugins edits are
 # git-transactional: they take effect at the commit/checkout/merge that carries them, like any other source.
 set -u
 # args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the

package/spec-cli/hooks/harness.sh

@@ -59,15 +59,35 @@ hp_field() {
 # the session id from a payload (both harnesses use session_id).
 # Codex hooks run inside ONE shared per-project app-server. That process can inherit the FIRST launched
 # session's SPEXCODE_SESSION_ID, so on codex the payload session_id (the acting thread id) must win and then
-# hp_store_dir aliases it to the governed record. Claude's payload id already equals its governed record id,
-# so preferring SPEXCODE_SESSION_ID there preserves the launcher's pinned id path.
+# hp_store_dir aliases it to the governed record. Claude's payload id equals its governed record id, so the
+# PAYLOAD is the acting identity; the inherited env is only a fallback for payload-less events. Env-first was
+# a live bug: a nested subagent (Task tool) inherits the parent's SPEXCODE_SESSION_ID, so with env winning,
+# every child tool call fired mark-active against the PARENT's record — the parent read `working` forever and
+# every park/done declaration was clobbered within seconds (measured). Same staleness class the codex branch
+# already guards against (payload-first below); claude now follows the same rule.
 hp_session_id() {
+  local pid
   case "$SPEXCODE_HARNESS" in
     codex) hp_field "$1" session_id ;;
-    *)     printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}" ;;
+    *)     pid=$(hp_field "$1" session_id); printf '%s' "${pid:-$SPEXCODE_SESSION_ID}" ;;
   esac
 }
 
+# is THIS payload a tool call executed by an IN-PROCESS SUBAGENT (Claude's Task tool — a sub-conversation
+# inside the SAME harness process) rather than the session's own top-level agent? The subagent's payload
+# carries the PARENT's session_id/transcript_path (measured live, claude 2.1.207), so hp_session_id cannot
+# tell them apart — but the harness stamps every subagent-executed call with a top-level `agent_id`
+# (+ `agent_type`) field that a top-level call NEVER carries. The check is structural, never a heuristic:
+# scan ONLY the payload prefix before the first `"tool_input"` (every harness-stamped top-level field
+# precedes tool_input), and require the key shape `"agent_id":`. Inside a JSON string value every quote is
+# escaped (\"), so a bare-quoted `"agent_id"` followed by a colon in that prefix can only be the harness's
+# own stamp — a tool parameter literally NAMED agent_id (an MCP tool) sits inside tool_input, past the
+# truncation, and file/prompt content can never fake an unescaped quote. Codex payloads carry no such field
+# (its verified field set) so this never matches there. Echoes "1" when yes, else nothing.
+hp_is_subagent() {
+  printf '%s' "${1%%\"tool_input\"*}" | grep -q '"agent_id"[[:space:]]*:' && printf 1
+}
+
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
 # worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
@@ -114,7 +134,7 @@ hp_store_dir() {
 
 # the TOOLCHAIN's own version fingerprint — the toolchain side of the content key. The materialized artifacts
 # are a function of (config content, toolchain), so a TOOLCHAIN update must move the key too, or an updated
-# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .config (the field
+# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .plugins (the field
 # lesson: a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the
 # package dir (moves exactly when the toolchain's content moves, not on every repo commit); an npm install
 # (no .git) answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's
@@ -127,7 +147,7 @@ hp_toolchain_version() {
 }
 
 # the deterministic content fingerprint of EVERYTHING the materialize is a function of: the EDITABLE config
-# roots (.config + config md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
+# roots (.plugins + plugin-system md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
 # spexcode.local.json — the `harnesses` set materialize reads via readConfig(mainCheckout)), and the
 # toolchain version above. Since the dispatch-gate retired ([[commit-surgery]] — materialize anchors on
 # git-native events only), this is a FRESHNESS STAMP materialize records after each pass, a diagnostic
@@ -138,7 +158,7 @@ hp_config_hash() {
   gcd=$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
     || gcd=$(realpath "$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
   { hp_toolchain_version
-    find .spec/*/.config .spec/*/config \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
+    find .spec/*/.plugins .spec/*/plugin-system \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
       | sort -z | xargs -0 cat 2>/dev/null
     [ -n "$gcd" ] && cat "$(dirname "$gcd")/spexcode.json" "$(dirname "$gcd")/spexcode.local.json" 2>/dev/null
   } | sha256sum | cut -d' ' -f1

package/spec-cli/src/anchors.ts

@@ -0,0 +1,300 @@
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { gitA, type DriftIndex, ancestorsOf, inAncestors, ackCoverFor } from './git.js'
+
+// ---- the anchor vocabulary ([[code-anchor]]) ----
+// A spec's `code:` entry may pin ONE named unit: `path#symbol` (`#Class.method` for a class method).
+// Everything below the entry parse splits into two layers:
+//   - the LANGUAGE SEAM: pure extractors (content, filename) -> Unit[] — no git, no cache, no fs.
+//     Each extension maps to exactly ONE designated extractor; there is NO cross-tier fallback.
+//   - the LANGUAGE-AGNOSTIC ENGINE: blob-oid memo, anchor resolution (dead/ambiguous), diff-hunk ∩
+//     unit-range intersection over the drift window. It never knows which language it is measuring.
+
+export type Unit = { name: string; kind: string; start: number; end: number; typeOnly?: boolean }
+
+export type Extractor = {
+  id: string
+  claims(ext: string): boolean
+  // true = usable here. A string is WHY it cannot run — lint turns that into an ERROR with the repair
+  // entrypoint (never a silent or degraded pass): the designated extractor either runs or the anchor
+  // is unverifiable.
+  ready(): true | string
+  // PURE function of its arguments (importable by an external benchmark/scorer as-is). Throws when the
+  // content cannot be parsed — the caller maps that to a conservative verdict, never a silent skip.
+  extract(content: string, filename: string): Unit[]
+}
+
+export type CodeEntry = { path: string; anchor: string | null }
+export function parseCodeEntry(raw: string): CodeEntry {
+  const i = raw.indexOf('#')
+  if (i < 0) return { path: raw, anchor: null }
+  return { path: raw.slice(0, i), anchor: raw.slice(i + 1).trim() || null }
+}
+
+// ---- extractor: ts-ast (the designated extractor for the JS family) ----
+// Parse-only via the HOST project's own typescript (resolved from the repo root, walking up like any
+// require) — never a bundled copy, so the parse matches what the project itself compiles with. Not
+// resolvable => ready() returns the repair entrypoint and lint ERRORS (no regex fallback for JS).
+const JS_EXTS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts'])
+
+export function tsAstExtractor(root: string): Extractor {
+  let ts: any | null | undefined // undefined = unprobed; null = unresolvable
+  let readiness: true | string | undefined
+  const probe = () => {
+    if (ts !== undefined) return
+    try { ts = createRequire(join(root, 'package.json'))('typescript') } catch { ts = null }
+  }
+  return {
+    id: 'ts-ast',
+    claims: (ext) => JS_EXTS.has(ext),
+    ready() {
+      if (readiness !== undefined) return readiness
+      probe()
+      if (!ts) return (readiness = `typescript is not resolvable from ${root} — anchors on JS-family files need the host project's typescript: run 'npm i -D typescript', or remove the #anchor`)
+      // resolvability is not usability: typescript@7 (the Go rewrite) may resolve yet not expose the JS
+      // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse — an incompatible
+      // host typescript is a loud error, never a silent pass or downgrade.
+      try {
+        const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+        if (!sf?.statements?.length || sf.parseDiagnostics?.length) throw new Error('probe parse failed')
+        readiness = true
+      } catch {
+        readiness = `host typescript (v${ts?.version ?? 'unknown'}) resolves but its createSourceFile API is unusable (a TS7/Go build?) — pin 'npm i -D typescript@5', or remove the #anchor`
+      }
+      return readiness
+    },
+    extract(content, filename) {
+      probe()
+      if (!ts) throw new Error('ts-ast extractor is not ready (typescript unresolvable)')
+      const kind = /\.(tsx)$/.test(filename) ? ts.ScriptKind.TSX
+        : /\.(jsx)$/.test(filename) ? ts.ScriptKind.JSX
+        : /\.(ts|mts|cts)$/.test(filename) ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS
+      const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, true, kind)
+      // parse-only gate: a file that does not parse yields GARBAGE units (a shell script's `x=$(...)`
+      // parses as a const) — throw so the caller renders an honest "cannot parse" verdict instead.
+      if (sf.parseDiagnostics?.length) throw new Error(`${filename} does not parse as ${ts.ScriptKind[kind]} (${sf.parseDiagnostics.length} syntax error(s))`)
+      const line = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1
+      const units: Unit[] = []
+      const push = (name: string, ukind: string, node: any, typeOnly = false) =>
+        units.push({ name, kind: ukind, start: line(node.getStart(sf)), end: line(node.end), ...(typeOnly ? { typeOnly } : {}) })
+      for (const st of sf.statements) {
+        if (ts.isFunctionDeclaration(st)) push(st.name ? st.name.text : '(default)', 'function', st)
+        else if (ts.isClassDeclaration(st)) {
+          const cname = st.name ? st.name.text : '(default)'
+          push(cname, 'class', st)
+          for (const m of st.members) {
+            if ((ts.isMethodDeclaration(m) || ts.isConstructorDeclaration(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) && m.body) {
+              const mname = ts.isConstructorDeclaration(m) ? 'constructor' : (m.name && ts.isIdentifier(m.name) ? m.name.text : '(computed)')
+              push(`${cname}.${mname}`, 'method', m)
+            }
+          }
+        } else if (ts.isVariableStatement(st)) {
+          for (const d of st.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name)) continue // destructuring — not anchorable by one name
+            const fn = d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))
+            // range = the whole statement (multi-declarator lines co-move; each name shares the range)
+            units.push({ name: d.name.text, kind: fn ? 'const-fn' : 'const-data', start: line(st.getStart(sf)), end: line(st.end) })
+          }
+        } else if (ts.isEnumDeclaration(st)) push(st.name.text, 'enum', st)
+        else if (ts.isInterfaceDeclaration(st)) push(st.name.text, 'interface', st, true)
+        else if (ts.isTypeAliasDeclaration(st)) push(st.name.text, 'type', st, true)
+      }
+      return units
+    },
+  }
+}
+
+// ---- extractor: heuristic(langSpec) — a generic regex engine fed LANGUAGE DATA, not language branches ----
+// The designated extractor for languages described by a LangSpec row; adding a language = adding a data
+// row + a registry entry (never a new engine). The JS family is deliberately NOT routed here (its
+// designated extractor is ts-ast above); JS_LANG_R5B below exists as the validated reference row for the
+// engine's shape and for the external benchmark to score.
+export type LangSpec = {
+  id: string
+  extensions: string[]
+  // column-0 declaration patterns; capture group 1 = the unit name (or the declarator list when declList)
+  decls: { re: RegExp; kind: string; typeOnly?: boolean; classOpener?: boolean; declList?: boolean }[]
+  // class-member pattern, active while inside a classOpener's balanced-bracket body (name -> Class.name)
+  member?: { re: RegExp; blacklist?: RegExp }
+  // a column-0 line matching this ENDS the previous unit (comment-aware so trailing comment blocks
+  // attach to the NEXT unit, not the previous one)
+  boundary: RegExp
+}
+
+const balance = (s: string) => { let n = 0; for (const ch of s) { if ('([{'.includes(ch)) n++; else if (')]}'.includes(ch)) n-- } return n }
+// split a declarator-list head on top-level commas: `COLS = 220, ROWS = 50` -> [COLS, ROWS]
+function declNames(head: string): string[] {
+  let d = 0, seg = ''
+  const segs: string[] = []
+  for (const ch of head) {
+    if ('([{<'.includes(ch)) d++
+    else if (')]}>'.includes(ch)) d--
+    if (ch === ',' && d === 0) { segs.push(seg); seg = '' } else seg += ch
+  }
+  segs.push(seg)
+  return segs.map((s) => s.match(/^\s*([A-Za-z_$][\w$]*)\s*(?::|=|$)/)?.[1]).filter((x): x is string => !!x)
+}
+
+export function heuristicExtractor(spec: LangSpec): Extractor {
+  return {
+    id: spec.id,
+    claims: (ext) => spec.extensions.includes(ext),
+    ready: () => true,
+    extract(content) {
+      const lines = content.split('\n')
+      const units: Unit[] = []
+      let cls: string | null = null, depth = 0
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i]
+        if (cls) {
+          const m = spec.member && l.match(spec.member.re)
+          if (m && !spec.member!.blacklist?.test(m[1])) units.push({ name: `${cls}.${m[1]}`, kind: 'method', start: i + 1, end: i + 1 })
+          depth += balance(l)
+          if (depth <= 0) cls = null
+          continue
+        }
+        for (const d of spec.decls) {
+          const m = l.match(d.re)
+          if (!m) continue
+          for (const name of d.declList ? declNames(m[1]) : [m[1]])
+            units.push({ name, kind: d.kind, start: i + 1, end: i + 1, ...(d.typeOnly ? { typeOnly: true } : {}) })
+          if (d.classOpener) { cls = m[1]; depth = balance(l) }
+          break
+        }
+      }
+      // R5b ranges: a unit ends before the next column-0 boundary line; a method is also capped by the
+      // next unit's start (methods sit inside their class's indentation, below boundary's radar).
+      const bset: number[] = []
+      for (let i = 0; i < lines.length; i++) if (spec.boundary.test(lines[i])) bset.push(i + 1)
+      const starts = units.map((u) => u.start).sort((a, b) => a - b)
+      for (const u of units) {
+        const nb = bset.find((b) => b > u.start)
+        let end = nb ?? lines.length + 1
+        if (u.kind === 'method') { const ns = starts.find((x) => x > u.start); if (ns && ns < end) end = ns }
+        u.end = Math.max(u.start, end - 1)
+      }
+      return units
+    },
+  }
+}
+
+// The validated JS-family reference row (R5b: name precision 99.7% / recall 100% / range 98.9% on the
+// 41-file oracle) — NOT registered for JS (ts-ast is designated); kept as the engine's reference shape
+// and the benchmark's scoring subject.
+export const JS_LANG_R5B: LangSpec = {
+  id: 'heuristic-js',
+  extensions: [...JS_EXTS],
+  decls: [
+    { re: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/, kind: 'function' },
+    { re: /^(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/, kind: 'class', classOpener: true },
+    { re: /^(?:export\s+)?(?:declare\s+)?enum\s+([A-Za-z_$][\w$]*)/, kind: 'enum' },
+    { re: /^(?:export\s+)?(?:declare\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: 'interface', typeOnly: true },
+    { re: /^(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][\w$]*)/, kind: 'type', typeOnly: true },
+    { re: /^(?:export\s+)?(?:const|let|var)\s+(.+)$/, kind: 'const', declList: true },
+  ],
+  member: {
+    re: /^\s+(?:(?:public|private|protected|static|readonly|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(/,
+    blacklist: /^(if|for|while|switch|return|catch|new|await|typeof|throw|else|do)$/,
+  },
+  boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
+}
+
+// ---- registry: extension -> its ONE designated extractor ----
+// The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
+// heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
+// config — whatever the implementation needs rides inside its own factory, never in the registry.
+export function extractors(root: string): Extractor[] {
+  return [tsAstExtractor(root)]
+}
+// first claiming extractor IS the designation (the registry order defines it); null = no anchor support
+// for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
+export function extractorFor(regs: Extractor[], ext: string): Extractor | null {
+  return regs.find((x) => x.claims(ext)) ?? null
+}
+export const extOf = (path: string): string => {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  const dot = base.lastIndexOf('.')
+  return dot > 0 ? base.slice(dot + 1) : ''
+}
+
+// ---- anchor resolution (language-agnostic) ----
+export type AnchorResolution = { ok: Unit } | { dead: true } | { ambiguous: number }
+export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
+  const hits = units.filter((u) => u.name === symbol)
+  if (!hits.length) return { dead: true }
+  if (hits.length > 1) return { ambiguous: hits.length }
+  return { ok: hits[0] }
+}
+
+// ---- the historical hit engine (language-agnostic; batch short-lived git, no resident process) ----
+
+// units of a file AS OF a commit, memoized by (blob oid, extractor id) — a blob is immutable, so the
+// memo never invalidates; distinct file versions in a window are few. 'absent' = no blob at that commit;
+// 'unparseable' = the extractor rejected that version's content (the caller treats it conservatively).
+type BlobUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
+const unitMemo = new Map<string, BlobUnits>()
+const MEMO_MAX = 4096
+async function unitsAt(root: string, commit: string, path: string, x: Extractor): Promise<BlobUnits> {
+  const oid = (await gitA(['-C', root, 'rev-parse', `${commit}:${path}`])).trim()
+  if (!oid) return { absent: true }
+  const key = `${oid}\0${x.id}`
+  const hit = unitMemo.get(key)
+  if (hit) return hit
+  const text = await gitA(['-C', root, 'cat-file', 'blob', oid])
+  let v: BlobUnits
+  try { v = { units: x.extract(text, path) } } catch (e: any) { v = { unparseable: e?.message ?? String(e) } }
+  if (unitMemo.size >= MEMO_MAX) unitMemo.clear()
+  unitMemo.set(key, v)
+  return v
+}
+
+// post-image line ranges of one commit's diff to one file (`@@ -a,b +c,d @@`, --unified=0). d>0 → lines
+// c..c+d-1 changed; d==0 (pure deletion) → the point line after which content vanished. Immutable per
+// (commit, file), memoized.
+const hunkMemo = new Map<string, [number, number][]>()
+async function hunksAt(root: string, commit: string, path: string): Promise<[number, number][]> {
+  const key = `${commit}\0${path}`
+  const hit = hunkMemo.get(key)
+  if (hit) return hit
+  const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '--unified=0', '--format=', commit, '--', path])
+  const ranges: [number, number][] = []
+  for (const m of out.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+    const c = +m[1], d = m[2] === undefined ? 1 : +m[2]
+    ranges.push(d > 0 ? [c, c + d - 1] : [Math.max(1, c), Math.max(1, c)])
+  }
+  if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
+  hunkMemo.set(key, ranges)
+  return ranges
+}
+
+// the drift window of an anchored file: every commit to `path` not reachable from the spec's version
+// and not covered by a valid Spec-OK ack — the SAME set driftFor counts, exposed as commits so the
+// anchor engine can probe each one. (fileCommits comes from a --name-only walk, which lists no files
+// for merge commits — the window is non-merge by construction.)
+export function windowCommits(idx: DriftIndex, sinceHash: string, path: string): string[] {
+  if (!sinceHash) return []
+  const base = ancestorsOf(idx, sinceHash)
+  if (!base) return []
+  const cover = ackCoverFor(idx, sinceHash)
+  return (idx.fileCommits.get(path) ?? []).filter((h) => !inAncestors(idx, base, h) && !cover.some((a) => inAncestors(idx, a, h)))
+}
+
+// which window commits TOUCHED the anchored unit: the commit's --unified=0 hunks intersect the unit's
+// line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later renamed
+// or moved still attribute correctly). A version whose content the extractor cannot parse is a
+// CONSERVATIVE hit (`unparseable` set) — over-warn, never silently skip.
+export type AnchorHit = { commit: string; unparseable?: string }
+export async function anchorHitCommits(root: string, win: string[], path: string, symbol: string, x: Extractor): Promise<AnchorHit[]> {
+  const hits: AnchorHit[] = []
+  for (const c of win) {
+    const at = await unitsAt(root, c, path, x)
+    if ('absent' in at) continue // file not in that commit's tree — nothing of the anchor to touch
+    if ('unparseable' in at) { hits.push({ commit: c, unparseable: at.unparseable }); continue }
+    const ranges = at.units.filter((u) => u.name === symbol)
+    if (!ranges.length) continue // unit didn't exist under this name at that commit
+    const hunks = await hunksAt(root, c, path)
+    if (hunks.some(([a, b]) => ranges.some((u) => a <= u.end && u.start <= b))) hits.push({ commit: c })
+  }
+  return hits
+}