@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/fleet.js

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 /**
  * Fleet-home layout (kernel plan v1, M1-P2 step 1; blueprint section 3 with
@@ -78,3 +78,221 @@ export function loadFleet(dir) {
         beaconPath: join(root, BEACON_FILE),
     };
 }
+/**
+ * Classify a layout path without opening it. lstat first, so a symlink is
+ * seen as a symlink; then stat, so a symlink to a directory is a directory
+ * and a dangling one is reported as such rather than as absent.
+ */
+export function classifyLayoutEntry(path) {
+    try {
+        lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "absent" };
+        }
+        return {
+            kind: "unexaminable",
+            reason: `${path} could not be examined: ${String(error)}`,
+        };
+    }
+    let stats;
+    try {
+        stats = statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "other", reason: `${path} is a symlink to nothing` };
+        }
+        return {
+            kind: "unexaminable",
+            reason: `${path} could not be examined: ${String(error)}`,
+        };
+    }
+    if (stats.isDirectory()) {
+        return { kind: "directory" };
+    }
+    return { kind: "other", reason: `${path} exists and is not a directory` };
+}
+/**
+ * The EPHEMERAL directories: exactly the gitignored set, with the trailing
+ * slash that `.gitignore` needs stripped off. DERIVED from FLEET_IGNORED
+ * rather than listed again, because a second list is a second thing to keep
+ * in step and the first divergence would be silent: `tiphys resume` would
+ * rebuild one set while `.gitignore` ignored another.
+ */
+export const EPHEMERAL_DIRS = FLEET_IGNORED.map((entry) => entry.endsWith("/") ? entry.slice(0, -1) : entry);
+/**
+ * The DURABLE directories: every fleet directory that is not ephemeral.
+ * A clone of a fleet home carries these and not the ephemeral ones, which
+ * is the fact `tiphys resume` exists to act on.
+ */
+export const DURABLE_DIRS = FLEET_DIRS.filter((name) => !EPHEMERAL_DIRS.includes(name));
+/**
+ * The durable layout entries missing from dir, in declaration order:
+ * directories first with a trailing slash, then the root files. An empty
+ * result means the directory carries everything a clone of a fleet home
+ * carries, which is the precondition `tiphys resume` requires and never
+ * fabricates.
+ */
+export function missingDurableEntries(dir) {
+    const missing = [];
+    for (const name of DURABLE_DIRS) {
+        if (classifyLayoutEntry(join(dir, name)).kind !== "directory") {
+            missing.push(`${name}/`);
+        }
+    }
+    for (const name of FLEET_FILES) {
+        const p = join(dir, name);
+        if (!existsSync(p) || !statSync(p).isFile()) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+function describePathType(stats) {
+    if (stats.isDirectory()) {
+        return "a directory";
+    }
+    if (stats.isFIFO()) {
+        return "a named pipe";
+    }
+    if (stats.isSocket()) {
+        return "a socket";
+    }
+    if (stats.isCharacterDevice()) {
+        return "a character device";
+    }
+    if (stats.isBlockDevice()) {
+        return "a block device";
+    }
+    return "an entry of an unrecognized type";
+}
+/**
+ * lstat first, so a symlink is seen as a symlink; then stat, so a symlink to
+ * a regular file is regular and a dangling one is reported as such rather
+ * than as absent. The path is never opened.
+ */
+export function classifyPathEntry(path) {
+    try {
+        lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "absent" };
+        }
+        return {
+            kind: "unexaminable",
+            reason: `${path} could not be examined: ${String(error)}`,
+        };
+    }
+    let stats;
+    try {
+        stats = statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "dangling" };
+        }
+        return {
+            kind: "unexaminable",
+            reason: `${path} could not be examined: ${String(error)}`,
+        };
+    }
+    if (stats.isFile()) {
+        return { kind: "regular" };
+    }
+    return {
+        kind: "irregular",
+        reason: `${path} is ${describePathType(stats)}, not a regular file, so it was not opened`,
+    };
+}
+/** THE ONE READ of a path that might not be there and might not be a file. */
+export function readRegularPathIfPresent(path) {
+    const entry = classifyPathEntry(path);
+    if (entry.kind === "absent" || entry.kind === "dangling") {
+        return { kind: "absent" };
+    }
+    if (entry.kind === "irregular" || entry.kind === "unexaminable") {
+        return { kind: "refused", reason: entry.reason };
+    }
+    let body;
+    try {
+        body = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            // Removed between the probe and the read.
+            return { kind: "absent" };
+        }
+        return {
+            kind: "refused",
+            reason: `${path} could not be read: ${String(error)}`,
+        };
+    }
+    return { kind: "read", body };
+}
+/**
+ * Refuse an open-for-WRITE of a path that is not a regular file. The hazard
+ * is symmetric: open(2) for writing on a FIFO with no reader blocks exactly
+ * as reading one with no writer does, so a staged write is as dangerous as a
+ * read. Returns the reason, or undefined when the path may be opened (absent
+ * included: creating it is the point).
+ */
+export function refuseOpenPathForWrite(path) {
+    const entry = classifyPathEntry(path);
+    if (entry.kind === "irregular" || entry.kind === "unexaminable") {
+        return entry.reason;
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ */
+/* The fleet home's SYNC CLASSES                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * THE KERNEL'S OWN WRITE-THEN-RENAME SCRATCH SUFFIXES.
+ *
+ * `FLEET_IGNORED` above is a DENYLIST of three directory prefixes, and
+ * `tiphys sync` derives "durable" as "not covered by it". That derivation is
+ * right for everything the ignore rules were written to cover and blind to a
+ * class they were never asked about: a transient artifact the KERNEL ITSELF
+ * creates beside a TRACKED target, which git therefore reports as an
+ * ordinary new durable path.
+ *
+ * The enumeration behind this list is every path the kernel writes under a
+ * fleet home, classified against `FLEET_IGNORED`. The three that land
+ * DURABLE without being fleet content are:
+ *
+ *   status/current.json.tmp     src/status.ts:142, a fixed name inside the
+ *                               tracked status/ directory.
+ *   .cutover.<random>.tmp       src/cutover.ts:278, a dot-prefixed random
+ *                               name at the fleet ROOT.
+ *   tiphys-environment.json     src/exclusion.ts:303, durable ON PURPOSE
+ *                               (M4-P21 criterion 3) and therefore NOT in
+ *                               this list.
+ *
+ * Two members, two directories, two naming shapes, which is why the rule is
+ * a SUFFIX and not a filename: a rule naming `current.json.tmp` would close
+ * the first and leave the second open.
+ *
+ * `FLEET_IGNORED` IS DELIBERATELY UNCHANGED. It drives `EPHEMERAL_DIRS`,
+ * `DURABLE_DIRS` and the `.gitignore` that `tiphys init` writes, so a glob
+ * added there would become a directory name `tiphys resume` tried to rebuild.
+ * Nothing stops being synced because of this constant; `tiphys sync` gains a
+ * refusal, and only for paths matching a suffix below.
+ */
+export const FLEET_SCRATCH_SUFFIXES = [
+    ".tmp",
+    ".stage",
+    ".mutex",
+];
+/**
+ * True when a fleet-relative path is a kernel scratch artifact by its name
+ * alone. Name-only on purpose: `tiphys sync` asks this about a path git
+ * REPORTED, which may already have been renamed away by the time the
+ * question is asked, so a stat here would answer about a different world
+ * than the one being committed.
+ */
+export function isFleetScratchPath(relativePath) {
+    return FLEET_SCRATCH_SUFFIXES.find((suffix) => relativePath.endsWith(suffix));
+}

package/dist/src/gates/citations.js

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { lstatSync, readdirSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { pathsIdentifySameObject } from "../path-identity.js";
 import { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite, runStep, singleLine, } from "../task.js";
 import { EXIT_GATE_ERROR, exitCodeForStatus, makeGateResult, renderGateResult, } from "./result.js";
 import { formatDiagnostics, loadSchema, validate } from "./validate.js";
@@ -1156,8 +1157,13 @@ export function main(argv) {
         return EXIT_GATE_ERROR;
     }
 }
+// IDENTITY, NOT STRING EQUALITY (M4-P2 fix round, 2026-09-16). `resolve`
+// normalizes relative segments and does NOT resolve symlinks, so an
+// invocation reached through a symlinked directory or through a symlink to
+// this file leaves the two sides as different spellings of one file and
+// this gate silently does nothing. Measured; see src/path-identity.ts:13.
 const invokedDirectly = process.argv[1] !== undefined &&
-    resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+    pathsIdentifySameObject(fileURLToPath(import.meta.url), process.argv[1]);
 if (invokedDirectly) {
     process.exitCode = main(process.argv.slice(2));
 }

package/dist/src/gates/coverage.d.ts

@@ -96,10 +96,13 @@
  * config-supplied pattern (both `idPattern`s and every `bucketKinds[].pattern`)
  * is VALIDATED (compiles, and is rejected if it matches a known
  * catastrophic-backtracking shape) before it is ever executed, and every
- * EXECUTION of a config-supplied pattern is BOUNDED by a wall-clock timeout
- * (`boundedExec`, below), so neither a malformed pattern (CR-990, used to
+ * EXECUTION of a config-supplied pattern is BOUNDED (`boundedExec`, below),
+ * so neither a malformed pattern (CR-990, used to
  * throw with no result record written) nor a ReDoS pattern (CR-991, used
- * to hang indefinitely) can defeat this gate; CR-992 (overlapping kinds)
+ * to hang indefinitely) can defeat this gate. M4-P28 changed WHAT that
+ * bound measures, from elapsed wall clock to CPU work, because the first
+ * one reddened for well-behaved patterns whenever the machine was busy.
+ * CR-992 (overlapping kinds)
  * is folded into the same fix because it is the same "a config string is
  * trusted further than its syntax justifies" mechanism one property over.
  */
@@ -162,29 +165,117 @@ export declare const KERNEL_COVERAGE_CONFIG: CoverageConfig;
  * closes both instances at once.
  */
 export declare function isEmptyCell(value: string): boolean;
-/** Wall-clock bound on one regex execution. Measured (this round): a real
- * catastrophic pattern, `(a+)+b` against 30 a's, which never returns on
- * its own, is interrupted within 251-267ms under this mechanism; a safe
- * pattern executes in under a millisecond, so the bound is not on the
- * critical path for any pattern this repository's own config uses. */
-export declare const REGEX_EXEC_TIMEOUT_MS = 250;
+/**
+ * THE VERDICT-PRODUCING BOUND IS CPU WORK, NOT ELAPSED TIME (M4-P28).
+ *
+ * What this constant replaces, and why the replacement is not a bigger
+ * number. Until this phase the bound was `REGEX_EXEC_TIMEOUT_MS = 250`,
+ * handed to `vm` as a WALL-CLOCK timeout, and exceeding it was reported as
+ * "did not complete within 250ms ... (possible catastrophic
+ * backtracking)". Elapsed wall time is complexity DIVIDED BY available
+ * CPU, so that condition did not test the property it named: it reddened
+ * whenever the machine was busy. Measured and recorded in
+ * delivery/verification/wall-clock-budgets-are-load-dependent.md:1, five
+ * independent witnesses hit it on six structurally different patterns,
+ * including `^(?:parked)$`, a doubly anchored literal with no quantifier,
+ * no character class and no alternation, which has nothing to backtrack
+ * over at any input length. One million executions of
+ * `^(?:R-[0-9]+[a-z]?)$` against `R-094a` take 154.2ms in total, so ONE is
+ * roughly 1.6 million times under the old budget; for one of them to
+ * exceed it the thread must be descheduled for a quarter of a second,
+ * which is a fact about the machine.
+ *
+ * Raising 250 to a larger number was considered and is REJECTED by the
+ * plan (delivery/plan/kernel-plan-m4.md:3784): it keeps the same
+ * instrument and only moves the load at which it lies.
+ *
+ * WHAT IS MEASURED NOW. `process.threadCpuUsage()` reports the CPU time
+ * this thread has consumed, in microseconds. Another process being busy
+ * does not add to it, because a descheduled thread consumes no CPU while
+ * it is not running. The regex runs on THIS thread inside
+ * `runInContext`, so the delta across that call is the work the regex
+ * did, and nothing else. On an interpreter without
+ * `process.threadCpuUsage` (added in Node 22.15; the package floor is 26)
+ * the fallback is `process.cpuUsage()`, which is process-wide and
+ * therefore an over-estimate, never an under-estimate, so the fallback
+ * cannot let a catastrophic pattern through.
+ */
+export declare const REGEX_EXEC_CPU_BUDGET_MS = 250;
+/**
+ * HOW LONG ONE ATTEMPT IS WILLING TO WAIT. This is PATIENCE, not a
+ * verdict: nothing is ever reported about a pattern because this elapsed.
+ * A wall-clock interrupt is still needed, because a catastrophic match
+ * never returns on its own and `vm`'s `timeout` is the only mechanism
+ * here that can stop one (v8 checks for the termination request during a
+ * regex match, not only between statements).
+ *
+ * It is set to TWICE the CPU budget so that a thread receiving at least
+ * half of one CPU reaches the budget inside a single attempt; measured on
+ * an unloaded box, `(a+)+b` against 30 a's consumes 230.6ms of CPU in a
+ * 252ms wall window, so a backstop equal to the budget would have needed
+ * a second attempt to reach a verdict it had nearly earned.
+ */
+export declare const REGEX_EXEC_WALL_BACKSTOP_MS = 500;
+/**
+ * How many interrupted attempts before this module admits it cannot
+ * reach a verdict. Each attempt doubles its own patience, and the CPU
+ * consumed ACCUMULATES across attempts, so a genuinely spinning pattern
+ * is still caught on a loaded machine (it burns CPU whenever it runs)
+ * while a benign one accumulates microseconds however often it is
+ * interrupted.
+ */
+export declare const REGEX_EXEC_MAX_ATTEMPTS = 4;
+/** The pattern did too much WORK. A verdict about the pattern. */
 export declare class RegexBoundExceededError extends Error {
 }
 /**
- * Execute `compiled.exec(value)` inside a v8 context with a wall-clock
- * timeout. `node:vm`'s `timeout` option interrupts synchronous JavaScript
- * execution, INCLUDING regex backtracking (v8 checks for the termination
- * request during a regex match, not only between statements), which is
- * why this bound can stop a hung `.exec()` where a plain try/catch around
- * a synchronous call cannot: a catastrophic match never throws on its
- * own, it simply never returns. Measured directly (this round): the same
- * `(a+)+b` pattern against inputs of length 18 through 40 completes in
- * under 40ms up to length 22, then 63ms, 302ms, and is interrupted at the
- * 250ms bound from length 26 onward, rather than running to the multi-
- * second and then multi-minute times the unbounded engine produces at
- * length 26 and 40.
+ * No verdict was reached: every attempt was interrupted before the
+ * pattern finished, and the CPU it consumed never came near the budget,
+ * which is the signature of a thread that is not being scheduled rather
+ * than one that is spinning. Under M2-C-3 a check that cannot reach a
+ * verdict reports ERROR, never a verdict it did not earn, so this is
+ * deliberately NOT a subclass of `RegexBoundExceededError`: the two must
+ * not be confusable by a `catch` or an `instanceof`.
+ */
+export declare class RegexBudgetUndeterminedError extends Error {
+}
+/** Overrides for one call, used by the witness tests to stand in for a
+ * machine slower or busier than this one. Only the PATIENCE is varied
+ * there; the verdict instrument stays the CPU budget. */
+export interface RegexExecBounds {
+    cpuBudgetMs?: number;
+    wallBackstopMs?: number;
+    maxAttempts?: number;
+}
+/**
+ * Execute `compiled.exec(value)` inside a v8 context, bounded by the CPU
+ * WORK it does rather than by the time it takes.
+ *
+ * One attempt runs the match with a wall-clock interrupt. Whatever
+ * happens, the CPU consumed by this thread during that call is added to a
+ * running total:
+ *
+ *   - total CPU at or above the budget: the thread really did burn that
+ *     much CPU on this one match, which no anchored non-backtracking
+ *     pattern can do, so `RegexBoundExceededError` is thrown. A busy
+ *     machine cannot cause this, because a descheduled thread accumulates
+ *     no CPU.
+ *   - the match finished: return its result, which is the only path that
+ *     produces a match.
+ *   - interrupted with the total still far below the budget: the machine
+ *     was busy, not the pattern. Double the patience and try again.
+ *
+ * After `maxAttempts` interruptions with the CPU total still under
+ * budget, `RegexBudgetUndeterminedError` is thrown, naming the CPU
+ * consumed, the wall clock spent and the load average, so the record says
+ * what it observed instead of asserting something about the pattern.
+ *
+ * An error from `runInContext` that is NOT the timeout is also
+ * undetermined rather than a finding: the old code funnelled every throw
+ * into the catastrophic-backtracking message, which is the same
+ * substitution one cause over.
  */
-export declare function boundedExec(compiled: RegExp, value: string): RegExpExecArray | null;
+export declare function boundedExec(compiled: RegExp, value: string, bounds?: RegexExecBounds): RegExpExecArray | null;
 /**
  * A STATIC heuristic for the single most common catastrophic-backtracking
  * shape (fix round 1, CR-991): a parenthesised group containing an

package/dist/src/gates/coverage.js

@@ -1,7 +1,9 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { pathsIdentifySameObject } from "../path-identity.js";
 import { Script, createContext } from "node:vm";
+import { cpus, loadavg } from "node:os";
 import { readRegularFileIfPresent, refuseOpenForWrite, runStep, singleLine, } from "../task.js";
 import { loadSchema, validate } from "./validate.js";
 import { EXIT_GATE_ERROR, exitCodeForStatus, makeGateResult, renderGateResult, } from "./result.js";
@@ -70,41 +72,166 @@ export function isEmptyCell(value) {
  * meaningfully slower in this round's own benchmark than reusing one.
  */
 const regexSandbox = createContext(Object.create(null));
-/** Wall-clock bound on one regex execution. Measured (this round): a real
- * catastrophic pattern, `(a+)+b` against 30 a's, which never returns on
- * its own, is interrupted within 251-267ms under this mechanism; a safe
- * pattern executes in under a millisecond, so the bound is not on the
- * critical path for any pattern this repository's own config uses. */
-export const REGEX_EXEC_TIMEOUT_MS = 250;
+/**
+ * THE VERDICT-PRODUCING BOUND IS CPU WORK, NOT ELAPSED TIME (M4-P28).
+ *
+ * What this constant replaces, and why the replacement is not a bigger
+ * number. Until this phase the bound was `REGEX_EXEC_TIMEOUT_MS = 250`,
+ * handed to `vm` as a WALL-CLOCK timeout, and exceeding it was reported as
+ * "did not complete within 250ms ... (possible catastrophic
+ * backtracking)". Elapsed wall time is complexity DIVIDED BY available
+ * CPU, so that condition did not test the property it named: it reddened
+ * whenever the machine was busy. Measured and recorded in
+ * delivery/verification/wall-clock-budgets-are-load-dependent.md:1, five
+ * independent witnesses hit it on six structurally different patterns,
+ * including `^(?:parked)$`, a doubly anchored literal with no quantifier,
+ * no character class and no alternation, which has nothing to backtrack
+ * over at any input length. One million executions of
+ * `^(?:R-[0-9]+[a-z]?)$` against `R-094a` take 154.2ms in total, so ONE is
+ * roughly 1.6 million times under the old budget; for one of them to
+ * exceed it the thread must be descheduled for a quarter of a second,
+ * which is a fact about the machine.
+ *
+ * Raising 250 to a larger number was considered and is REJECTED by the
+ * plan (delivery/plan/kernel-plan-m4.md:3784): it keeps the same
+ * instrument and only moves the load at which it lies.
+ *
+ * WHAT IS MEASURED NOW. `process.threadCpuUsage()` reports the CPU time
+ * this thread has consumed, in microseconds. Another process being busy
+ * does not add to it, because a descheduled thread consumes no CPU while
+ * it is not running. The regex runs on THIS thread inside
+ * `runInContext`, so the delta across that call is the work the regex
+ * did, and nothing else. On an interpreter without
+ * `process.threadCpuUsage` (added in Node 22.15; the package floor is 26)
+ * the fallback is `process.cpuUsage()`, which is process-wide and
+ * therefore an over-estimate, never an under-estimate, so the fallback
+ * cannot let a catastrophic pattern through.
+ */
+export const REGEX_EXEC_CPU_BUDGET_MS = 250;
+/**
+ * HOW LONG ONE ATTEMPT IS WILLING TO WAIT. This is PATIENCE, not a
+ * verdict: nothing is ever reported about a pattern because this elapsed.
+ * A wall-clock interrupt is still needed, because a catastrophic match
+ * never returns on its own and `vm`'s `timeout` is the only mechanism
+ * here that can stop one (v8 checks for the termination request during a
+ * regex match, not only between statements).
+ *
+ * It is set to TWICE the CPU budget so that a thread receiving at least
+ * half of one CPU reaches the budget inside a single attempt; measured on
+ * an unloaded box, `(a+)+b` against 30 a's consumes 230.6ms of CPU in a
+ * 252ms wall window, so a backstop equal to the budget would have needed
+ * a second attempt to reach a verdict it had nearly earned.
+ */
+export const REGEX_EXEC_WALL_BACKSTOP_MS = 500;
+/**
+ * How many interrupted attempts before this module admits it cannot
+ * reach a verdict. Each attempt doubles its own patience, and the CPU
+ * consumed ACCUMULATES across attempts, so a genuinely spinning pattern
+ * is still caught on a loaded machine (it burns CPU whenever it runs)
+ * while a benign one accumulates microseconds however often it is
+ * interrupted.
+ */
+export const REGEX_EXEC_MAX_ATTEMPTS = 4;
+/** The pattern did too much WORK. A verdict about the pattern. */
 export class RegexBoundExceededError extends Error {
 }
 /**
- * Execute `compiled.exec(value)` inside a v8 context with a wall-clock
- * timeout. `node:vm`'s `timeout` option interrupts synchronous JavaScript
- * execution, INCLUDING regex backtracking (v8 checks for the termination
- * request during a regex match, not only between statements), which is
- * why this bound can stop a hung `.exec()` where a plain try/catch around
- * a synchronous call cannot: a catastrophic match never throws on its
- * own, it simply never returns. Measured directly (this round): the same
- * `(a+)+b` pattern against inputs of length 18 through 40 completes in
- * under 40ms up to length 22, then 63ms, 302ms, and is interrupted at the
- * 250ms bound from length 26 onward, rather than running to the multi-
- * second and then multi-minute times the unbounded engine produces at
- * length 26 and 40.
+ * No verdict was reached: every attempt was interrupted before the
+ * pattern finished, and the CPU it consumed never came near the budget,
+ * which is the signature of a thread that is not being scheduled rather
+ * than one that is spinning. Under M2-C-3 a check that cannot reach a
+ * verdict reports ERROR, never a verdict it did not earn, so this is
+ * deliberately NOT a subclass of `RegexBoundExceededError`: the two must
+ * not be confusable by a `catch` or an `instanceof`.
  */
-export function boundedExec(compiled, value) {
-    Object.assign(regexSandbox, { __pattern: compiled, __value: value, __out: undefined });
-    try {
-        new Script("__out = __pattern.exec(__value);").runInContext(regexSandbox, {
-            timeout: REGEX_EXEC_TIMEOUT_MS,
-        });
-    }
-    catch {
-        throw new RegexBoundExceededError(`pattern ${compiled.source} did not complete within ${String(REGEX_EXEC_TIMEOUT_MS)}ms ` +
-            `against a value of length ${String(value.length)} (possible catastrophic backtracking)`);
+export class RegexBudgetUndeterminedError extends Error {
+}
+/** Thread CPU time where the interpreter has it, process CPU otherwise. */
+function cpuSample() {
+    const threadReader = process.threadCpuUsage;
+    if (typeof threadReader === "function") {
+        return threadReader.call(process);
     }
-    const out = regexSandbox.__out;
-    return out ?? null;
+    return process.cpuUsage();
+}
+/** Milliseconds of CPU (user plus system) between two samples. */
+function cpuMillisBetween(before, after) {
+    return (after.user - before.user + (after.system - before.system)) / 1000;
+}
+/**
+ * Execute `compiled.exec(value)` inside a v8 context, bounded by the CPU
+ * WORK it does rather than by the time it takes.
+ *
+ * One attempt runs the match with a wall-clock interrupt. Whatever
+ * happens, the CPU consumed by this thread during that call is added to a
+ * running total:
+ *
+ *   - total CPU at or above the budget: the thread really did burn that
+ *     much CPU on this one match, which no anchored non-backtracking
+ *     pattern can do, so `RegexBoundExceededError` is thrown. A busy
+ *     machine cannot cause this, because a descheduled thread accumulates
+ *     no CPU.
+ *   - the match finished: return its result, which is the only path that
+ *     produces a match.
+ *   - interrupted with the total still far below the budget: the machine
+ *     was busy, not the pattern. Double the patience and try again.
+ *
+ * After `maxAttempts` interruptions with the CPU total still under
+ * budget, `RegexBudgetUndeterminedError` is thrown, naming the CPU
+ * consumed, the wall clock spent and the load average, so the record says
+ * what it observed instead of asserting something about the pattern.
+ *
+ * An error from `runInContext` that is NOT the timeout is also
+ * undetermined rather than a finding: the old code funnelled every throw
+ * into the catastrophic-backtracking message, which is the same
+ * substitution one cause over.
+ */
+export function boundedExec(compiled, value, bounds = {}) {
+    const cpuBudgetMs = bounds.cpuBudgetMs ?? REGEX_EXEC_CPU_BUDGET_MS;
+    const maxAttempts = bounds.maxAttempts ?? REGEX_EXEC_MAX_ATTEMPTS;
+    let patienceMs = bounds.wallBackstopMs ?? REGEX_EXEC_WALL_BACKSTOP_MS;
+    let cpuSpentMs = 0;
+    let wallSpentMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        Object.assign(regexSandbox, { __pattern: compiled, __value: value, __out: undefined });
+        const cpuBefore = cpuSample();
+        const wallBefore = Date.now();
+        let failure;
+        let interrupted = false;
+        try {
+            new Script("__out = __pattern.exec(__value);").runInContext(regexSandbox, {
+                timeout: patienceMs,
+            });
+        }
+        catch (error) {
+            failure = error;
+            interrupted = error.code === "ERR_SCRIPT_EXECUTION_TIMEOUT";
+        }
+        cpuSpentMs += cpuMillisBetween(cpuBefore, cpuSample());
+        wallSpentMs += Date.now() - wallBefore;
+        if (cpuSpentMs >= cpuBudgetMs) {
+            throw new RegexBoundExceededError(`pattern ${compiled.source} consumed ${cpuSpentMs.toFixed(1)}ms of CPU time ` +
+                `(budget ${String(cpuBudgetMs)}ms) against a value of length ${String(value.length)} ` +
+                `over ${String(attempt)} attempt(s) spanning ${String(wallSpentMs)}ms of wall clock ` +
+                "(catastrophic backtracking)");
+        }
+        if (failure !== undefined && !interrupted) {
+            throw new RegexBudgetUndeterminedError(`pattern ${compiled.source} against a value of length ${String(value.length)} ` +
+                `failed to execute: ${String(failure.message ?? failure)}; no verdict ` +
+                "about the pattern was reached");
+        }
+        if (!interrupted) {
+            const out = regexSandbox.__out;
+            return out ?? null;
+        }
+        patienceMs *= 2;
+    }
+    throw new RegexBudgetUndeterminedError(`pattern ${compiled.source} against a value of length ${String(value.length)} was ` +
+        `interrupted on all ${String(maxAttempts)} attempts after ${String(wallSpentMs)}ms of wall ` +
+        `clock, having consumed only ${cpuSpentMs.toFixed(1)}ms of CPU time against a budget of ` +
+        `${String(cpuBudgetMs)}ms; load average ${loadavg()[0]?.toFixed(2) ?? "unknown"} on ` +
+        `${String(cpus().length)} cpu(s). No verdict about the pattern was reached: this record ` +
+        "reports that the machine was too busy to establish one, not that the pattern is dangerous");
 }
 /**
  * A STATIC heuristic for the single most common catastrophic-backtracking
@@ -690,7 +817,15 @@ function emit(resultPath, fields) {
  * functions through the computed-URL pattern and must not trigger a CLI
  * run as a side effect of that import.
  */
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+// IDENTITY, NOT STRING EQUALITY (M4-P2 fix round, 2026-09-16). Measured:
+// through a symlinked directory in the invocation path, or through a
+// symlink to this file, argv[1] carries the caller's spelling while
+// import.meta.url carries the canonical one, so the bare comparison is
+// false and this gate silently does nothing and exits 0. That is a guard
+// that cannot go red (T-008), and six sibling gates already compare by
+// identity.
+if (process.argv[1] !== undefined &&
+    pathsIdentifySameObject(fileURLToPath(import.meta.url), process.argv[1])) {
     try {
         process.exitCode = main(process.argv.slice(2));
     }