@afokapu/atdd-bun 0.10.55 → 0.10.57

package/detectors/bun_interlocking_coverage/_shared/interlocking.mjs

@@ -364,7 +364,7 @@ export function productionExecutionProofs(text, file, croot) {
     const named = [...receivers].some((name) => receiver.trim().endsWith(name));
     if (!direct && !named) continue;
     const after = text.slice((m.index ?? 0) + whole.length);
-    const execute = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).exec(after);
+    const execute = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).exec(after);
     const anonymous = new RegExp(`new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).test(after);
     if (execute || anonymous) proofs.push({ resolution, execution: execute?.[1] ?? null });
   }
@@ -420,15 +420,64 @@ export function stationMasterExecutionProof(text, action) {
   return seen.has(PROD_INTERLOCKING) && seen.has(PROD_TRAIN) && assertsExpression(text, `${escaped(result)}(?:\\.[A-Za-z_$][\\w$]*)?`);
 }
 
-// HTTP/module entrypoints do not expose a StationMaster instance to the test. Their equivalent
-// witness is an asserted dispatch result plus a module body that resolves and executes the selected
-// train; this keeps an end-to-end smoke from having to pierce the public boundary for private fields.
-export function stationModuleExecutionProof(text, stationText) {
-  if (!stationText || !new RegExp(`new\\s+${PROD_INTERLOCKING}\\b`).test(stationText) ||
-    !/\.resolveTrain\s*\(/.test(stationText) || !new RegExp(`new\\s+${PROD_TRAIN}\\b`).test(stationText) ||
-    !/\.execute\s*\(/.test(stationText)) return false;
-  const call = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*await\\s+(?:${ident}\\.)?(?:dispatch|handleAction|executeAction)\\s*\\(`).exec(text);
-  return Boolean(call && assertsExpression(text, escaped(call[1])));
+function balancedBlock(text, open) {
+  let depth = 0, quote = null;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i], next = text[i + 1];
+    if (quote) {
+      if (c === "\\") { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") { quote = c; continue; }
+    if (c === "/" && next === "/") { i = text.indexOf("\n", i + 2); if (i < 0) return null; continue; }
+    if (c === "/" && next === "*") { const end = text.indexOf("*/", i + 2); if (end < 0) return null; i = end + 1; continue; }
+    if (c === "{") depth++;
+    if (c === "}" && --depth === 0) return text.slice(open + 1, i);
+  }
+  return null;
+}
+
+function exportedActionBody(text, name) {
+  const n = escaped(name);
+  const headers = [
+    new RegExp(`\\bexport\\s+(?:async\\s+)?function\\s+${n}\\s*\\([^)]*\\)\\s*\\{`, "g"),
+    new RegExp(`\\bexport\\s+(?:const|let|var)\\s+${n}\\s*=\\s*(?:async\\s*)?\\([^)]*\\)\\s*=>\\s*\\{`, "g"),
+  ];
+  for (const header of headers) {
+    const match = header.exec(text);
+    if (match) return balancedBlock(text, (match.index ?? 0) + match[0].lastIndexOf("{"));
+  }
+  return null;
+}
+
+function exportedActionReturnsProductionExecution(stationText, action) {
+  const body = exportedActionBody(stationText, action);
+  if (!body) return false;
+  const receivers = productionReceivers(stationText);
+  const resolutions = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*([^\\n]{0,240}?)\\.resolveTrain\\s*\\(`, "g");
+  for (const m of body.matchAll(resolutions)) {
+    const [whole, resolution, receiver] = m;
+    const direct = new RegExp(`new\\s+${PROD_INTERLOCKING}\\b`).test(receiver);
+    const named = [...receivers].some((name) => receiver.trim().endsWith(name));
+    if (!direct && !named) continue;
+    const after = body.slice((m.index ?? 0) + whole.length);
+    const directReturn = new RegExp(`\\breturn\\s+(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).test(after);
+    if (directReturn) return true;
+    const execution = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).exec(after)?.[1];
+    if (execution && new RegExp(`\\breturn\\s+(?:await\\s+)?${escaped(execution)}\\s*;?`).test(after)) return true;
+  }
+  return false;
+}
+
+// HTTP/module entrypoints do not expose a StationMaster instance to the test. The asserted result
+// must therefore come from the SAME exported action the test invokes, and that action's own return
+// path must resolve then execute the selected train. Module-wide runner tokens are not evidence.
+export function stationModuleExecutionProof(text, stationText, action) {
+  if (!stationText) return false;
+  const call = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*await\\s+(?:${ident}\\.)?(dispatch|handleAction|executeAction)\\s*\\(\\s*["']${escaped(action)}["']`).exec(text);
+  return Boolean(call && assertsExpression(text, `${escaped(call[1])}(?:\\.[A-Za-z_$][\\w$]*)?`) &&
+    exportedActionReturnsProductionExecution(stationText, call[2]));
 }
 
 // Bun's native `expect` vocabulary provides a compact mutation witness: exact ordered equality

package/detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs

@@ -72,7 +72,7 @@ for (const scanRoot of roots) {
 
       const semantic = hasProductionExecutionProof(text, file, croot) ||
         records.some((rec) => rec.actions.some((action) => stationMasterExecutionProof(text, action))) ||
-        (drivesStationMaster(text) && stationModuleExecutionProof(text, station));
+        (drivesStationMaster(text) && records.some((rec) => rec.actions.some((action) => stationModuleExecutionProof(text, station, action))));
       if (!semantic) {
         violations.push(
           mk(

package/detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs

@@ -21,10 +21,12 @@ import {
   PROD_INTERLOCKING,
   PROD_TRAIN,
   stationMasterExecutionProof,
+  stationModuleExecutionProof,
   rel,
   mk,
   writeReport,
 } from "../_shared/interlocking.mjs";
+import { join } from "node:path";
 
 const RULE = "tester.bun.interlocking-smoke-coverage-for-station-master";
 const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
@@ -34,10 +36,11 @@ const violations = [];
 // it under the smoke rules (no substituted collaborators, observable outcome). A local E2E that names the action beside
 // the runners is not a smoke and no longer clears the rule (FWS #TzSCGS5ajYhP).
 const SMOKE_PHASE = /^\s*\/\/\s*Phase:\s*SMOKE\b/m;
-function actionSmokeCovered(action, e2eFiles) {
+function actionSmokeCovered(action, e2eFiles, stationModule) {
   return e2eFiles.some(
     ({ raw, text: t }) =>
-      SMOKE_PHASE.test(raw) && tokenCovered(action, t) && STATION_MASTER.test(t) && t.includes(PROD_INTERLOCKING) && t.includes(PROD_TRAIN) && stationMasterExecutionProof(t, action),
+      SMOKE_PHASE.test(raw) && tokenCovered(action, t) && STATION_MASTER.test(t) && t.includes(PROD_INTERLOCKING) && t.includes(PROD_TRAIN) &&
+        (stationMasterExecutionProof(t, action) || stationModuleExecutionProof(t, stationModule, action)),
   );
 }
 
@@ -47,11 +50,14 @@ for (const scanRoot of roots) {
       .map((f) => ({ file: f, rec: parseInterlocking(readText(f)) }))
       .filter((x) => x.rec);
     const e2eTexts = e2eFiles(croot).map((f) => { const raw = readText(f); return { raw, text: maskComments(raw) }; });
+    const stationModule = ["server.ts", join("src", "server.ts")]
+      .map((name) => readText(join(croot, name)))
+      .find((text) => text && text.includes(PROD_INTERLOCKING) && text.includes(PROD_TRAIN));
 
     for (const { file, rec } of records) {
       if (!rec.exposed) continue;
       for (const action of rec.actions) {
-        if (actionSmokeCovered(action, e2eTexts)) continue;
+        if (actionSmokeCovered(action, e2eTexts, stationModule)) continue;
         const [line, src] = lineOf(rec.rawText, new RegExp("^\\s*-\\s*['\"]?" + action + "['\"]?\\s*$"));
         violations.push(
           mk(

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/e2e/smoke/resolve-match.smoke.test.ts

@@ -0,0 +1,12 @@
+// Phase: SMOKE
+import { expect, test } from "bun:test";
+import { dispatch } from "../../src/server";
+import { InterlockingRunner } from "../../src/trains/interlocking";
+import { TrainRunner } from "../../src/trains/runner";
+
+test("inert runner helper does not prove functional Station Master dispatch", async () => {
+  const result = await dispatch("resolve_match", { allPlayersVoted: true });
+  expect(result.selectedTrainId).toBe("train:match:match-resolution-standard");
+  expect(InterlockingRunner).toBeDefined();
+  expect(TrainRunner).toBeDefined();
+});

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/plan/_trains/_interlockings/match-resolution.yaml

@@ -0,0 +1,8 @@
+interlocking_id: interlocking:match-resolution
+entrypoint:
+  exposed: true
+  actions:
+    - resolve_match
+routes:
+  - route_id: nominal-all-voted
+    train_id: train:match:match-resolution-standard

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/src/server.ts

@@ -0,0 +1,13 @@
+import { InterlockingRunner } from "./trains/interlocking";
+import { TrainRunner } from "./trains/runner";
+
+const runner = new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+
+async function inertProductionHelper(action: string, inputs: object) {
+  const resolution = runner.resolveTrain(action, inputs);
+  return await new TrainRunner(resolution.trainId).execute({});
+}
+
+export async function dispatch(_action: string, _inputs: object) {
+  return { selectedTrainId: "train:match:match-resolution-standard" };
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/e2e/smoke/resolve-match.smoke.test.ts

@@ -0,0 +1,12 @@
+// Phase: SMOKE
+import { expect, test } from "bun:test";
+import { dispatch } from "../../src/server";
+import { InterlockingRunner } from "../../src/trains/interlocking";
+import { TrainRunner } from "../../src/trains/runner";
+
+test("resolve_match target token cannot cover resolve_other dispatch", async () => {
+  const result = await dispatch("resolve_other", { allPlayersVoted: true });
+  expect(result.selectedTrainId).toBe("train:match:match-resolution-standard");
+  expect(InterlockingRunner).toBeDefined();
+  expect(TrainRunner).toBeDefined();
+});

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/plan/_trains/_interlockings/match-resolution.yaml

@@ -0,0 +1,8 @@
+interlocking_id: interlocking:match-resolution
+entrypoint:
+  exposed: true
+  actions:
+    - resolve_match
+routes:
+  - route_id: nominal-all-voted
+    train_id: train:match:match-resolution-standard

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/src/server.ts

@@ -0,0 +1,9 @@
+import { InterlockingRunner } from "./trains/interlocking";
+import { TrainRunner } from "./trains/runner";
+
+const runner = new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+
+export async function dispatch(action: string, inputs: object) {
+  const resolution = runner.resolveTrain(action, inputs);
+  return await new TrainRunner(resolution.trainId).execute({});
+}

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.55",
+  "version": "0.10.57",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
@@ -385,12 +385,12 @@
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/server.ts": "d5bc34c5b1b2b0a511e0c4604ce6f9c77491dca9aee994be720540f3052babc1",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/interlocking.ts": "9bcfdb4ecff6efd1f658b9fd587342615179924e25468c75daa07c2626d4d8ab",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/runner.ts": "0e4b885e50f12cc2a8c8f6740bf83e7b2e7137a28e1e143586e9a8550ea5bd45",
-    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "ea5f87285111a6cd67d7febf3731d5f37c8932a98749ee51cfd39e076994aed6",
+    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "ee5e880f8e5800a767fb37a177bae29faf2b2207c56244ff8bd14bb51b1a64ab",
     "detectors/bun_interlocking_coverage/atdd.implementation.yaml": "f160517a8138ba3ca05e3d130e6fbfb796e643376f25743fdef4fc210196525b",
     "detectors/bun_interlocking_coverage/checks/_map.json": "0a218ea319cc6258af7bd721c2154cb9561fe67e80d80ef32d08fc77bc9403c3",
-    "detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs": "6d0645debe91d05987d858efbaf04f5b70f383d34aeb319fa96b3d3e7ee28330",
+    "detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs": "04fbc7c2ea8f3b762b1fae227e020defdee539fd28d0dec5ab0a6c87f421a1af",
     "detectors/bun_interlocking_coverage/checks/interlocking_route_coverage.mjs": "2230b8477ece6a9f459fb0d3cd9e3f8d194d9800eb976ed7064f4dfb820202b0",
-    "detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs": "ca1250e762a40f04520aa3ef525d61fe834a8f5df03d961e0d6c80e4f3044a2e",
+    "detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs": "e4a564689bc82041db791d88e6e029ce0fff2e4a2ebf071083b65fafbf7eaec8",
     "detectors/bun_interlocking_coverage/checks/interlocking_trace_binds.mjs": "1cc3a11d50a075f3211a6d9cbf27aafcbf7e77b6a855ab040f765ec89dfe0eef",
     "detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs": "8a8a8e88ce8a80024d0bdcc6866819fdfaa5a2ed26e8a9c5a459848d2de346d9",
     "detectors/bun_interlocking_coverage/detect.mjs": "a124418dc29aaf8fda9cd09427230d25768206b3f563d516774667e8cf75b66e",
@@ -435,6 +435,12 @@
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage/e2e/interlockings/match-resolution/routes.test.ts": "ba6ea85b3fbe15e3c49332da3ad2921a0ff3436a6fe3b5a5035fb35fdc874720",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage/e2e/interlockings/match-resolution/trace.test.ts": "aee4ea93ceb8636846344e915cd7e66f7e8f99ba08596f83266590fa2b9ff58e",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage/plan/_trains/_interlockings/match-resolution.yaml": "79b5b7ccbd7d0e73df74c53ec071580a0442fe30ae6d0bf393e3102b2be2e5c0",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/e2e/smoke/resolve-match.smoke.test.ts": "80fe9fac7af88bade87683c4dd8b78beff26f2c9ac0e4f550353817f7de96f5e",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/plan/_trains/_interlockings/match-resolution.yaml": "3f475539871048e7a0c9b92cfc4b6fb0690f591c91e4da00bdca7cf397f39025",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/src/server.ts": "82bc38c96843f5dfe811cbb49b5ece2523d178c0f48337177bc45ba15ea96a0f",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/e2e/smoke/resolve-match.smoke.test.ts": "a71ae9e8e2eb4c143e7c8a333ec1a56b831dc60245fd9cab15422801c659a89d",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/plan/_trains/_interlockings/match-resolution.yaml": "3f475539871048e7a0c9b92cfc4b6fb0690f591c91e4da00bdca7cf397f39025",
+    "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_mismatched_action/src/server.ts": "962f6f7e84c7a770b932b672271b7542e3bc7c850f8cfcb97bb75f8b1f32196a",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_trace_binds/e2e/interlockings/match-resolution/routes.test.ts": "ba6ea85b3fbe15e3c49332da3ad2921a0ff3436a6fe3b5a5035fb35fdc874720",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_trace_binds/e2e/interlockings/match-resolution/trace.test.ts": "ba682afab675c12a4404ebd58b3dc7ffc4147982a96f8727c9d80215682b2788",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_trace_binds/e2e/smoke/resolve-match.smoke.test.ts": "07398b0d33ef6b7139c1a2c762bb8cc7afc307b7dfad248d048e7f4bad81320d",
@@ -1218,7 +1224,7 @@
     "relationships.yaml": "5860a308ebc3ee7fa8172fc2c6633984000ab3003f0ae4b6fa28db48879eda22",
     "src/agent.ts": "6d6c6e75908af8fbab13432f0001b0374bb25cf3dee46ba218dfd67e0090cb56",
     "src/ci.ts": "67e54d2cbfc44a9e42837d5e750af526d6255c539d3c452a4d5fca3226c0d9ac",
-    "src/cli.ts": "c4ede85983445a6388bf74bbccf1251dd45df2788a699f1bf2250fa0fda3c516",
+    "src/cli.ts": "90e59edbb8a7ea116ad9e7b4ba56b5c612ac18ada05824e8e941048be4dc72c8",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
     "src/enforce.ts": "7e6b3a1fc7c90f8e1836ab3e4655778fb569a63be5e7c199de44024fc003e6be",
     "src/hooks.ts": "233d26c0320adea3b315d808811da9b53b989db8effd4f6ed9306a80069101e8",
@@ -1229,7 +1235,7 @@
     "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
     "src/planner-validators.ts": "99adeb65f579af923c11f21a8f55cfb9993b007fd8df59c5f764696b55379cfc",
     "src/profile-registry.ts": "5a7761d324181ae27deb51f198d63648a4c99e858b4de98b54d35e6cf8a39fe7",
-    "src/ratchet.ts": "1e90fba040fd90437cd9d0300bcd2dc575a3952a7e5919cc2d5c8ff59814f1f1",
+    "src/ratchet.ts": "16213f88fc09de7911defc185ac6ec45b9ecdfbebbe40a12fb6114fe75e7f896",
     "src/register.ts": "6a2f1c6b8df0dc9c8f45df8ec9fac2be29044e048b08c8ffe423410e94dadedd",
     "src/release.ts": "7b0fe444ee81f476f53b9c21b6c347ef588ee616c60211419cf984132be768ba",
     "src/setup.ts": "38233265afedc63499bbef3b5403889651add335a70efd3813254ba53f4fc4fe",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.55",
+  "version": "0.10.57",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/cli.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 import { enforce, enabledProfiles, flowCompatibilityDiagnostic, normalizeProfileName, profileNames, type Profile } from "./enforce";
-import { activationContextDigest, compareFindings, contextDigest, isStrictProfileExpansion, parseRatchetPolicy } from "./ratchet";
+import { activationContextDigest, canonicalFindingPath, compareFindings, contextDigest, isStrictProfileExpansion, parseRatchetPolicy } from "./ratchet";
 import { existsSync } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
 import { agentInit, agentStatus } from "./agent";
@@ -173,7 +173,7 @@ if (!args.includes("--ratchet")) {
         if (!(profileActivation ? activationIsValid : ordinaryContextMatches)) { console.error(profileActivation ? "ratchet profile activation requires an explicit monotonic profile expansion and identical non-profile context" : "ratchet base and candidate profile/context differ; use a separately governed adoption path"); process.exitCode = 1; }
         else {
           const [baseFindings, candidateFindings] = await Promise.all([enforce({ root: scratch, profiles: candidateProfiles as Profile[] }), enforce({ root: candidateRoot, profiles: candidateProfiles as Profile[] })]);
-          const normalize = (findings: Awaited<ReturnType<typeof enforce>>, directory: string) => findings.map(finding => ({ ...finding, file: relative(directory, finding.file).replaceAll("\\", "/") }));
+          const normalize = (findings: Awaited<ReturnType<typeof enforce>>, directory: string) => findings.map(finding => ({ ...finding, file: canonicalFindingPath(directory, finding.file) }));
           const delta = compareFindings(normalize(baseFindings, scratch), normalize(candidateFindings, candidateRoot));
           console.log(JSON.stringify({ schema: "atdd-bun.ratchet-report/v1", mode: policy.mode, base, candidate: (await git(candidateRoot, ["rev-parse", "HEAD"])).out, profiles: stable(candidateProfiles), context: contextDigest(candidateConfig, candidateProfiles), ...delta }, null, 2));
           if (policy.mode === "reject-new" && delta.new.length) process.exitCode = 1;

package/src/ratchet.ts

@@ -1,3 +1,5 @@
+import { relative, resolve } from "node:path";
+
 /** Pure v1 primitives for the opt-in exact-base finding ratchet. No baseline is written or accepted. */
 export type RatchetMode = "report" | "reject-new";
 export type RatchetPolicy = { mode: RatchetMode; profiles: string[] };
@@ -24,6 +26,14 @@ const normalizedPath = (path: string) => {
   return normalized;
 };
 
+/** Canonicalize a detector location against the root that produced it, refusing traversal and external paths. */
+export function canonicalFindingPath(root: string, path: string): string {
+  const supplied = path.replaceAll("\\", "/");
+  if (supplied.split("/").includes("..")) throw new Error(`ratchet finding path must be normalized and repository-relative: ${path}`);
+  const rootPath = resolve(root), target = resolve(rootPath, path), fromRoot = relative(rootPath, target).replaceAll("\\", "/");
+  return normalizedPath(fromRoot);
+}
+
 /** Stable semantic identity: presentation position and rendered evidence deliberately do not participate. */
 export function findingFingerprint(finding: FindingIdentity): string {
   const path = normalizedPath(finding.file), subject = finding.subject ?? path;