@dzhechkov/harness-core 0.7.11 → 0.8.1

package/src/loop-blobs.generated.ts

@@ -52,11 +52,11 @@ export const BLOBS: Record<string, LoopBlob> = {
   "training-pairs": {
     name: "training-pairs",
     version: "1.1.0",
-    contentHash: "740b733d3d995e7031590f1707b442d0f0f9d7d585ada6f37bbf08c5db3351e9",
+    contentHash: "199eaaa8ce5dba4f54744b4a4f34eea32a3c33d4de8dbbddd3d119b70459361d",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-checkpoints.ts",
     requires: ["checkpoints"],
     exports: ["TRAINPAIR_SCHEMA_VERSION","TRAINPAIR_MAX_IO_CHARS","trainingPairFamily","trainingPairPath","TRAINPAIR_PRIVACY_NOTE","buildTrainingPair","serializeTrainingPair","trainingPairAppendCmd","decideCaptureMode","captureFailureRecord","trainingPairBackfillCmd","TP_BACKFILL_OK","TP_BACKFILL_SKIP"],
-    code: "function decideCaptureMode(opts) {\n    if (!opts.enabled)\n        return 'skip-disabled';\n    if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0)\n        return 'skip-empty';\n    return opts.resumed ? 'backfill' : 'capture';\n}\nfunction captureFailureRecord(stage, mode, reason, detail) {\n    const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';\n    const normalizedMode = mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'\n        ? mode\n        : null;\n    const normalizedReason = reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'\n        ? reason\n        : 'threw';\n    let normalizedDetail = null;\n    if (detail !== null && detail !== undefined) {\n        try {\n            const text = String(detail);\n            if (text !== '')\n                normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;\n        }\n        catch {\n            normalizedDetail = null;\n        }\n    }\n    return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };\n}\nconst TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = \"feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.\";\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = coerceText(opts.input);\n    let output = coerceText(opts.output);\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n        captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',\n        resumed: opts.resumed === true,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}\nconst TP_BACKFILL_OK = 'TP-BACKFILL-OK';\nconst TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';\nconst TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';\nfunction trainingPairBackfillCmd(repoAbs, slug, stage, lines, markKey) {\n    if (typeof repoAbs !== 'string' || repoAbs === '')\n        return null;\n    if (typeof slug !== 'string' || slug === '')\n        return null;\n    if (typeof stage !== 'string' || stage === '')\n        return null;\n    if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== ''))\n        return null;\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';\n    const markStage = stage.replace(/\\.\\./g, '_').replace(/\\//g, '_');\n    const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\\0' + lines.join('\\n')) : markKey;\n    const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;\n    const appends = lines\n        .map(line => \"printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs))\n        .join(' && ');\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        ' && mkdir -p ' + shellQuote(markDir) +\n        ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +\n        'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +\n        '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +\n        '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi');\n}",
+    code: "function decideCaptureMode(opts) {\n    if (!opts.enabled)\n        return 'skip-disabled';\n    if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0)\n        return 'skip-empty';\n    return opts.resumed ? 'backfill' : 'capture';\n}\nfunction captureFailureRecord(stage, mode, reason, detail) {\n    const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';\n    const normalizedMode = mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'\n        ? mode\n        : null;\n    const normalizedReason = reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'\n        ? reason\n        : 'threw';\n    let normalizedDetail = null;\n    if (detail !== null && detail !== undefined) {\n        try {\n            const text = String(detail);\n            if (text !== '')\n                normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;\n        }\n        catch {\n            normalizedDetail = null;\n        }\n    }\n    return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };\n}\nconst TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = \"feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.\";\nconst TP_PROFILE_MARKER_START = '<!-- dz:profile:start -->';\nconst TP_PROFILE_MARKER_END = '<!-- dz:profile:end -->';\nconst TP_PROFILE_REDACTED = '[dz:profile REDACTED]';\nfunction redactProfileBlock(text) {\n    if (typeof text !== 'string' || text === '')\n        return typeof text === 'string' ? text : '';\n    let out = '';\n    let rest = text;\n    for (;;) {\n        const start = rest.indexOf(TP_PROFILE_MARKER_START);\n        if (start === -1)\n            return out + rest;\n        out += rest.slice(0, start) + TP_PROFILE_REDACTED;\n        const end = rest.indexOf(TP_PROFILE_MARKER_END, start + TP_PROFILE_MARKER_START.length);\n        if (end === -1)\n            return out;\n        rest = rest.slice(end + TP_PROFILE_MARKER_END.length);\n    }\n}\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = redactProfileBlock(coerceText(opts.input));\n    let output = redactProfileBlock(coerceText(opts.output));\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n        captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',\n        resumed: opts.resumed === true,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}\nconst TP_BACKFILL_OK = 'TP-BACKFILL-OK';\nconst TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';\nconst TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';\nfunction trainingPairBackfillCmd(repoAbs, slug, stage, lines, markKey) {\n    if (typeof repoAbs !== 'string' || repoAbs === '')\n        return null;\n    if (typeof slug !== 'string' || slug === '')\n        return null;\n    if (typeof stage !== 'string' || stage === '')\n        return null;\n    if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== ''))\n        return null;\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';\n    const markStage = stage.replace(/\\.\\./g, '_').replace(/\\//g, '_');\n    const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\\0' + lines.join('\\n')) : markKey;\n    const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;\n    const appends = lines\n        .map(line => \"printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs))\n        .join(' && ');\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        ' && mkdir -p ' + shellQuote(markDir) +\n        ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +\n        'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +\n        '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +\n        '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi');\n}",
   },
   "model-resolver": {
     name: "model-resolver",

package/src/mutation-gate.ts

@@ -45,12 +45,15 @@ export interface MutationRegistryEntry {
 export interface MutationRegistry {
   /** optional suite command override for the whole registry (default `npm test`). */
   readonly testCommand?: string;
+  /** opt-in proof that the suite harness reached its clean completion path. */
+  readonly requireCompletionReceipt?: boolean;
   readonly entries: readonly MutationRegistryEntry[];
 }
 
 export type MutationVerdict =
   | 'PROVEN' // mutation applied, suite went red, failing count (when known) >= minFailing
   | 'UNDEFENDED' // mutation applied, suite stayed GREEN — the property has no discriminating test
+  | 'RECEIPT_MISMATCH' // the suite harness declared a receipt error, or an opted-in completion receipt was absent — neither the exit code nor failing count may be read as discrimination
   | 'NOT_APPLIED' // `find` occurred 0 or >1 times — code drifted; nothing was tested (rule 1)
   | 'BELOW_MIN' // suite red, but a RELIABLE count came in under the entry's own minFailing contract
   | 'MUTATION_UNPARSEABLE' // the MUTATED file no longer parses — a registry/setup error: whole-suite redness from a load failure proves nothing (route a)
@@ -89,12 +92,22 @@ export interface MutationObservation {
    * failure), NEVER PROVEN: redness that cannot be attributed proves nothing.
    */
   readonly outputUnrecognised?: string;
+  /**
+   * set to the marker text when the suite harness declares its own execution-receipt contract
+   * violated, or to the missing-receipt detail for an opted-in registry. Either condition
+   * invalidates both green and count-based readings of the same run.
+   */
+  readonly receiptMismatch?: string;
+  /** named reason from spawnSync when no exit code exists (timeout, signal, maxBuffer, spawn). */
+  readonly runFailureReason?: string;
   /**
    * exit code of the suite re-run on the RESTORED tree after this entry (the attribution check
    * for flaky neighbours). undefined = not run; 0 = reproducibly green; any other value (or null)
    * = the "green" baseline is not reproducible, so the red under mutation is not attributable.
    */
   readonly rebaselineExitCode?: number | null;
+  /** named no-exit reason for the restored-tree attribution run, when it produced none. */
+  readonly rebaselineFailureReason?: string;
 }
 
 export interface MutationEntryResult {
@@ -135,7 +148,7 @@ export interface ParsedRegistry {
   readonly errors: readonly string[];
 }
 
-/** Parse + validate a registry JSON text. Accepts a bare array of entries or `{testCommand, entries}`. */
+/** Parse + validate a registry JSON text. Accepts a bare array or `{testCommand?, requireCompletionReceipt?, entries}`. */
 export function parseMutationRegistry(text: string): ParsedRegistry {
   let raw: unknown;
   try {
@@ -146,10 +159,11 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
 
   let entriesRaw: unknown;
   let testCommand: string | undefined;
+  let requireCompletionReceipt: boolean | undefined;
   if (Array.isArray(raw)) {
     entriesRaw = raw;
   } else if (raw && typeof raw === 'object') {
-    const obj = raw as { testCommand?: unknown; entries?: unknown };
+    const obj = raw as { testCommand?: unknown; requireCompletionReceipt?: unknown; entries?: unknown };
     entriesRaw = obj.entries;
     if (obj.testCommand !== undefined) {
       if (typeof obj.testCommand !== 'string' || obj.testCommand.trim() === '') {
@@ -157,9 +171,15 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
       }
       testCommand = obj.testCommand.trim();
     }
+    if (obj.requireCompletionReceipt !== undefined) {
+      if (typeof obj.requireCompletionReceipt !== 'boolean') {
+        return { registry: null, errors: ['requireCompletionReceipt must be a boolean when present'] };
+      }
+      requireCompletionReceipt = obj.requireCompletionReceipt;
+    }
   }
   if (!Array.isArray(entriesRaw)) {
-    return { registry: null, errors: ['registry must be an array of entries or {testCommand?, entries: [...]}'] };
+    return { registry: null, errors: ['registry must be an array of entries or {testCommand?, requireCompletionReceipt?, entries: [...]}'] };
   }
   if (entriesRaw.length === 0) {
     // An empty registry "passes" by testing nothing — the same silent hole as a skipped mutation.
@@ -237,9 +257,14 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
   });
 
   if (errors.length > 0) return { registry: null, errors };
-  return testCommand !== undefined
-    ? { registry: { testCommand, entries }, errors: [] }
-    : { registry: { entries }, errors: [] };
+  return {
+    registry: {
+      ...(testCommand !== undefined ? { testCommand } : {}),
+      ...(requireCompletionReceipt !== undefined ? { requireCompletionReceipt } : {}),
+      entries,
+    },
+    errors: [],
+  };
 }
 
 // ── Mutation application — exact text surgery, exactly once (rule 1) ──────────────────────────
@@ -315,6 +340,21 @@ function stripSgr(s: string): string {
   return s.replace(SGR, '');
 }
 
+/** Return the first suite-harness receipt error at column 0, with SGR removed. */
+export function detectSuiteReceiptMismatch(rawOutput: string): string | undefined {
+  const match = /^mutation-suite-receipt-error:[^\S\r\n]*(.*)$/m.exec(stripSgr(rawOutput));
+  return match === null ? undefined : (match[1] ?? '').trim();
+}
+
+/** Return the first suite-harness clean-completion receipt at column 0, with SGR removed. */
+export function detectSuiteCompletionReceipt(rawOutput: string): { lanes: number; names: number } | undefined {
+  const match = /^mutation-suite-receipt-ok:[^\S\r\n]*lanes=(\d+)[^\S\r\n]+names=(\d+)[^\S\r\n]*$/m.exec(stripSgr(rawOutput));
+  if (match === null) return undefined;
+  const lanes = Number(match[1]);
+  const names = Number(match[2]);
+  return Number.isSafeInteger(lanes) && Number.isSafeInteger(names) ? { lanes, names } : undefined;
+}
+
 export type RunnerKind = 'node-test' | 'vitest' | 'unknown';
 
 /**
@@ -464,10 +504,10 @@ export interface BaselineResult {
  * A RED baseline in the scratch copy is a SETUP error, never a mutation result: every subsequent
  * "red under mutation" would be noise, and every "green" a lie about an unrunnable copy.
  */
-export function classifyBaseline(exitCode: number | null): BaselineResult {
+export function classifyBaseline(exitCode: number | null, runFailureReason?: string): BaselineResult {
   if (exitCode === 0) return { ok: true, detail: 'baseline suite green in the scratch copy' };
   if (exitCode === null) {
-    return { ok: false, detail: 'baseline suite produced no exit code (timeout/spawn failure) — the copy is not runnable; fix the copy, do not read this as a mutation result' };
+    return { ok: false, detail: `baseline suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; fix the copy, do not read this as a mutation result` };
   }
   return { ok: false, detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — a broken copy cannot prove anything; fix the copy (node_modules link? path-dependent test?) before trusting any verdict` };
 }
@@ -489,13 +529,16 @@ export function classifyBaseline(exitCode: number | null): BaselineResult {
  *                               the flaky-rebaseline check (a structurally-broken run needs no
  *                               attribution analysis);
  *   4. INCONCLUSIVE (no exit) — the run produced nothing to classify at all;
- *   5. UNDEFENDED (exit 0)    — the disjoint GREEN arm: mutually exclusive with every red-based
+ *   5. RECEIPT_MISMATCH       — the harness declared its own receipt contract broken, which
+ *                               invalidates BOTH the green reading and every count-based reading
+ *                               of the same run;
+ *   6. UNDEFENDED (exit 0)    — the disjoint GREEN arm: mutually exclusive with every red-based
  *                               verdict below;
- *   6. INCONCLUSIVE (unrecognised output) — red, but the shape is unreadable: counts parsed out of
+ *   7. INCONCLUSIVE (unrecognised output) — red, but the shape is unreadable: counts parsed out of
  *                               unrecognised output must not reach BELOW_MIN/OVER_FAILING/PROVEN;
- *   7. INCONCLUSIVE (flaky rebaseline)    — red, readable, but not attributable;
- *   8. BELOW_MIN → 9. OVER_FAILING        — reliable-count contract checks, both failing;
- *  10. PROVEN                 — applied, red, behavioural, attributable, within bounds.
+ *   8. INCONCLUSIVE (flaky rebaseline)    — red, readable, but not attributable;
+ *   9. BELOW_MIN → 10. OVER_FAILING       — reliable-count contract checks, both failing;
+ *  11. PROVEN                 — applied, red, behavioural, attributable, within bounds.
  *
  * THE DROP DECISION (SPEC §Reporting, decided here + justified): `failing < observed` but still
  * `>= minFailing` is a LOUD WARNING, not a failure. Two reasons, both load-bearing:
@@ -568,7 +611,18 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
       applied: true,
       verdict: 'INCONCLUSIVE',
       drop: false,
-      detail: 'suite produced NO exit code under the mutation (timeout / spawn failure) — inconclusive is a FAILURE, never a pass',
+      detail: `suite produced NO exit code under the mutation (${obs.runFailureReason ?? 'unknown timeout / spawn failure'}) — inconclusive is a FAILURE, never a pass`,
+    };
+  }
+
+  if (obs.receiptMismatch !== undefined) {
+    const boundedReceipt = Array.from(obs.receiptMismatch).slice(0, 220).join('');
+    return {
+      ...base,
+      applied: true,
+      verdict: 'RECEIPT_MISMATCH',
+      drop: false,
+      detail: `the suite harness declared its own receipt contract violated (${boundedReceipt}) — neither this run's exit code nor its failing count may be read as discrimination; RECEIPT_MISMATCH is a FAILURE, never PROVEN`,
     };
   }
 
@@ -604,7 +658,7 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
       applied: true,
       verdict: 'INCONCLUSIVE',
       drop: false,
-      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? 'no exit code' : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
+      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
     };
   }
 
@@ -645,7 +699,7 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
 }
 
 /** Verdicts that fail the gate. INCONCLUSIVE and NOT_APPLIED fail (inconclusive ≠ pass). */
-const FAILING_VERDICTS: ReadonlySet<MutationVerdict> = new Set(['UNDEFENDED', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
+const FAILING_VERDICTS: ReadonlySet<MutationVerdict> = new Set(['UNDEFENDED', 'RECEIPT_MISMATCH', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
 
 /** Exit contract: 0 all proven · 1 any entry failed (or red baseline) · (2 = usage/setup, CLI-side). */
 export function mutationGateExitCode(results: readonly MutationEntryResult[], baselineOk: boolean): number {
@@ -660,6 +714,7 @@ export interface MutationGateSummary {
   readonly total: number;
   readonly proven: number;
   readonly undefended: number;
+  readonly receiptMismatch: number;
   readonly notApplied: number;
   readonly belowMin: number;
   readonly unparseable: number;
@@ -678,6 +733,7 @@ export function summarizeMutationResults(results: readonly MutationEntryResult[]
     total: results.length,
     proven: results.filter((r) => r.verdict === 'PROVEN').length,
     undefended: results.filter((r) => r.verdict === 'UNDEFENDED').length,
+    receiptMismatch: results.filter((r) => r.verdict === 'RECEIPT_MISMATCH').length,
     notApplied: results.filter((r) => r.verdict === 'NOT_APPLIED').length,
     belowMin: results.filter((r) => r.verdict === 'BELOW_MIN').length,
     unparseable: results.filter((r) => r.verdict === 'MUTATION_UNPARSEABLE').length,
@@ -692,6 +748,7 @@ export function summarizeMutationResults(results: readonly MutationEntryResult[]
 const VERDICT_MARK: Record<MutationVerdict, string> = {
   PROVEN: '✓',
   UNDEFENDED: '✗',
+  RECEIPT_MISMATCH: '✗',
   NOT_APPLIED: '✗',
   BELOW_MIN: '✗',
   MUTATION_UNPARSEABLE: '✗',
@@ -715,7 +772,7 @@ export function renderMutationReport(
     if (r.verdict !== 'PROVEN' || r.drop) lines.push(`      ${r.detail}`);
   }
   const s = summarizeMutationResults(results);
-  lines.push(`  summary: ${s.proven}/${s.total} proven · ${s.undefended} undefended · ${s.notApplied} not-applied · ${s.belowMin} below-min · ${s.unparseable} unparseable · ${s.loadFatal} load-fatal · ${s.overFailing} over-failing · ${s.inconclusive} inconclusive · ${s.drops} coverage drop(s) among ${s.dropComparable}/${s.total} observed-anchored entries (a drop is undetectable without an \`observed\` anchor)`);
+  lines.push(`  summary: ${s.proven}/${s.total} proven · ${s.undefended} undefended · ${s.receiptMismatch} receipt-mismatch · ${s.notApplied} not-applied · ${s.belowMin} below-min · ${s.unparseable} unparseable · ${s.loadFatal} load-fatal · ${s.overFailing} over-failing · ${s.inconclusive} inconclusive · ${s.drops} coverage drop(s) among ${s.dropComparable}/${s.total} observed-anchored entries (a drop is undetectable without an \`observed\` anchor)`);
   lines.push(mutationGateExitCode(results, baseline.ok) === 0
     ? '  verdict: PASS — every named protection has a test that goes red when the protection is deleted'
     : '  verdict: FAIL — at least one named protection is undefended, unmutable, or unproven');

package/src/named-lock.ts

@@ -33,7 +33,7 @@ import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
 import { lockSync } from 'proper-lockfile';
 
-import { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from './store-lock.js';
+import { LOCK_TIMEOUT_MS, resolveStaleMs } from './store-lock.js';
 import type { StoreLockOptions } from './store-lock.js';
 
 /** `proper-lockfile` silently clamps `stale` up to this minimum. */
@@ -99,7 +99,7 @@ const sleepSync = (ms: number): void => {
 
 function resolveOpts(opts: StoreLockOptions): { staleMs: number; timeoutMs: number; pollMs: number } {
   return {
-    staleMs: Math.max(opts.staleMs ?? STALE_LOCK_MS, MIN_STALE_MS),
+    staleMs: Math.max(opts.staleMs ?? resolveStaleMs(), MIN_STALE_MS),
     timeoutMs: opts.timeoutMs ?? defaultTimeoutMs(),
     pollMs: opts.pollMs ?? 25,
   };
@@ -206,12 +206,14 @@ function tryAcquire(
           // NEVER remove a lock directory we cannot prove is ours — including at process exit.
           return disarmExitRemoval(resourceKey) ? 'stolen' : 'stolen-undisarmed';
         }
-        try {
-          release();
-        } catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
+        // Load-bearing order: remove our marker while the directory still excludes waiters. If we
+        // unlock first, a successor can acquire and publish its marker before our cleanup runs.
         try {
           rmSync(ownerMarkerPath(lockPath), { force: true });
         } catch { /* best effort: a stale marker is overwritten by the next holder anyway */ }
+        try {
+          release();
+        } catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
         return 'released';
       },
     };
@@ -257,9 +259,9 @@ export function withNamedLockSync<T>(
           lockPath,
           compromised ??
             new Error(
-              'the lock directory no longer carries this holder\u2019s ownership token — a waiter broke it as stale ' +
-              'while the critical section was still running (a synchronous body cannot heartbeat). The successor\u2019s ' +
-              'lock was left untouched; THIS run must be treated as having raced and retried.' +
+              'the lock directory no longer carries this holder\u2019s ownership token; a waiter may have broken it ' +
+              'as stale, or another holder\u2019s release may have removed it. The current holder left the observed ' +
+              'lock untouched; THIS run must be treated as having raced and retried.' +
               (outcome === 'stolen-undisarmed'
                 ? ' WARNING: proper-lockfile\u2019s exit-time lock removal could NOT be disarmed (its getLocks() accessor ' +
                   'is unavailable in this version), so this process may still remove the successor\u2019s lock when it exits.'

package/src/native-dep-probe.ts

@@ -0,0 +1,118 @@
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+
+export type NativeDepState = 'usable' | 'absent' | 'unusable';
+
+export interface NativeDepVerdict {
+  readonly state: NativeDepState;
+  readonly pkg: string;
+  readonly reason?: string;
+  readonly path?: string;
+}
+
+const verdictCache = new Map<string, NativeDepVerdict>();
+const exerciseIds = new WeakMap<Function, string>();
+let nextExerciseId = 1;
+
+function exerciseIdentity(exercise: unknown): string {
+  if (typeof exercise !== 'function') return `invalid-${typeof exercise}`;
+  const existing = exerciseIds.get(exercise);
+  if (existing) return existing;
+  const identity = `function-${nextExerciseId++}`;
+  exerciseIds.set(exercise, identity);
+  return identity;
+}
+
+function formatError(error: unknown): string {
+  try {
+    const message = error instanceof Error ? error.message : String(error);
+    const oneLine = message.replace(/\s+/g, ' ').trim() || 'unknown error';
+    return oneLine.length > 400 ? `${oneLine.slice(0, 397)}...` : oneLine;
+  } catch {
+    return 'unknown error';
+  }
+}
+
+export function exerciseSqliteOpen(mod: unknown): void {
+  const defaultExport =
+    typeof mod === 'object' && mod !== null && 'default' in mod
+      ? (mod as { default: unknown }).default
+      : mod;
+  const Database = defaultExport as new (filename: string) => { close(): void };
+  const database = new Database(':memory:');
+  database.close();
+}
+
+export function probeNativeDep(
+  projectRoot: string,
+  pkg: string,
+  exercise?: (mod: unknown) => unknown,
+  exerciseId?: string,
+): NativeDepVerdict {
+  let cacheKey: string;
+  try {
+    const resolvedExerciseId =
+      exerciseId ?? (exercise === undefined ? undefined : exerciseIdentity(exercise));
+    cacheKey = `${resolve(projectRoot)}::${pkg}::${resolvedExerciseId ?? 'none'}`;
+  } catch {
+    return { state: 'absent', pkg };
+  }
+
+  const cached = verdictCache.get(cacheKey);
+  if (cached) return cached;
+
+  let resolvedPath: string;
+  let projectRequire: ReturnType<typeof createRequire>;
+  try {
+    projectRequire = createRequire(join(projectRoot, 'package.json'));
+    resolvedPath = projectRequire.resolve(pkg);
+  } catch {
+    const verdict: NativeDepVerdict = { state: 'absent', pkg };
+    verdictCache.set(cacheKey, verdict);
+    return verdict;
+  }
+
+  let verdict: NativeDepVerdict;
+  try {
+    const mod = projectRequire(resolvedPath);
+    const exerciseResult = exercise?.(mod);
+    const then =
+      exerciseResult !== null &&
+      (typeof exerciseResult === 'object' || typeof exerciseResult === 'function')
+        ? (exerciseResult as { then?: unknown }).then
+        : undefined;
+    if (typeof then === 'function') {
+      void Promise.resolve(exerciseResult).catch(() => {});
+      verdict = {
+        state: 'unusable',
+        pkg,
+        reason:
+          'exercise returned a promise; probeNativeDep is synchronous and cannot await it',
+        path: resolvedPath,
+      };
+    } else {
+      verdict = { state: 'usable', pkg, path: resolvedPath };
+    }
+  } catch (error) {
+    verdict = {
+      state: 'unusable',
+      pkg,
+      reason: formatError(error),
+      path: resolvedPath,
+    };
+  }
+
+  verdictCache.set(cacheKey, verdict);
+  return verdict;
+}
+
+export function describeNativeDep(verdict: NativeDepVerdict): string {
+  if (verdict.state === 'usable') return '';
+  if (verdict.state === 'absent') {
+    if (verdict.pkg === 'agentdb' || verdict.pkg === 'better-sqlite3') {
+      return `${verdict.pkg} not installed in project (run: dz setup --memory agentdb)`;
+    }
+    return `${verdict.pkg} not installed in project (run: npm i ${verdict.pkg})`;
+  }
+  return `${verdict.pkg} is installed at ${verdict.path ?? 'an unknown path'}, but its native part will not load on this Node: ${verdict.reason ?? 'unknown error'} (run: npm rebuild ${verdict.pkg})`;
+}

package/src/operations.ts

@@ -27,6 +27,7 @@ import {
   type HooksListHookMetadata,
   type ManagedEntry,
 } from './codex-hooks.js';
+import { sweepSkillDrift } from './skill-drift.js';
 import { generateCodexHelpers } from './codex-hooks-assets.js';
 import {
   classifyVetoProbe,
@@ -997,6 +998,40 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       detail: '.claude/mcp.json is NOT loaded by Claude Code — re-run dz setup to register agentdb in .mcp.json (project root)',
     });
   }
+  // 8x. agentdb MCP/writer store SEPARATION (ADR-001 agentdb-setup-shared-store-fix, 2026-08-26).
+  // A shared store is a measured data-loss path (2026-07-09: 5 of 20 samples zero bytes, 4 torn) —
+  // the same predicate setup.ts's `agentdb wiring` step uses, imported, never re-implemented.
+  // Deliberately OUTSIDE the `.dz/agentdb-writer.mjs` branch below: a registration can be wrong
+  // before any writer is deployed, and that is exactly when it is cheapest to fix.
+  const mcpConfigPath = join(root, '.mcp.json');
+  if (existsSync(mcpConfigPath)) {
+    try {
+      const { agentdbStoreSeparationProblem } = await import('./setup.js');
+      const mcp = JSON.parse(readFileSync(mcpConfigPath, 'utf-8')) as {
+        mcpServers?: Record<string, { env?: Record<string, string> }>;
+      };
+      const pinned = mcp.mcpServers?.['agentdb']?.env?.['AGENTDB_PATH'];
+      // Only speak when an agentdb server is actually registered — a project without one keeps
+      // its doctor output noise-free, exactly as before this check existed.
+      // A REGISTERED agentdb server with NO AGENTDB_PATH is not a quiet project — it is the
+      // protection DELETED. Without the pin the server resolves its store from its own cwd, which is
+      // exactly the unpinned arrangement that produced an empty orphan store in this repo. The first
+      // version of this check skipped that case, so removing the guard produced no finding at all
+      // (cross-family QE, Codex gpt-5.6-sol). Silence on a deleted protection is the failure mode
+      // this whole feature exists to end.
+      const registered = mcp.mcpServers?.['agentdb'] !== undefined;
+      if (registered && pinned === undefined) {
+        checks.push({
+          name: 'agentdb store separation',
+          ok: false,
+          detail: 'an agentdb MCP server is registered with NO AGENTDB_PATH — it will resolve its store from its own cwd, so nothing guarantees it stays off the session-hook writer store; re-run dz setup --memory agentdb',
+        });
+      } else if (pinned !== undefined) {
+        const problem = agentdbStoreSeparationProblem(root, pinned);
+        if (problem) checks.push({ name: 'agentdb store separation', ok: false, detail: problem });
+      }
+    } catch { /* doctor never throws on a diagnostic */ }
+  }
   // Flat dz hook entries (dz ≤0.3.43 emitted `{type,command}` without the matcher-group wrapper)
   // are silently IGNORED by Claude Code — the writer never fires. Detect and point at the fix.
   try {
@@ -1097,12 +1132,53 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
         checks.push({
           name: 'agentdb version drift',
           ok: false,
-          detail: `local agentdb@${localVer} != MCP pin ${pinned} (alpha schema drift risk on the shared DB) — re-run dz setup`,
+          detail: `local agentdb@${localVer} != MCP pin ${pinned} (alpha schema drift risk) — re-run dz setup`,
         });
       }
     } catch { /* either side absent — covered by other checks */ }
   }
 
+  // 8a-bis. DEV-TREE SKILL LAG — advisory, never blocking.
+  //
+  // The `no-skill-drift` HARD rule sweeps scope 'installs', which DELIBERATELY excludes the
+  // hand-edited `.claude/skills/` dev tree: those copies are allowed to lag a published bump, and
+  // holding them to byte-identity would make the gate red-on-arrival. That reasoning is sound and
+  // is NOT changed here.
+  //
+  // What was missing is that nobody SAW the lag. MEASURED 2026-08-26: `.claude/skills/idea2prd-manual`
+  // was a month behind its package copy — missing the entire v3 modernization that landed in
+  // 0.1.3/0.1.4 — and `.claude/skills/observability` had never received the 2026-08-24 tightening of
+  // its dashboard gate. Those dev copies are exactly what the agents in THIS repo read, so "legitimately
+  // lagging" quietly meant "the agents here have been running a stale skill for a month". A narrow
+  // gate plus zero visibility is how a lag becomes a silent regression.
+  //
+  // So: report the DIFFERENCE between the wide sweep and the gated one — i.e. only skills whose sole
+  // divergence is the dev tree. Never `ok:false` for a lag alone; the HARD rule keeps owning what
+  // blocks. `dz drift-check --all` remains the detailed view.
+  try {
+    const allowlist = ((): string[] => {
+      const ap = join(root, '.dz', 'drift-allowlist.json');
+      if (!existsSync(ap)) return [];
+      try {
+        const raw = JSON.parse(readFileSync(ap, 'utf8')) as unknown;
+        const arr = Array.isArray(raw) ? raw : Array.isArray((raw as { skills?: unknown })?.skills) ? (raw as { skills: unknown[] }).skills : [];
+        return arr.map((e) => (typeof e === 'string' ? e : (e as { name?: string })?.name)).filter((n): n is string => typeof n === 'string' && n.length > 0);
+      } catch { return []; }
+    })();
+    const wide = sweepSkillDrift(root, { scope: 'all', allowlist });
+    const gated = new Set(sweepSkillDrift(root, { scope: 'installs', allowlist }).drifted.map((d) => d.name));
+    // Only what the HARD rule does NOT already own: these differ ONLY because of the dev tree.
+    const devOnly = wide.drifted.filter((d) => !gated.has(d.name));
+    if (devOnly.length > 0) {
+      const names = devOnly.slice(0, 5).map((d) => `${d.name} (${d.driftFiles} file(s))`).join(', ');
+      checks.push({
+        name: 'dev-tree skill lag',
+        ok: true, // ADVISORY: the gated scope decides what blocks; this only makes the lag visible.
+        detail: `${devOnly.length} skill(s) differ ONLY in the .claude/skills dev tree: ${names}${devOnly.length > 5 ? ', …' : ''} — a dev copy may legitimately lag a published bump, but it is what the agents here READ, so a month-old copy is a silent regression. Inspect with: dz drift-check --all`,
+      });
+    }
+  } catch { /* doctor never throws on a diagnostic */ }
+
   // 8b. EVIDENCE-CHAIN INTEGRITY (feature event-chain, ADR-001). `.dz/recall-usage.jsonl` and
   // `.dz/guard-audit.jsonl` are what `dz compounding` and `dz guard promote` decide on; a rewrite
   // that loses or duplicates a record there is a wrong verdict with no symptom. Deliberately OUTSIDE

package/src/parser-safe-region.ts

@@ -0,0 +1,65 @@
+/**
+ * The `feature-adr.js` workflow's PARSER-SAFE REGION — the shared predicate, not a re-implementation.
+ *
+ * The Workflow runtime's parser is STRICTER than `node --check`: inside the routing block that runs
+ * from `const MODELS =` to `const ROUTER =` a template literal is a hard parse error, so no backtick
+ * may appear there. That constraint used to be enforced by a `not.toContain('`')` assertion written
+ * inline in one test (`feature-adr-model-routing.test.ts:142`), which proves only that the SHIPPED
+ * file is currently clean — delete the assertion and nothing goes red.
+ *
+ * ADR-001 / AM-1 asked for the other half: a guard that is PROVEN to fire on a real violation. Making
+ * the predicate a shared export is what buys that — the same function decides the shipped file and the
+ * deliberately mutated copy, so a test can inject one backtick into the region and watch it refuse.
+ * Deleting the guard now deletes the thing the mutation test calls.
+ *
+ * Pure and dependency-free: string in, verdict out. No file I/O, no process state.
+ *
+ * @packageDocumentation
+ */
+
+/** Opening marker of the parser-safe region (the first line of the inlined routing block). */
+export const PARSER_SAFE_REGION_START = 'const MODELS =';
+/** Closing marker of the parser-safe region (the first declaration after the routing block). */
+export const PARSER_SAFE_REGION_END = 'const ROUTER =';
+
+/** Why a source could not be cleared — `null` when the region is clean. */
+export type ParserSafeRegionRefusal =
+  /** a marker is missing or the two markers are out of order: the region cannot be located at all */
+  | 'region-not-found'
+  /** a backtick sits between the two markers — the Workflow parser rejects the file */
+  | 'backtick-in-region';
+
+export interface ParserSafeRegionVerdict {
+  /** true only when the region was LOCATED and contains no backtick. */
+  readonly ok: boolean;
+  /** the refusal reason, or `null` on a clean verdict. */
+  readonly refusal: ParserSafeRegionRefusal | null;
+  /** absolute character offset of the first offending backtick, or `null`. */
+  readonly index: number | null;
+  /** 1-based line number of the first offending backtick, or `null`. */
+  readonly line: number | null;
+}
+
+/**
+ * Decide whether `source` respects the parser-safe region.
+ *
+ * A source whose markers cannot be located is NOT quietly cleared — an unlocatable region is
+ * `region-not-found`, never `ok`. That asymmetry is deliberate: a refactor that moves or renames the
+ * markers must be loud, because a silently-skipped check is indistinguishable from a passing one.
+ */
+export function checkParserSafeRegion(source: string): ParserSafeRegionVerdict {
+  const start = source.indexOf(PARSER_SAFE_REGION_START);
+  const end = source.indexOf(PARSER_SAFE_REGION_END);
+  if (start === -1 || end === -1 || end <= start) {
+    return { ok: false, refusal: 'region-not-found', index: null, line: null };
+  }
+  const offset = source.slice(start, end).indexOf('`');
+  if (offset === -1) return { ok: true, refusal: null, index: null, line: null };
+  const index = start + offset;
+  return {
+    ok: false,
+    refusal: 'backtick-in-region',
+    index,
+    line: source.slice(0, index).split('\n').length,
+  };
+}