intentdna 1.9.0 → 1.9.3

package/dist/runtime/verifier.js

@@ -1,4 +1,5 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { EvaluatorResultError, parseEvaluatorResult } from "./evaluator.js";
@@ -7,6 +8,191 @@ export const MAX_VERIFIER_EVIDENCE_BYTES = 4096;
 export const VERIFIER_DIAGNOSTIC_PREFIX = "INTENTDNA_DIAGNOSTIC:";
 export const MAX_VERIFIER_DIAGNOSTIC_BYTES = 2048;
 const VERIFIER_DIAGNOSTIC_CODE = /^INTENTDNA_DIAGNOSTIC:[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+function assertVerifierRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${label} must be an object`);
+    }
+}
+function assertVerifierExactKeys(value, required, optional = [], label) {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(value);
+    if (required.some((key) => !Object.hasOwn(value, key)) || keys.some((key) => !allowed.has(key))) {
+        throw new TypeError(`${label} has invalid fields`);
+    }
+}
+function assertVerifierTimestamp(value, label) {
+    if (typeof value !== "string"
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)) {
+        throw new TypeError(`${label} must be a canonical UTC timestamp`);
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
+        throw new TypeError(`${label} must be a valid timestamp`);
+    }
+    return parsed;
+}
+function assertVerifierDigest(value, label) {
+    if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value)) {
+        throw new TypeError(`${label} must be a lowercase sha256 digest`);
+    }
+}
+function assertVerifierSignal(value, label) {
+    if (typeof value !== "string" || !/^SIG[A-Z0-9]+$/u.test(value)) {
+        throw new TypeError(`${label} must be a signal name`);
+    }
+}
+function assertVerifierCommandProcessOutcome(value) {
+    assertVerifierRecord(value, "verifier execution outcome");
+    assertVerifierExactKeys(value, ["kind", "exitCode", "signal", "timedOut", "launchError"], [], "verifier execution outcome");
+    if (value.kind === "exited") {
+        if (!Number.isSafeInteger(value.exitCode)
+            || value.exitCode < 0
+            || value.signal !== null
+            || value.timedOut !== false
+            || value.launchError !== null) {
+            throw new TypeError("verifier exited outcome has an invalid tuple");
+        }
+        return;
+    }
+    if (value.kind === "signaled") {
+        if (value.exitCode !== null || value.timedOut !== false || value.launchError !== null) {
+            throw new TypeError("verifier signaled outcome has an invalid tuple");
+        }
+        assertVerifierSignal(value.signal, "verifier signaled outcome signal");
+        return;
+    }
+    if (value.kind === "timed_out") {
+        if ((value.exitCode !== null
+            && (!Number.isSafeInteger(value.exitCode) || value.exitCode <= 0))
+            || value.timedOut !== true
+            || value.launchError !== null) {
+            throw new TypeError("verifier timed_out outcome has an invalid tuple");
+        }
+        if (value.signal !== null)
+            assertVerifierSignal(value.signal, "verifier timed_out outcome signal");
+        return;
+    }
+    if (value.kind === "launch_error") {
+        if (value.exitCode !== null || value.signal !== null || value.timedOut !== false) {
+            throw new TypeError("verifier launch_error outcome has an invalid tuple");
+        }
+        assertVerifierRecord(value.launchError, "verifier launch error");
+        assertVerifierExactKeys(value.launchError, ["code", "messageDigest"], [], "verifier launch error");
+        if (typeof value.launchError.code !== "string"
+            || !/^[A-Z][A-Z0-9_]*$/u.test(value.launchError.code)) {
+            throw new TypeError("verifier launch error code is invalid");
+        }
+        assertVerifierDigest(value.launchError.messageDigest, "verifier launch error message digest");
+        return;
+    }
+    throw new TypeError("verifier execution outcome kind is invalid");
+}
+export function assertVerifierCommandExecutionResult(value) {
+    assertVerifierRecord(value, "verifier command execution result");
+    assertVerifierExactKeys(value, [
+        "outcome",
+        "processTreeDrained",
+        "startedAt",
+        "completedAt",
+        "stdoutDigest",
+        "stdoutBytes",
+        "stderrDigest",
+        "stderrBytes",
+    ], ["evidence"], "verifier command execution result");
+    assertVerifierCommandProcessOutcome(value.outcome);
+    if (typeof value.processTreeDrained !== "boolean") {
+        throw new TypeError("verifier command execution processTreeDrained must be a boolean");
+    }
+    if (value.evidence !== undefined
+        && (typeof value.evidence !== "string"
+            || value.evidence.length === 0
+            || value.evidence.length > MAX_VERIFIER_EVIDENCE_BYTES)) {
+        throw new TypeError("verifier command execution evidence is invalid");
+    }
+    const startedAt = assertVerifierTimestamp(value.startedAt, "verifier command execution startedAt");
+    const completedAt = assertVerifierTimestamp(value.completedAt, "verifier command execution completedAt");
+    if (completedAt < startedAt) {
+        throw new TypeError("verifier command execution completedAt precedes startedAt");
+    }
+    assertVerifierDigest(value.stdoutDigest, "verifier command execution stdoutDigest");
+    assertVerifierDigest(value.stderrDigest, "verifier command execution stderrDigest");
+    if (!Number.isSafeInteger(value.stdoutBytes) || value.stdoutBytes < 0
+        || !Number.isSafeInteger(value.stderrBytes) || value.stderrBytes < 0) {
+        throw new TypeError("verifier command execution byte counts must be non-negative safe integers");
+    }
+}
+export function verifierCommandExecutionPassed(execution) {
+    return execution.processTreeDrained
+        && execution.outcome.kind === "exited"
+        && execution.outcome.exitCode === 0;
+}
+export function verifierCommandExecutionTimedOut(execution) {
+    return execution.outcome.timedOut;
+}
+export function verifierCommandExecutionExitCode(execution) {
+    return execution.outcome.exitCode;
+}
+export function verifierCommandExecutionSignal(execution) {
+    return execution.outcome.signal;
+}
+const VERIFIER_PROCESS_DRAIN_GRACE_MS = 1_000;
+function terminateVerifierProcessGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        const force = signal === "SIGKILL" ? ["/F"] : [];
+        const result = spawnSync("taskkill", ["/PID", String(child.pid), "/T", ...force], { windowsHide: true, stdio: "ignore" });
+        if (!result.error && result.status === 0)
+            return;
+    }
+    try {
+        if (process.platform === "win32")
+            child.kill(signal);
+        else
+            process.kill(-child.pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+function verifierProcessGroupExists(child) {
+    if (child.pid === undefined)
+        return false;
+    if (process.platform === "win32")
+        return child.exitCode === null && child.signalCode === null;
+    try {
+        process.kill(-child.pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        throw error;
+    }
+}
+async function drainVerifierProcessGroup(child) {
+    if (!verifierProcessGroupExists(child))
+        return;
+    terminateVerifierProcessGroup(child, "SIGTERM");
+    const deadline = Date.now() + VERIFIER_PROCESS_DRAIN_GRACE_MS;
+    while (verifierProcessGroupExists(child) && Date.now() < deadline) {
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+    }
+    if (!verifierProcessGroupExists(child))
+        return;
+    terminateVerifierProcessGroup(child, "SIGKILL");
+    const forcedDeadline = Date.now() + VERIFIER_PROCESS_DRAIN_GRACE_MS;
+    while (verifierProcessGroupExists(child) && Date.now() < forcedDeadline) {
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+    }
+    if (verifierProcessGroupExists(child)) {
+        throw new Error("verifier process group did not drain after SIGKILL");
+    }
+}
 const SAFE_COMMAND_VARIABLE_RE = /^[A-Za-z0-9_-]+$/;
 const SAFE_PATH_VARIABLE_RE = /^[-A-Za-z0-9_./]+$/;
 function isSafeRelativePathVariable(value) {
@@ -214,60 +400,167 @@ function appendFailureDiagnostic(message, evidence) {
     const diagnostics = extractVerifierDiagnostics(evidence ?? "").join("\n");
     return diagnostics ? `${message}\n${diagnostics}` : message;
 }
-export async function execVerifierCommand(projectDir, command, timeoutMs = DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS, env) {
+function verifierLaunchError(error, fallbackCode) {
+    const rawCode = error && typeof error === "object" && "code" in error
+        ? String(error.code ?? "")
+        : "";
+    const code = /^[A-Z][A-Z0-9_]*$/u.test(rawCode) ? rawCode : fallbackCode;
+    const message = error instanceof Error
+        ? `${error.name}:${error.message}`
+        : String(error);
+    return {
+        code,
+        messageDigest: `sha256:${createHash("sha256").update(message).digest("hex")}`,
+    };
+}
+function verifierProcessOutcome(code, signal, timedOut) {
+    if (timedOut) {
+        return {
+            kind: "timed_out",
+            exitCode: code === 0 ? null : code,
+            signal,
+            timedOut: true,
+            launchError: null,
+        };
+    }
+    if (code !== null && signal === null) {
+        return {
+            kind: "exited",
+            exitCode: code,
+            signal: null,
+            timedOut: false,
+            launchError: null,
+        };
+    }
+    if (code === null && signal !== null) {
+        return {
+            kind: "signaled",
+            exitCode: null,
+            signal,
+            timedOut: false,
+            launchError: null,
+        };
+    }
+    return {
+        kind: "launch_error",
+        exitCode: null,
+        signal: null,
+        timedOut: false,
+        launchError: verifierLaunchError(new Error("process closed without exactly one of exit code or signal"), "INVALID_PROCESS_OUTCOME"),
+    };
+}
+export async function execVerifierCommand(projectDir, command, timeoutMs = DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS, env = {}, now = () => new Date()) {
     return new Promise((resolvePromise) => {
-        const child = spawn("bash", ["-lc", command], {
-            cwd: projectDir,
-            stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, ...(env ?? {}) },
-        });
+        const startedAt = now().toISOString();
+        let child;
+        try {
+            child = spawn("bash", ["--noprofile", "--norc", "-c", command], {
+                cwd: projectDir,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...env },
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            const emptyDigest = `sha256:${createHash("sha256").digest("hex")}`;
+            resolvePromise({
+                outcome: {
+                    kind: "launch_error",
+                    exitCode: null,
+                    signal: null,
+                    timedOut: false,
+                    launchError: verifierLaunchError(error, "SPAWN_ERROR"),
+                },
+                processTreeDrained: true,
+                startedAt,
+                completedAt: now().toISOString(),
+                stdoutDigest: emptyDigest,
+                stdoutBytes: 0,
+                stderrDigest: emptyDigest,
+                stderrBytes: 0,
+            });
+            return;
+        }
         let stdoutPendingLine = "";
         let stderrPendingLine = "";
         let stdoutBytes = 0;
         let stderrBytes = 0;
+        const stdoutDigest = createHash("sha256");
+        const stderrDigest = createHash("sha256");
         let settled = false;
+        let timedOut = false;
+        let drainPromise = null;
+        let timeoutId = null;
         const diagnostics = [];
-        const settle = (result) => {
+        const startDrain = () => {
+            drainPromise ??= drainVerifierProcessGroup(child).then(() => true, () => false);
+            return drainPromise;
+        };
+        const settle = (outcome, processTreeDrained) => {
             if (settled)
                 return;
             settled = true;
-            clearTimeout(timeoutId);
-            resolvePromise(result);
+            if (timeoutId !== null)
+                clearTimeout(timeoutId);
+            resolvePromise({
+                outcome,
+                processTreeDrained,
+                evidence: summarizeCommandEvidenceFromStats(stdoutBytes, stderrBytes, [
+                    ...diagnostics,
+                    ...extractVerifierDiagnostics(`${stdoutPendingLine}\n${stderrPendingLine}`),
+                ]),
+                startedAt,
+                completedAt: now().toISOString(),
+                stdoutDigest: `sha256:${stdoutDigest.digest("hex")}`,
+                stdoutBytes,
+                stderrDigest: `sha256:${stderrDigest.digest("hex")}`,
+                stderrBytes,
+            });
         };
-        const timeoutId = setTimeout(() => {
-            child.kill("SIGTERM");
-            setTimeout(() => child.kill("SIGKILL"), 1000).unref();
-            diagnostics.push(...extractVerifierDiagnostics(`${stdoutPendingLine}\n${stderrPendingLine}`));
-            settle({ passed: false, timedOut: true, exitCode: 124, evidence: summarizeCommandEvidenceFromStats(stdoutBytes, stderrBytes, diagnostics) });
+        timeoutId = setTimeout(() => {
+            timedOut = true;
+            void startDrain().then((drained) => {
+                if (!drained)
+                    settle(verifierProcessOutcome(null, null, true), false);
+            });
         }, timeoutMs);
-        child.stdout.on("data", (chunk) => {
-            const text = String(chunk);
-            stdoutBytes += Buffer.byteLength(text, "utf8");
+        child.stdout?.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const text = bytes.toString("utf8");
+            stdoutBytes += bytes.length;
+            stdoutDigest.update(bytes);
             stdoutPendingLine = collectVerifierDiagnostics(stdoutPendingLine, text, diagnostics);
         });
-        child.stderr.on("data", (chunk) => {
-            const text = String(chunk);
-            stderrBytes += Buffer.byteLength(text, "utf8");
+        child.stderr?.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const text = bytes.toString("utf8");
+            stderrBytes += bytes.length;
+            stderrDigest.update(bytes);
             stderrPendingLine = collectVerifierDiagnostics(stderrPendingLine, text, diagnostics);
         });
-        child.on("error", () => settle({
-            passed: false,
-            timedOut: false,
-            exitCode: 1,
-            evidence: summarizeCommandEvidenceFromStats(stdoutBytes, stderrBytes, [
-                ...diagnostics,
-                ...extractVerifierDiagnostics(`${stdoutPendingLine}\n${stderrPendingLine}`),
-            ]),
-        }));
-        child.on("close", (code) => settle({
-            passed: code === 0,
-            timedOut: false,
-            exitCode: code ?? 1,
-            evidence: summarizeCommandEvidenceFromStats(stdoutBytes, stderrBytes, [
-                ...diagnostics,
-                ...extractVerifierDiagnostics(`${stdoutPendingLine}\n${stderrPendingLine}`),
-            ]),
-        }));
+        child.on("error", (error) => {
+            void startDrain().then((drained) => {
+                if (timedOut) {
+                    settle(verifierProcessOutcome(null, null, true), drained);
+                    return;
+                }
+                settle({
+                    kind: "launch_error",
+                    exitCode: null,
+                    signal: null,
+                    timedOut: false,
+                    launchError: verifierLaunchError(error, "SPAWN_ERROR"),
+                }, drained);
+            });
+        });
+        child.on("exit", () => {
+            void startDrain();
+        });
+        child.on("close", async (code, signal) => {
+            const drained = await startDrain();
+            settle(verifierProcessOutcome(code, signal, timedOut), drained);
+        });
     });
 }
 async function execVerifierStdout(projectDir, command, args) {
@@ -522,15 +815,18 @@ export async function runCompletionVerifier(completion, ir, context) {
         return { passed: false, target: commandResolution.target, evidence: commandResolution.evidence, exit_code: commandResolution.exit_code, message: commandResolution.message };
     const command = commandResolution.command;
     const commandResult = await execVerifierCommand(context.projectDir, command, context.commandTimeoutMs, verifierCommandEnv(context.variables));
+    const passed = verifierCommandExecutionPassed(commandResult);
+    const timedOut = verifierCommandExecutionTimedOut(commandResult);
+    const exitCode = verifierCommandExecutionExitCode(commandResult);
     return {
-        passed: commandResult.passed,
+        passed,
         target: command,
         evidence: commandResult.evidence,
-        exit_code: commandResult.exitCode,
-        timedOut: commandResult.timedOut,
-        message: commandResult.passed
+        exit_code: exitCode ?? (timedOut ? 124 : 1),
+        timedOut,
+        message: passed
             ? undefined
-            : commandResult.timedOut
+            : timedOut
                 ? `Verifier command timed out after ${context.commandTimeoutMs ?? DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS}ms`
                 : appendFailureDiagnostic("Verifier command failed", commandResult.evidence),
     };
@@ -548,15 +844,18 @@ export async function runCheckpointVerifier(checkpoint, ir, context) {
             return { passed: false, target: commandResolution.target, evidence: commandResolution.evidence, exit_code: commandResolution.exit_code, message: commandResolution.message };
         const command = commandResolution.command;
         const commandResult = await execVerifierCommand(context.projectDir, command, context.commandTimeoutMs, verifierCommandEnv(context.variables));
+        const passed = verifierCommandExecutionPassed(commandResult);
+        const timedOut = verifierCommandExecutionTimedOut(commandResult);
+        const exitCode = verifierCommandExecutionExitCode(commandResult);
         return {
-            passed: commandResult.passed,
+            passed,
             target: command,
             evidence: commandResult.evidence,
-            exit_code: commandResult.exitCode,
-            timedOut: commandResult.timedOut,
-            message: commandResult.passed
+            exit_code: exitCode ?? (timedOut ? 124 : 1),
+            timedOut,
+            message: passed
                 ? checkpoint.message
-                : commandResult.timedOut
+                : timedOut
                     ? `Verifier command timed out after ${context.commandTimeoutMs ?? DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS}ms`
                     : appendFailureDiagnostic("Verifier command failed", commandResult.evidence),
         };
@@ -598,14 +897,17 @@ export async function runCheckpointVerifier(checkpoint, ir, context) {
             return { passed: false, target: checkpoint.assert, evidence: "policy_denied", exit_code: 126, message: verifierAssertPolicyMessage(checkpoint.assert) };
         }
         const commandResult = await execVerifierCommand(context.projectDir, assertCommands[checkpoint.assert], context.commandTimeoutMs);
+        const passed = verifierCommandExecutionPassed(commandResult);
+        const timedOut = verifierCommandExecutionTimedOut(commandResult);
+        const exitCode = verifierCommandExecutionExitCode(commandResult);
         return {
-            passed: commandResult.passed,
+            passed,
             target: checkpoint.assert,
             evidence: commandResult.evidence,
-            exit_code: commandResult.exitCode,
-            message: commandResult.passed
+            exit_code: exitCode ?? (timedOut ? 124 : 1),
+            message: passed
                 ? checkpoint.message
-                : commandResult.timedOut
+                : timedOut
                     ? `Verifier command timed out after ${context.commandTimeoutMs ?? DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS}ms`
                     : checkpoint.message
                         ? appendFailureDiagnostic(checkpoint.message, commandResult.evidence)

package/dist/runtime/windows-job-keeper.d.ts

@@ -0,0 +1,47 @@
+import type { CanonicalResultDigest } from "./run-contracts.js";
+export declare const WINDOWS_JOB_KEEPER_PROTOCOL_VERSION: "IDNA_WINDOWS_JOB_KEEPER_V1";
+export declare const WINDOWS_JOB_KEEPER_MANIFEST_SCHEMA: "intentdna.windows_job_keeper_manifest.v1";
+export type WindowsJobKeeperArchitecture = "x86_64" | "aarch64";
+interface WindowsJobKeeperManifestFile {
+    readonly path: string;
+    readonly sha256: CanonicalResultDigest;
+}
+interface WindowsJobKeeperManifestBinary extends WindowsJobKeeperManifestFile {
+    readonly pe_machine: "0x8664" | "0xaa64";
+}
+export interface WindowsJobKeeperManifest {
+    readonly schema_version: typeof WINDOWS_JOB_KEEPER_MANIFEST_SCHEMA;
+    readonly protocol_version: typeof WINDOWS_JOB_KEEPER_PROTOCOL_VERSION;
+    readonly source: WindowsJobKeeperManifestFile;
+    readonly toolchain: {
+        readonly name: "zig";
+        readonly version: "0.16.0";
+        readonly build_script: WindowsJobKeeperManifestFile & {
+            readonly path: "../../scripts/build-windows-job-keeper.mjs";
+        };
+        readonly source_date_epoch: 0;
+        readonly targets: Readonly<Record<WindowsJobKeeperArchitecture, "x86_64-windows-gnu" | "aarch64-windows-gnu">>;
+    };
+    readonly binaries: Readonly<Record<WindowsJobKeeperArchitecture, WindowsJobKeeperManifestBinary>>;
+}
+export interface WindowsJobKeeperArtifact {
+    readonly architecture: WindowsJobKeeperArchitecture;
+    readonly path: string;
+    readonly digest: CanonicalResultDigest;
+    readonly source_digest: CanonicalResultDigest;
+    readonly protocol_version: typeof WINDOWS_JOB_KEEPER_PROTOCOL_VERSION;
+    readonly manifest_path: string | null;
+}
+export interface ResolveWindowsJobKeeperOptions {
+    readonly platform: NodeJS.Platform;
+    readonly architecture?: NodeJS.Architecture;
+    readonly helper_path?: string;
+    readonly expected_digest?: CanonicalResultDigest;
+}
+export declare class WindowsJobKeeperArtifactError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function parseWindowsJobKeeperManifest(value: unknown): WindowsJobKeeperManifest;
+export declare function readPeMachine(path: string): number;
+export declare function resolveWindowsJobKeeperArtifact(options: ResolveWindowsJobKeeperOptions): WindowsJobKeeperArtifact | null;
+export {};