loopforge 3.9.4 → 4.0.7

package/dist/evidence-provider.js

@@ -10,11 +10,18 @@
  * execution (v2.0.1), plus explicitly configured shell-free command providers.
  */
 import { createHash } from "node:crypto";
-import { createReadStream, lstatSync, readFileSync, readlinkSync, realpathSync, statSync, } from "node:fs";
-import { spawn, execFile, } from "node:child_process";
+import { readFileSync, realpathSync, statSync, } from "node:fs";
+import { spawn } from "node:child_process";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { GIT_OBSERVATION_SCHEMA_VERSION } from "./protocol.js";
+import { GIT_WORKSPACE_COVERAGE, gitMotionSignal, observedGitHead, } from "./git-motion.js";
 import { containInWorkspace } from "./workspace.js";
+import { isRecord } from "./token-utils.js";
+import { captureBoundary, GitCaptureFailure } from "./git-boundary.js";
+// v3.9.8: the Git boundary implementation moved to git-boundary.ts so evidence
+// and workspace checkpoints share ONE scan. These re-exports keep the existing
+// test/library surface stable.
+export { captureGitFileStateAsync } from "./git-boundary.js";
 import { commandConfigHash, deriveConfiguredCapability, getPolicy, resolveStateDirectory } from "./policy.js";
 import { logEvent } from "./observability.js";
 import { policyMetrics } from "./policy-metrics.js";
@@ -118,6 +125,18 @@ export function capabilityWarnings(configured, policy, observed) {
             "cannot be machine-verified; contract closure will require an explicit " +
             "blocked outcome.");
     }
+    // v3.9.9: the stall rule selects Git workspace coverage explicitly. Without
+    // the Git provider configured there is no workspace evidence basis for a
+    // stall verdict — other providers' facts remain visible but cannot affect
+    // that rule. This is a fact statement, not a blocker.
+    const providerNames = Array.isArray(policy.evidence.providers)
+        ? policy.evidence.providers
+        : [];
+    if (!providerNames.includes("git")) {
+        warnings.push("The Git workspace evidence provider is not configured — the stall rule " +
+            "has no workspace evidence basis this loop. Progress facts from other " +
+            "providers are recorded and displayed but cannot affect stall decisions.");
+    }
     // v3.8.2: a configured command whose harness is named in package.json. The
     // entrypoint set for `npm test` is ["package.json"], so the test files the
     // script actually runs are never in it: editing one is a warning, not a
@@ -191,12 +210,18 @@ function unregisteredProvider(name) {
 }
 /** v3.8: Build the observation a failed capture resolves to. The status names
  *  the machine fact; `detail` explains it for the audit trail. */
