@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/watcher.js

@@ -3,7 +3,7 @@ import { closeSync, fsyncSync, openSync, renameSync, statSync, unlinkSync, watch
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { CADENCE, readBeacon, renderBeacon, surveyTaskRecords, } from "./liveness.js";
-import { classifyEntry, executorRecordPath, readRegularFileIfPresent, refuseOpenForWrite, runStep, turnEndPath, } from "./task.js";
+import { classifyEntry, executorRecordPath, readRegularFileIfPresent, refuseOpenForWrite, runStep, runStepAsync, turnEndPath, } from "./task.js";
 /**
  * The watcher (kernel plan v1, M1-P5 step 1; R-078, R-079; DR-0007;
  * plan constraints C-1, C-2 and C-3).
@@ -689,16 +689,6 @@ function loadOrInitCadence(fleet, nowMs) {
     writeCadenceState(fleet, fresh);
     return fresh;
 }
-/** runStep's shape for an async step (src/task.ts covers the sync one). */
-async function runStepAsync(what, step) {
-    try {
-        return { ok: true, value: await step() };
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        return { ok: false, reason: `${what} failed: ${detail}` };
-    }
-}
 /**
  * Scan and, if there is something to surface, surface it. Returns
  * undefined ONLY when nothing was surfaced and that is a fact this pass

package/dist/src/witness/run.d.ts

@@ -49,6 +49,26 @@ export interface DiffFile {
 export interface PhaseDiff {
     baseSha: string;
     headSha: string;
+    /**
+     * The merge base of base and head, which is the revision the `base...head`
+     * three-dot diff below is actually taken against. Anything asking "what did
+     * this phase change" must read the old side HERE and not at `baseSha`: on a
+     * branch that has fallen behind, `baseSha` carries commits the branch never
+     * saw, and reading them as the branch's own starting point reproduces the
+     * two-dot misreading of standing warning 13.
+     *
+     * It falls back to `baseSha` when git computes no merge base, and THAT
+     * FALLBACK IS UNREACHABLE THROUGH THIS FUNCTION, which is said here rather
+     * than left for a reader to assume it is a tested path. Measured 2026-08-15
+     * on two orphan roots in one repository: `git merge-base A B` exits 1 with no
+     * output, and `git diff --name-status --no-renames A...B` exits 128 with
+     * `fatal: <A>...<B>: no merge base`. The diff below is the same three-dot
+     * form, so `computePhaseDiff` returns `ok: false` on the diff and never
+     * reaches the assignment. The fallback stays because the alternative is
+     * `"".trim()` silently becoming a sha-shaped empty string, which is a worse
+     * failure than an unreachable line.
+     */
+    mergeBaseSha: string;
     files: Map<string, DiffFile>;
 }
 export interface EvaluationInputs {
@@ -67,8 +87,18 @@ export interface EvaluationInputs {
     /** Changed files the spawn grep matched (rule (f) derivation). */
     spawningChangedFiles: string[];
     scratchRoot: string;
-    /** True for the phase's own witnesses; rule (d) applies only to them. */
-    phaseOwn: boolean;
+    /**
+     * Indices into `spec.dangerousStates` that THIS PHASE AUTHORED, which is
+     * the exact scope of rule (d). Empty for a stored witness the phase did not
+     * touch, and empty is the whole of "rule (d) does not apply here".
+     *
+     * This replaced a file-granular `phaseOwn: boolean`. The boolean was decided
+     * by the spec FILE appearing in the diff and then gated a PER MEMBER
+     * obligation, so any edit to any member imposed rule (d) on every sibling
+     * member of the same file. See `phaseOwnedMemberIndices` in ../witness/spec.ts
+     * for the derivation and for why an unreadable baseline owns everything.
+     */
+    phaseOwnedMembers: ReadonlySet<number>;
     hooks?: WitnessHooks;
 }
 export interface MemberRun {
@@ -134,11 +164,6 @@ interface GitResult {
     stderr: string;
     reason: string;
 }
-/**
- * Run git with a pinned C locale (verification-m1-p3-fix-round.md U-8: a
- * message-text classification with no locale pin silently stops matching in
- * a localized environment).
- */
 export declare function gitIn(cwd: string, args: string[]): GitResult;
 /**
  * Compute the phase diff base...head: changed files with status and the

package/dist/src/witness/run.js

@@ -11,10 +11,23 @@ import { describeMember, memberTouchedFiles } from "./spec.js";
  * message-text classification with no locale pin silently stops matching in
  * a localized environment).
  */
+/* THE DEFAULT maxBuffer IS 1 MiB AND A PHASE DIFF EXCEEDS IT, which turns this
+   helper's ENOBUFS into a gate `error` on exactly the pull requests that carry
+   the most to check. Measured 2026-08-15 on the M3 exit-test bundle:
+   `git diff -U0 --no-renames origin/main...HEAD` produced 9,120,827 bytes and
+   `red-witness` reported
+   `error: ... could not be run: Error: spawnSync git ENOBUFS`.
+
+   A cap is still wanted rather than none, so that a runaway diff fails loudly
+   instead of exhausting memory; 256 MiB is far above any real diff and far
+   below that risk. The failure remains an `error` with its reason, never a
+   green, which is M2-C-3. */
+const GIT_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
 export function gitIn(cwd, args) {
     const result = spawnSync("git", args, {
         cwd,
         encoding: "utf8",
+        maxBuffer: GIT_MAX_BUFFER_BYTES,
         env: { ...process.env, LC_ALL: "C", LANG: "C" },
     });
     if (result.error !== undefined) {
@@ -63,6 +76,8 @@ export function computePhaseDiff(repoRoot, base, head) {
     }
     const baseSha = baseResolved.stdout.trim();
     const headSha = headResolved.stdout.trim();
+    const mergeBase = gitIn(repoRoot, ["merge-base", baseSha, headSha]);
+    const mergeBaseSha = mergeBase.ok ? mergeBase.stdout.trim() : baseSha;
     const names = gitIn(repoRoot, [
         "diff",
         "--name-status",
@@ -108,7 +123,7 @@ export function computePhaseDiff(repoRoot, base, head) {
             }
         }
     }
-    return { ok: true, diff: { baseSha, headSha, files } };
+    return { ok: true, diff: { baseSha, headSha, mergeBaseSha, files } };
 }
 /**
  * The spawn grep of rule (f), over the changed files' head-state contents.
@@ -934,8 +949,31 @@ function evaluateRefusalRules(spec, inputs, namedTestFiles, derivation) {
         }
     }
     // (f) derived capture obligation from the spawn grep over changed files.
+    //
+    // THE SCOPE IS PER MEMBER, exactly as rule (d)'s is eleven lines down, and
+    // for the same reason. `7b18144` fixed that scope for rule (d) and left its
+    // sibling reading EVERY member of the spec, so an obligation derived from a
+    // file THIS PHASE changed was imposed on members the phase never authored,
+    // and could not have been discharged when they were written.
+    //
+    // MEASURED, M4-P11 at `a7d007f`: giving `src/checks.ts` its first subprocess
+    // call turned it into a spawning changed file and reddened THIRTY-NINE
+    // pre-existing witness specs over checklist parsing, verdict vocabulary,
+    // mode enums and hazard resolution. None of them had anything to do with git
+    // output; none of them could have declared a capture, because `src/checks.ts`
+    // spawned nothing when they were written. A required gate went red for every
+    // spec in a file's neighbourhood because one unrelated line was added.
+    //
+    // WHAT THE RULE STILL BINDS, so this is a scope correction and not a defang:
+    // a member THIS PHASE added or changed that touches a spawning changed file
+    // takes the capture obligation in full. Editing a member makes it owned, so
+    // a phase cannot launder an old member into an exemption by rewriting it.
     const touched = new Set();
-    for (const member of spec.dangerousStates) {
+    for (let index = 0; index < spec.dangerousStates.length; index += 1) {
+        if (!inputs.phaseOwnedMembers.has(index)) {
+            continue;
+        }
+        const member = spec.dangerousStates[index];
         for (const file of memberTouchedFiles(member, readPatch)) {
             touched.add(file);
         }
@@ -947,36 +985,44 @@ function evaluateRefusalRules(spec, inputs, namedTestFiles, derivation) {
             `spawn-and-parse) matched, so consumesExternalOutput is required and ` +
             `this witness omits it`);
     }
-    // (d) diff intersection, for the phase's own witnesses.
-    if (inputs.phaseOwn) {
-        for (let index = 0; index < spec.dangerousStates.length; index += 1) {
-            const member = spec.dangerousStates[index];
-            if (member.kind === "baseline-ref") {
-                continue;
+    // (d) diff intersection, for the members THIS PHASE AUTHORED.
+    //
+    // The scope is per MEMBER, never per spec file: `inputs.phaseOwnedMembers`
+    // carries the indices the phase added or changed relative to the merge base.
+    // A member a sibling edit dragged into the file's diff is not owned and
+    // takes no obligation from this rule. The property rule (d) protects is
+    // unchanged: a member this phase AUTHORED must intersect this phase's diff,
+    // so a phase still cannot add a dangerous state about unrelated code.
+    for (let index = 0; index < spec.dangerousStates.length; index += 1) {
+        if (!inputs.phaseOwnedMembers.has(index)) {
+            continue;
+        }
+        const member = spec.dangerousStates[index];
+        if (member.kind === "baseline-ref") {
+            continue;
+        }
+        const files = memberTouchedFiles(member, readPatch);
+        const changedTouched = files.filter((file) => inputs.diff.files.has(file));
+        if (changedTouched.length === 0) {
+            reasons.push(`rule (d): declared dangerous state does not intersect the phase diff ` +
+                `(member ${String(index)}, ${describeMember(member)})`);
+            continue;
+        }
+        if (member.kind === "mutation") {
+            const diffFile = inputs.diff.files.get(member.file);
+            const shown = gitIn(inputs.repoRoot, [
+                "show",
+                `${inputs.headSha}:${member.file}`,
+            ]);
+            let insideHunk = false;
+            if (diffFile !== undefined && shown.ok) {
+                const occupied = findOccurrenceLines(shown.stdout, member.find);
+                insideHunk = occupied.some((lineNo) => diffFile.hunks.some(([start, end]) => lineNo >= start && lineNo <= end));
             }
-            const files = memberTouchedFiles(member, readPatch);
-            const changedTouched = files.filter((file) => inputs.diff.files.has(file));
-            if (changedTouched.length === 0) {
+            if (!insideHunk) {
                 reasons.push(`rule (d): declared dangerous state does not intersect the phase diff ` +
-                    `(member ${String(index)}, ${describeMember(member)})`);
-                continue;
-            }
-            if (member.kind === "mutation") {
-                const diffFile = inputs.diff.files.get(member.file);
-                const shown = gitIn(inputs.repoRoot, [
-                    "show",
-                    `${inputs.headSha}:${member.file}`,
-                ]);
-                let insideHunk = false;
-                if (diffFile !== undefined && shown.ok) {
-                    const occupied = findOccurrenceLines(shown.stdout, member.find);
-                    insideHunk = occupied.some((lineNo) => diffFile.hunks.some(([start, end]) => lineNo >= start && lineNo <= end));
-                }
-                if (!insideHunk) {
-                    reasons.push(`rule (d): declared dangerous state does not intersect the phase diff ` +
-                        `(member ${String(index)}, mutation of ${member.file} touches no ` +
-                        `line inside a changed hunk)`);
-                }
+                    `(member ${String(index)}, mutation of ${member.file} touches no ` +
+                    `line inside a changed hunk)`);
             }
         }
     }

package/dist/src/witness/spec.d.ts

@@ -71,8 +71,176 @@ export type WitnessSpecLoad = {
     reason: string;
     diagnostics: string[];
 };
+/**
+ * Validate and materialise one spec from its BODY, with `label` naming the
+ * source in any reason. Split out of `loadWitnessSpec` so a spec can also be
+ * materialised from a git object (`git show <ref>:<path>`) rather than only
+ * from a working-tree path: the per-member ownership derivation below needs
+ * the merge-base version of a spec, which has no path.
+ */
+export declare function parseWitnessSpec(body: string, label: string): WitnessSpecLoad;
 /** Load and validate one spec from a path the caller supplied (M2-C-6). */
 export declare function loadWitnessSpec(path: string): WitnessSpecLoad;
+/**
+ * How a patch member's BODY is read, one reader per revision. A patch member's
+ * `patch` field is a PATH; the dangerous state it declares lives in the file at
+ * that path, so establishing whether the member changed needs the body on BOTH
+ * sides, at the merge base and at the audited head.
+ */
+export interface PatchBodyReaders {
+    head: (patchPath: string) => string | undefined;
+    baseline: (patchPath: string) => string | undefined;
+}
+/**
+ * CANONICAL FORM OF ONE DANGEROUS-STATE MEMBER: everything that determines the
+ * dangerous state, in a fixed order, JSON-encoded. Two members are the SAME
+ * member when their canonical forms are equal. Field order inside the source
+ * document is not significant, so reformatting a spec is not authorship.
+ *
+ * PER KIND, and the three kinds are NOT alike, which is the correction fix
+ * round 1 makes:
+ *
+ * - `mutation` declares `file`, `find` and `replace`, and all three are INLINE
+ *   in the spec document. The canonical form carries all three, so it is
+ *   complete: nothing outside the document can change what this member does.
+ * - `patch` declares one field, `patch`, and it is a POINTER. The dangerous
+ *   state is the patch FILE'S BODY, which lives outside the spec document
+ *   entirely. Keying on the path alone made a member whose body was rewritten
+ *   top to bottom compare EQUAL to its own previous version, so a phase could
+ *   turn a dangerous state about file X into one about an unrelated file Y and
+ *   be judged not to have authored it. The body's sha256 is therefore part of
+ *   the canonical form. An unreadable body yields `undefined`, which the caller
+ *   treats as "cannot be established", never as "unchanged".
+ * - `baseline-ref` declares `ref`, which is ALSO a pointer: the dangerous state
+ *   is the whole tree at that ref, and a ref moves. It is deliberately NOT
+ *   resolved, for two reasons stated rather than assumed. First, rule (d)
+ *   SKIPS `baseline-ref` members outright (src/witness/run.ts:1295), so a
+ *   baseline-ref member's ownership has no consequence anywhere: ownership is
+ *   read in exactly one place and that place skips this kind. Second, resolving
+ *   the ref would attribute a ref moved by SOMEBODY ELSE to this phase, which
+ *   is the opposite of what an authorship derivation should say. If rule (d)
+ *   ever stops skipping this kind, this decision has to be revisited, and the
+ *   fix would be the patch one: fold the resolved tree, not the ref name.
+ */
+export declare function canonicalMember(member: DangerousStateMember, readPatchBody: (patchPath: string) => string | undefined): string | undefined;
+/**
+ * HAS THE SPEC BEEN RE-POINTED, as opposed to strengthened?
+ *
+ * A witness spec says "these named TESTS guard this BEHAVIOR, and here are the
+ * dangerous states they have been shown red against". Rule (d) is an obligation
+ * on that sentence, not only on its members: it exists so a phase cannot claim
+ * coverage using a dangerous state about code it did not touch. So a phase that
+ * rewrites the sentence takes the obligation for every state offered under it.
+ *
+ * THE TEST IS DIRECTIONAL, NOT EQUALITY, AND THAT DISTINCTION IS THE WHOLE
+ * FUNCTION. Fix round 1 compared `[behavior, sortedTests]` for equality, which
+ * is wrong in the safe direction and was caught by delta verification: a phase
+ * that ADDS one guarding test to an existing spec, changing no member and no
+ * behavior, was told its untouched siblings had to intersect the diff. Adding a
+ * test is not a re-point. It is strictly strengthening, and that is a MEASURED
+ * property of the harness rather than a judgement:
+ *
+ *   - RED arm, src/witness/run.ts:918: `red: exitCode !== 0 && failed.length
+ *     === tests.length`. A repetition counts as red only when EVERY named test
+ *     failed, so an added test must ALSO redden against every declared
+ *     dangerous state or the member stops being red and the spec goes red.
+ *   - GREEN arm, src/witness/run.ts:1676: `headGreen = exitCode === 0 &&
+ *     passedNamedTests.length === spec.tests.length`. An added test must ALSO
+ *     pass at head.
+ *
+ * Both arms gain an obligation, neither loses one, and both are demonstrated by
+ * EXECUTION rather than accepted on trust. So there is nothing for rule (d) to
+ * police in an extension: no new dangerous state is declared, and the existing
+ * states' burden only grows.
+ *
+ * WHAT STILL COUNTS AS RE-POINTING, and each is a real relaxation:
+ *
+ * - `behavior` changed. The sentence is now about something else, and an older
+ *   phase's dangerous state becomes evidence for a behavior this phase
+ *   introduced. Any change, in either direction.
+ * - A baseline test name DROPPED. That relaxes both arms above: one fewer test
+ *   must redden against every member and one fewer must pass at head. A phase
+ *   can drop the test that was doing the work and keep the coverage claim.
+ * - A test name SWAPPED, which is a drop plus an addition and is caught by the
+ *   drop half.
+ *
+ * So the predicate is `behavior` equality AND `baselineTests` being a SUBSET of
+ * `headTests`. Reordering is not a change: the comparison is over sets, which
+ * is the same positional indifference the member matching gets from comparing
+ * canonical forms rather than indices. Duplicates in `tests` collapse under set
+ * semantics, and that is harmless because both arms above count `tests`
+ * positionally on the same array, so a duplicate adds an obligation to each
+ * side identically.
+ *
+ * WHY MEMBERS ARE NOT TREATED THE SAME WAY, since adding a member also only
+ * ADDS an obligation (every member must independently redden). Because a member
+ * IS the thing rule (d) is an obligation on, and a test is not. An added member
+ * is a newly declared dangerous state, and checking that a declared dangerous
+ * state relates to the phase's own diff is the entire purpose of the rule; make
+ * added members exempt and rule (d) is empty. An added test declares no
+ * dangerous state at all.
+ *
+ * WHICH FIELDS ARE CONSIDERED, AND WHY THE OTHERS ARE NOT. The test applied to
+ * every field of the closed schema was: does changing THIS FIELD ALONE let a
+ * phase assert something new about its own diff while reusing a dangerous state
+ * somebody else authored?
+ *
+ * - `behavior`, `tests`: YES, in the directional sense above. IN.
+ * - `class`: NO. It selects which refusal rules apply (rules (a), (e), (g)) and
+ *   none of them is ownership-gated, so a class change is evaluated in full on
+ *   every run whether the spec is owned or not. A weakened class is refused by
+ *   rule (e), which DERIVES the class from the named tests' sources rather than
+ *   trusting the declaration. OUT, and including it would buy false reds on
+ *   class fix-ups while closing no attack.
+ * - `id`: NO. It is the handle, checked for collisions at
+ *   src/gates/red-witness.ts:263. Renaming a spec asserts nothing new. OUT.
+ * - `deterministic`, `repeats`: NO. They set the red THRESHOLD in the member
+ *   execution loop (src/witness/run.ts:1517 and src/witness/run.ts:1605), which
+ *   runs for every member of every evaluated spec regardless of ownership. OUT.
+ * - `consumesExternalOutput`: NO. Rules (c) and (f) read it and neither is
+ *   ownership-gated. OUT.
+ */
+export declare function claimRePointed(headSpec: WitnessSpec, baselineSpec: WitnessSpec): boolean;
+/**
+ * WHICH MEMBERS OF A SPEC THIS PHASE AUTHORED (the ownership scope of rule
+ * (d)).
+ *
+ * Rule (d) requires a declared dangerous state to intersect the phase diff, so
+ * that a phase cannot add a witness about unrelated code and claim coverage.
+ * That obligation is a claim about AUTHORSHIP, and authorship is per MEMBER.
+ * Deriving it from the spec FILE appearing in the diff is one granularity too
+ * coarse: it makes every sibling member of an edited file acquire an obligation
+ * its author never took on. Measured by the M3 exit test at stage E1.6, where
+ * repairing one member's quoted source line reddened two untouched members of
+ * the same file.
+ *
+ * THREE WAYS A PHASE AUTHORS, and the round-1 reviews found that only the first
+ * was implemented:
+ *
+ * 1. A member whose CANONICAL FORM changed, which now includes a patch body.
+ * 2. A member with no counterpart at the merge base. Matching is a MULTISET
+ *    consume rather than a set membership test, so a second copy of an existing
+ *    member is authored (rule (g) is what refuses that copy, and it must still
+ *    see it as new).
+ * 3. THE CLAIM WAS RE-POINTED. Then every member is authored, because every
+ *    declared dangerous state is now being offered as evidence for a sentence
+ *    this phase wrote. There is no narrower attribution available: a claim
+ *    change cannot be pinned on one member, since the claim is a property of
+ *    the document. This is the ONLY whole-spec trigger, and keeping it that
+ *    narrow is the point. An edit to a sibling member, a `repeats` bump, a
+ *    reformat, a rename, and ADDING A GUARDING TEST all still author nothing,
+ *    which is what the converse tests hold. `claimRePointed` carries the
+ *    derivation of why extension is safe and dropping a test is not.
+ *
+ * `baselineSpec` is `undefined` when the spec did not exist at the merge base,
+ * did not parse there, or could not be read there. All three mean the phase is
+ * answerable for the whole file, so every member is owned. That is the
+ * conservative direction, and it is applied identically to an unreadable patch
+ * BODY on either side: the failure mode of this derivation is a member wrongly
+ * EXEMPTED, so anything the derivation cannot establish keeps the obligation
+ * rather than dropping it.
+ */
+export declare function phaseOwnedMemberIndices(headSpec: WitnessSpec, baselineSpec: WitnessSpec | undefined, readers: PatchBodyReaders): Set<number>;
 export type WitnessSpecListing = {
     ok: true;
     paths: string[];