+/** v3.9.9: THE per-kind base observation schema table. Custom observations
+ *  keep base 1; only their nested progress snapshot moved to inner 2. */
+export function expectedObservationSchemaVersion(kind) {
+    return kind === "git" ? GIT_OBSERVATION_SCHEMA_VERSION : 1;
+}
 function syntheticObservation(providerId, kind, phase, startedAt, status, detail) {
     return {
         // v3.9.1: a failed Git capture still carries the current Git observation
         // schema so the committed snapshot can be parsed; its non-observed status
-        // is what tells consumers the boundary is unavailable.
-        schemaVersion: kind === "git" ? GIT_OBSERVATION_SCHEMA_VERSION : 1,
+        // is what tells consumers the boundary is unavailable. Every synthetic
+        // observation goes through the ONE per-kind table.
+        schemaVersion: expectedObservationSchemaVersion(kind),
         providerId,
         kind,
         phase,
@@ -207,6 +232,31 @@ function syntheticObservation(providerId, kind, phase, startedAt, status, detail
         data: { detail },
     };
 }
+export function observationVersionIssue(kind, schemaVersion, data, _status) {
+    if (kind !== "git" && kind !== "command" && kind !== "custom") {
+        return {
+            envelope: "observation",
+            schemaVersion: typeof schemaVersion === "number" ? schemaVersion : -1,
+            reason: "schema",
+        };
+    }
+    if (!isRecord(data)) {
+        return {
+            envelope: "observation",
+            schemaVersion: typeof schemaVersion === "number" ? schemaVersion : -1,
+            reason: "malformed",
+        };
+    }
+    const expected = expectedObservationSchemaVersion(kind);
+    if (schemaVersion !== expected) {
+        return {
+            envelope: "observation",
+            schemaVersion: typeof schemaVersion === "number" ? schemaVersion : -1,
+            reason: "schema",
+        };
+    }
+    return null;
+}
 /** Collects observations from all configured providers (always async).
  *
  * v3.8: every configured provider produces exactly one observation per
@@ -255,8 +305,18 @@ export class EvidenceCollector {
                 const capture = Promise.resolve(provider.capture({
                     signal: controller.signal,
                     timeoutMs,
-                    loopId: options.loopId,
+                    ...(options.loopId !== undefined ? { loopId: options.loopId } : {}),
                     phase,
+                    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                    ...(options.materializer
+                        ? { materializer: options.materializer }
+                        : {}),
+                    ...(options.boundarySink
+                        ? { boundarySink: options.boundarySink }
+                        : {}),
+                    ...(options.maxPaths !== undefined
+                        ? { maxPaths: options.maxPaths }
+                        : {}),
                 }));
                 const observation = timeoutMs > 0
                     ? await Promise.race([
@@ -277,10 +337,12 @@ export class EvidenceCollector {
                 }
                 if (!observation) {
                     policyMetrics.recordEvidence(provider.name, "unavailable", Date.now() - startedAt, options.loopId);
-                    return syntheticObservation(provider.name, provider.kind, phase, startedAt, "unavailable", "provider reported no observation");
+                    const unavailable = syntheticObservation(provider.name, provider.kind, phase, startedAt, "unavailable", "provider reported no observation");
+                    return unavailable;
                 }
-                policyMetrics.recordEvidence(provider.name, observation.status === "timeout" ? "timeout" : "available", Date.now() - startedAt, options.loopId);
-                return observation;
+                const normalized = observation;
+                policyMetrics.recordEvidence(provider.name, normalized.status === "timeout" ? "timeout" : "available", Date.now() - startedAt, options.loopId, normalized.status);
+                return normalized;
             }
             catch (error) {
                 policyMetrics.recordEvidence(provider.name, "failure", Date.now() - startedAt, options.loopId);
@@ -580,7 +642,7 @@ export class CommandEvidenceProvider {
     observation(phase, status, exitCode, signal, stdout, stderr, truncated, durationMs, entrypointFiles, failureDetail, stdoutSha256, stderrSha256) {
         const finishedAt = Date.now();
         return {
-            schemaVersion: 1,
+            schemaVersion: expectedObservationSchemaVersion("command"),
             providerId: this.name,
             kind: "command",
             phase,
@@ -608,180 +670,8 @@ export class CommandEvidenceProvider {
         };
     }
 }
-class GitCaptureFailure extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
-        this.name = "GitCaptureFailure";
-    }
-}
-const GIT_MAX_BUFFER = 64 * 1024 * 1024;
-/** Bounded file-hash concurrency. A module constant, not a policy knob. */
-const BOUNDARY_HASH_CONCURRENCY = 16;
-function splitNul(text) {
-    return text.split("\0").filter((entry) => entry.length > 0);
-}
-function uniqueSorted(values) {
-    return [...new Set(values)].sort();
-}
-/** Parse `git ls-files --stage -z`. A conflicted path can have several
- *  stages; stage 0 wins when present, otherwise the first entry is kept. The
- *  worktree fingerprint is what matters, so this is only used to recognise
- *  gitlinks and to carry the index object id. */
-function parseStageEntries(text) {
-    const byPath = new Map();
-    for (const record of splitNul(text)) {
-        const tab = record.indexOf("\t");
-        if (tab < 0)
-            continue;
-        const [mode, object, stage] = record.slice(0, tab).split(" ");
-        if (!mode || !object || !stage)
-            continue;
-        const path = record.slice(tab + 1);
-        if (!path)
-            continue;
-        const existing = byPath.get(path);
-        if (!existing || stage === "0") {
-            byPath.set(path, { entry: { path, mode, object }, stage });
-        }
-    }
-    return [...byPath.values()]
-        .map((item) => item.entry)
-        .sort((a, b) => a.path.localeCompare(b.path));
-}
-/** v3.9.1: capture the complete boundary. All required git commands run in
- *  one parallel batch; HEAD is best-effort (a repository with no commit is a
- *  valid boundary with no head). Any required-command failure returns an
- *  explicit status — never an empty-but-observed boundary. */
-export async function captureGitFileStateAsync(signal, timeoutMs,
-/** Workspace root; injectable so tests can capture against a temp repo.
- *  Defaults to the process cwd, matching the evidence providers. */
-cwd = process.cwd()) {
-    const timeout = timeoutMs ?? 15000;
-    const runGit = (args) => {
-        return new Promise((resolveGit, reject) => {
-            let settled = false;
-            const succeed = (stdout) => {
-                if (settled)
-                    return;
-                settled = true;
-                resolveGit(stdout);
-            };
-            const fail = (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                reject(error);
-            };
-            // M1: core.quotePath=false — git otherwise octal-escapes every path
-            // with bytes >= 0x80. With -z, paths are NUL-delimited raw bytes; the
-            // flag is retained for the HEAD/plain outputs.
-            const child = execFile("git", ["-c", "core.quotePath=false", ...args], {
-                cwd,
-                encoding: "utf-8",
-                timeout,
-                signal,
-                maxBuffer: GIT_MAX_BUFFER,
-                windowsHide: true,
-            });
-            let stdout = "";
-            let stderr = "";
-            child.stdout?.on("data", (chunk) => {
-                stdout += chunk;
-            });
-            child.stderr?.on("data", (chunk) => {
-                stderr += chunk;
-            });
-            child.on("close", (code) => {
-                if (code === 0)
-                    succeed(stdout);
-                else if (code === null) {
-                    // A killed process can close without an exit code. If the error
-                    // event has not settled the promise yet, the measured cause is the
-                    // deadline.
-                    fail(new GitCaptureFailure("timeout", `git ${args[0]} was killed`));
-                }
-                else if (/not a git repository|not a repository/i.test(stderr)) {
-                    fail(new GitCaptureFailure("unavailable", stderr.trim() || "not a git repository"));
-                }
-                else {
-                    fail(new GitCaptureFailure("error", `git ${args[0]} exited ${code}${stderr ? `: ${stderr.trim().slice(0, 300)}` : ""}`));
-                }
-            });
-            child.on("error", (error) => {
-                if (signal?.aborted) {
-                    fail(new GitCaptureFailure("aborted", `git ${args[0]} aborted`));
-                }
-                else if (error.code === "ENOENT") {
-                    fail(new GitCaptureFailure("unavailable", "git executable was not found"));
-                }
-                else if (error.killed || error.signal) {
-                    fail(new GitCaptureFailure("timeout", `git ${args[0]} timed out after ${timeout}ms`));
-                }
-                else if (/not a git repository/i.test(error.message)) {
-                    fail(new GitCaptureFailure("unavailable", error.message));
-                }
-                else {
-                    fail(new GitCaptureFailure("error", error.message));
-                }
-            });
-        });
-    };
-    try {
-        // allSettled, not all: on failure the other children must still finish
-        // before this capture returns, or Windows keeps the workspace directory
-        // locked (and every caller would leak child-process handles).
-        const settled = await Promise.allSettled([
-            runGit(["ls-files", "--stage", "-z"]),
-            runGit(["ls-files", "--others", "--exclude-standard", "-z"]),
-            runGit(["diff", "--name-only", "-z"]),
-            runGit(["diff", "--cached", "--name-only", "-z"]),
-        ]);
-        const failures = settled
-            .filter((item) => item.status === "rejected")
-            .map((item) => item.reason)
-            .filter((error) => error instanceof GitCaptureFailure);
-        if (failures.length > 0) {
-            const failure = failures.find((item) => item.status === "aborted" || item.status === "timeout") ?? failures[0];
-            throw failure;
-        }
-        const rejected = settled.find((item) => item.status === "rejected");
-        if (rejected) {
-            throw new GitCaptureFailure("error", String(rejected.reason));
-        }
-        const [stageOut, untrackedOut, unstagedOut, stagedOut] = settled.map((item) => item.value);
-        let head;
-        try {
-            head = (await runGit(["rev-parse", "--verify", "HEAD"])).trim() || undefined;
-        }
-        catch (error) {
-            // A repository with no commit has no HEAD. Abort still propagates.
-            if (error instanceof GitCaptureFailure && error.status === "aborted")
-                throw error;
-        }
-        const untracked = uniqueSorted(splitNul(untrackedOut));
-        return {
-            ok: true,
-            state: {
-                tracked: parseStageEntries(stageOut),
-                untracked,
-                dirty: uniqueSorted([
-                    ...splitNul(unstagedOut),
-                    ...splitNul(stagedOut),
-                    ...untracked,
-                ]),
-                head,
-            },
-        };
-    }
-    catch (error) {
-        if (error instanceof GitCaptureFailure) {
-            return { ok: false, status: error.status, detail: error.message };
-        }
-        return { ok: false, status: "error", detail: String(error) };
-    }
-}
+// The Git boundary capture/fingerprint implementation lives in
+// git-boundary.ts (shared with workspace checkpoints).
 // ── Built-in: GitEvidenceProvider ──────────────────────────────────────────
 /** The runtime's resolved state directory, or null when it cannot be observed
  *  (configured outside the workspace, or an unresolvable path). */
@@ -800,111 +690,6 @@ function isInsideDirectory(file, workspace, dir) {
     const prefix = dir.endsWith(sep) ? dir : `${dir}${sep}`;
     return absolute === dir || absolute.startsWith(prefix);
 }
-function hashText(text) {
-    return createHash("sha256").update(text).digest("hex");
-}
-/** Stream a regular file through SHA-256 without loading it into memory. */
-function hashFileStream(abs, signal) {
-    return new Promise((resolveHash, reject) => {
-        const hash = createHash("sha256");
-        const stream = createReadStream(abs, { highWaterMark: 64 * 1024 });
-        let settled = false;
-        const cleanup = () => {
-            if (signal)
-                signal.removeEventListener("abort", onAbort);
-        };
-        const finish = (error) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            if (error)
-                reject(error);
-            else
-                resolveHash(hash.digest("hex"));
-        };
-        const onAbort = () => {
-            stream.destroy();
-            finish(new GitCaptureFailure("aborted", "boundary hashing aborted"));
-        };
-        if (signal?.aborted) {
-            onAbort();
-            return;
-        }
-        signal?.addEventListener("abort", onAbort, { once: true });
-        stream.on("data", (chunk) => hash.update(chunk));
-        stream.on("error", (error) => finish(error));
-        stream.on("end", () => finish());
-    });
-}
-/** Fingerprint one boundary path.
- *  - symlinks hash their LINK TEXT; the target is never read
- *  - regular files stream their content
- *  - gitlinks record the index commit (submodule contents are not covered)
- *  A per-file read/containment failure is an explicit `unreadable:<mode>`
- *  sentinel, not an omitted path. */
-async function boundaryFingerprint(workspace, path, tracked, signal) {
-    const abs = resolve(workspace, path);
-    let stat;
-    try {
-        stat = lstatSync(abs);
-    }
-    catch (error) {
-        return error.code === "ENOENT" ? "missing" : "unreadable";
-    }
-    const mode = stat.mode;
-    if (stat.isSymbolicLink()) {
-        try {
-            // The parent must be contained; the final link target is NOT followed.
-            const parent = path.includes("/")
-                ? path.slice(0, path.lastIndexOf("/")) || "."
-                : ".";
-            containInWorkspace(workspace, parent);
-            return `link:${hashText(readlinkSync(abs))}`;
-        }
-        catch {
-            return `unreadable:${mode}`;
-        }
-    }
-    if (stat.isDirectory()) {
-        if (tracked?.mode === "160000")
-            return `gitlink:${tracked.object}`;
-        return `dir:${mode}`;
-    }
-    if (!stat.isFile())
-        return `other:${mode}`;
-    try {
-        containInWorkspace(workspace, path);
-        const digest = await hashFileStream(abs, signal);
-        return `${mode}:${digest}`;
-    }
-    catch (error) {
-        if (error instanceof GitCaptureFailure)
-            throw error;
-        return `unreadable:${mode}`;
-    }
-}
-/** Hash the complete boundary with bounded concurrency. */
-async function fingerprintBoundary(workspace, entries, signal) {
-    const paths = [...entries.keys()].sort();
-    const fingerprints = {};
-    let next = 0;
-    const worker = async () => {
-        for (;;) {
-            if (signal?.aborted) {
-                throw new GitCaptureFailure("aborted", "boundary hashing aborted");
-            }
-            const index = next++;
-            if (index >= paths.length)
-                return;
-            const path = paths[index];
-            fingerprints[path] = await boundaryFingerprint(workspace, path, entries.get(path), signal);
-        }
-    };
-    const workers = Math.min(BOUNDARY_HASH_CONCURRENCY, Math.max(1, paths.length));
-    await Promise.all(Array.from({ length: workers }, () => worker()));
-    return fingerprints;
-}
 export class GitEvidenceProvider {
     name = "git";
     kind = "git";
@@ -939,56 +724,48 @@ export class GitEvidenceProvider {
             }, budget)
             : undefined;
         try {
-            const result = await captureGitFileStateAsync(controller.signal, context?.timeoutMs, workspace);
+            const result = await captureBoundary({
+                cwd: workspace,
+                signal: controller.signal,
+                ...(context?.timeoutMs !== undefined ? { timeoutMs: context.timeoutMs } : {}),
+                exclude: isRuntimeState,
+                ...(context?.materializer ? { materializer: context.materializer } : {}),
+                ...(context?.maxPaths !== undefined ? { maxPaths: context.maxPaths } : {}),
+            });
             if (timedOut) {
                 return syntheticObservation(this.name, this.kind, phase, startedAt, "timeout", `boundary capture exceeded ${budget}ms`);
             }
             if (!result.ok) {
                 return syntheticObservation(this.name, this.kind, phase, startedAt, result.status, result.detail);
             }
-            const tracked = result.state.tracked.filter((entry) => !isRuntimeState(entry.path));
-            const untracked = result.state.untracked.filter((file) => !isRuntimeState(file));
-            const dirty = result.state.dirty.filter((file) => !isRuntimeState(file));
-            const boundary = new Map();
-            for (const entry of tracked)
-                boundary.set(entry.path, entry);
-            for (const file of untracked) {
-                if (!boundary.has(file)) {
-                    boundary.set(file, { path: file, mode: "", object: "" });
-                }
-            }
-            try {
-                const fingerprints = await fingerprintBoundary(workspace, boundary, controller.signal);
-                if (timedOut) {
-                    return syntheticObservation(this.name, this.kind, phase, startedAt, "timeout", `boundary capture exceeded ${budget}ms`);
-                }
-                return {
-                    schemaVersion: GIT_OBSERVATION_SCHEMA_VERSION,
-                    providerId: "git",
-                    kind: "git",
-                    phase,
-                    startedAt,
-                    finishedAt: Date.now(),
-                    status: "observed",
-                    // `files` is the dirty display list; the complete boundary lives in
-                    // data.fingerprints and the round delta is derived from it.
-                    files: dirty,
-                    data: {
-                        dirty,
-                        fingerprints,
-                        head: result.state.head,
-                        coverage: "tracked_and_non_ignored_untracked",
-                    },
-                };
-            }
-            catch (error) {
-                const status = timedOut
-                    ? "timeout"
-                    : error instanceof GitCaptureFailure
-                        ? error.status
-                        : "error";
-                return syntheticObservation(this.name, this.kind, phase, startedAt, status, String(error instanceof Error ? error.message : error));
-            }
+            const boundary = result.boundary;
+            context?.boundarySink?.(boundary);
+            return {
+                schemaVersion: expectedObservationSchemaVersion("git"),
+                providerId: "git",
+                kind: "git",
+                phase,
+                startedAt,
+                finishedAt: Date.now(),
+                status: "observed",
+                // `files` is the dirty display list; the complete boundary lives in
+                // data.fingerprints and the round delta is derived from it.
+                files: [...boundary.dirty],
+                data: {
+                    dirty: [...boundary.dirty],
+                    fingerprints: boundary.fingerprints,
+                    ...(boundary.head ? { head: boundary.head } : {}),
+                    coverage: "tracked_and_non_ignored_untracked",
+                },
+            };
+        }
+        catch (error) {
+            const status = timedOut
+                ? "timeout"
+                : error instanceof GitCaptureFailure
+                    ? error.status
+                    : "error";
+            return syntheticObservation(this.name, this.kind, phase, startedAt, status, String(error instanceof Error ? error.message : error));
         }
         finally {
             if (timer)
@@ -998,6 +775,78 @@ export class GitEvidenceProvider {
     }
 }
 registerEvidenceProvider("git", () => new GitEvidenceProvider());
+/** The Git fact descriptor is derived from the PERSISTED observation, not from
+ *  a code constant: the scope is the boundary coverage the observation
+ *  declared and the version is its schema version, so a historical
+ *  observation with different evidence semantics naturally stops matching the
+ *  rule instead of being retroactively rewritten by future code. */
+function gitProgressCoverage(observation) {
+    if (observation?.kind === "git") {
+        const scope = typeof observation.data.coverage === "string" &&
+            observation.data.coverage.length > 0
+            ? observation.data.coverage
+            : GIT_WORKSPACE_COVERAGE.scope;
+        const version = Number.isInteger(observation.schemaVersion) &&
+            observation.schemaVersion >= 1
+            ? observation.schemaVersion
+            : GIT_WORKSPACE_COVERAGE.version;
+        return {
+            domain: GIT_WORKSPACE_COVERAGE.domain,
+            object: GIT_WORKSPACE_COVERAGE.object,
+            scope,
+            version,
+        };
+    }
+    return { ...GIT_WORKSPACE_COVERAGE };
+}
+function deltaProgressFact(observation, beforeObservation, afterObservation, changedFiles, ambiguous) {
+    if (observation.kind === "git") {
+        const coverage = gitProgressCoverage(afterObservation ?? beforeObservation);
+        const observable = !ambiguous &&
+            beforeObservation?.kind === "git" &&
+            afterObservation?.kind === "git" &&
+            beforeObservation.status === "observed" &&
+            afterObservation.status === "observed" &&
+            changedFiles !== null;
+        if (!observable) {
+            return {
+                kind: "git",
+                coverage,
+                state: "unknown",
+                complete: false,
+                detail: "the Git boundary pair is not comparable",
+            };
+        }
+        const signal = gitMotionSignal({
+            changedFiles,
+            headBefore: observedGitHead(beforeObservation),
+            headAfter: observedGitHead(afterObservation),
+        });
+        if (signal === null) {
+            return {
+                kind: "git",
+                coverage,
+                state: "unknown",
+                complete: true,
+                detail: "the Git change set is known but HEAD movement is not comparable",
+            };
+        }
+        return {
+            kind: "git",
+            coverage,
+            state: signal ? "changed" : "unchanged",
+            complete: true,
+        };
+    }
+    // Custom observations are reports. They carry no progress fact, so they can
+    // never influence stall or prompt freshness.
+    return null;
+}
+/** Stable display key for a coverage descriptor — derived only, never
+ *  persisted, never used as an identity substitute for exact comparison. */
+export function coverageKey(coverage) {
+    return `${coverage.domain}/${coverage.object}/${coverage.scope}@${coverage.version}`;
+}
 const DELTA_KIND_ORDER = {
     git: 0,
     command: 1,
@@ -1076,6 +925,7 @@ export function deriveObservationDeltas(before, after) {
             before: beforeObservation,
             after: afterObservation,
             changedFiles,
+            progress: deltaProgressFact(observation, beforeObservation, afterObservation, changedFiles, ambiguous),
         };
     });
     return deltas.sort((left, right) => DELTA_KIND_ORDER[left.kind] - DELTA_KIND_ORDER[right.kind] ||