engineering-behavior-observatory 0.2.1

package/dist/src/verifiers.js

@@ -0,0 +1,819 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, realpath, rm, utimes } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { performance } from "node:perf_hooks";
+import { pipeline } from "node:stream/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { assertNoDuplicateJsonKeys, canonicalizeMetadata, digestBytes, readVerifiedArtifact, validateArtifact, writeMetadataAtomically, } from "./artifacts.js";
+import { isSafeArtifactRelativePath } from "./contracts.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+const RESERVED_MANIFEST_PATHS = new Set(["manifest.json"]);
+const execFileAsync = promisify(execFile);
+const COMPLETION_MESSAGE = "ebo-verifier-complete/v1\n";
+const VERIFIER_COMPLETION_HOOK = `
+const fs = require("node:fs");
+const path = require("node:path");
+const Module = require("node:module");
+const stageRoot = __dirname;
+const nodeModulePaths = Module._nodeModulePaths;
+Module._nodeModulePaths = (from) => nodeModulePaths(from)
+  .filter((candidate) => candidate === stageRoot || candidate.startsWith(stageRoot + path.sep));
+const resolveFilename = Module._resolveFilename;
+Module._resolveFilename = function (request, parent, isMain, options) {
+  const resolved = resolveFilename.call(this, request, parent, isMain, options);
+  if (typeof resolved === "string"
+      && (resolved.startsWith("node:") || Module.builtinModules.includes(resolved)
+        || resolved === stageRoot || resolved.startsWith(stageRoot + path.sep))) return resolved;
+  throw new Error("Verifier dependency resolves outside its private staging root.");
+};
+let abnormal = false;
+const report = (error) => {
+  abnormal = true;
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exitCode = 1;
+};
+process.on("uncaughtException", report);
+process.on("unhandledRejection", report);
+process.on("exit", () => {
+  if (!abnormal) {
+    try { fs.writeSync(3, ${JSON.stringify(COMPLETION_MESSAGE)}); } catch {}
+  }
+});
+`;
+const VERIFIER_DEPENDENCY_LOADER = `
+const stageRoot = new URL(".", import.meta.url).href;
+export async function resolve(specifier, context, nextResolve) {
+  const result = await nextResolve(specifier, context);
+  if (result.url.startsWith("node:") || result.url.startsWith(stageRoot)) {
+    return result;
+  }
+  throw new Error("Verifier dependency resolves outside its private staging root.");
+}
+`;
+export async function digestWorkspace(workspacePath, signal) {
+    return digestWorkspaceEntries(workspacePath, true, signal);
+}
+export async function digestWorkspaceTree(workspacePath, signal) {
+    return digestWorkspaceEntries(workspacePath, false, signal);
+}
+async function digestWorkspaceEntries(workspacePath, includeTimestamps, signal) {
+    assertNotAborted(signal);
+    const root = await realpath(workspacePath);
+    const hash = createHash("sha256");
+    hash.update(includeTimestamps ? "ebo.workspace/v1\0" : "ebo.workspace-tree/v1\0");
+    const metadata = await lstat(root, { bigint: true });
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error("Workspace root is not a directory.");
+    hash.update(`root\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}`);
+    await hashWorkspaceDirectory(root, "", hash, includeTimestamps, signal);
+    return `sha256:${hash.digest("hex")}`;
+}
+async function hashWorkspaceDirectory(directory, relativeDirectory, hash, includeTimestamps, signal) {
+    assertNotAborted(signal);
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        const relativePath = posix.join(relativeDirectory, entry.name);
+        const metadata = await lstat(path, { bigint: true });
+        if (metadata.isSymbolicLink())
+            throw new Error(`Workspace contains a symbolic link at "${relativePath}".`);
+        if (metadata.isDirectory()) {
+            hash.update(`directory\0${relativePath}\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}`);
+            await hashWorkspaceDirectory(path, relativePath, hash, includeTimestamps, signal);
+        }
+        else if (metadata.isFile()) {
+            if (metadata.nlink > 1n)
+                throw new Error(`Workspace contains a hard-linked file at "${relativePath}".`);
+            const bytes = await readFile(path, { signal });
+            hash.update(`file\0${relativePath}\0${metadata.mode & 4095n}\0${includeTimestamps ? `${workspaceTimestamp(metadata)}\0` : ""}${bytes.length}\0`);
+            hash.update(bytes);
+        }
+        else {
+            throw new Error(`Workspace contains an unsupported entry at "${relativePath}".`);
+        }
+    }
+}
+async function captureWorkspaceContent(workspacePath, signal) {
+    assertNotAborted(signal);
+    const root = await realpath(workspacePath);
+    const metadata = await lstat(root, { bigint: true });
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error("Workspace root is not a directory.");
+    const entries = new Map([["", { kind: "directory", mode: metadata.mode & 4095n }]]);
+    await captureWorkspaceDirectory(root, "", entries, signal);
+    return entries;
+}
+async function captureWorkspaceDirectory(directory, relativeDirectory, entries, signal) {
+    assertNotAborted(signal);
+    const children = await readdir(directory, { withFileTypes: true });
+    children.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const child of children) {
+        const path = join(directory, child.name);
+        const relativePath = posix.join(relativeDirectory, child.name);
+        const metadata = await lstat(path, { bigint: true });
+        if (metadata.isSymbolicLink())
+            throw new Error(`Workspace contains a symbolic link at "${relativePath}".`);
+        if (metadata.isDirectory()) {
+            entries.set(relativePath, { kind: "directory", mode: metadata.mode & 4095n });
+            await captureWorkspaceDirectory(path, relativePath, entries, signal);
+        }
+        else if (metadata.isFile()) {
+            if (metadata.nlink > 1n)
+                throw new Error(`Workspace contains a hard-linked file at "${relativePath}".`);
+            entries.set(relativePath, { kind: "file", mode: metadata.mode & 4095n, bytes: await readFile(path, { signal }) });
+        }
+        else {
+            throw new Error(`Workspace contains an unsupported entry at "${relativePath}".`);
+        }
+    }
+}
+async function assertWorkspaceSnapshotContent(snapshotPath, expected, signal) {
+    const actual = await captureWorkspaceContent(snapshotPath, signal);
+    if (actual.size !== expected.size)
+        throw new Error("Workspace changed while its private evaluation snapshot was being created.");
+    for (const [relativePath, expectedEntry] of expected) {
+        const actualEntry = actual.get(relativePath);
+        if (actualEntry === undefined || actualEntry.kind !== expectedEntry.kind || actualEntry.mode !== expectedEntry.mode
+            || (expectedEntry.kind === "file" && !actualEntry.bytes.equals(expectedEntry.bytes))) {
+            throw new Error("Workspace changed while its private evaluation snapshot was being created.");
+        }
+    }
+}
+async function copyWorkspaceSnapshot(source, destination, signal) {
+    assertNotAborted(signal);
+    if (process.platform !== "win32") {
+        await execFileAsync("/bin/cp", ["-a", source, destination], { signal });
+        return;
+    }
+    await copyWorkspaceSnapshotOnWindows(source, destination, signal);
+    await restoreWorkspaceTimestamps(source, destination, signal);
+}
+async function copyWorkspaceSnapshotOnWindows(source, destination, signal) {
+    assertNotAborted(signal);
+    const sourceMetadata = await lstat(source, { bigint: true });
+    await mkdir(destination);
+    await chmod(destination, Number(sourceMetadata.mode & 4095n));
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+        assertNotAborted(signal);
+        const sourcePath = join(source, entry.name);
+        const destinationPath = join(destination, entry.name);
+        const metadata = await lstat(sourcePath, { bigint: true });
+        if (metadata.isSymbolicLink())
+            throw new Error(`Workspace contains a symbolic link at "${entry.name}".`);
+        if (metadata.isDirectory()) {
+            await copyWorkspaceSnapshotOnWindows(sourcePath, destinationPath, signal);
+        }
+        else if (metadata.isFile()) {
+            await pipeline(createReadStream(sourcePath), createWriteStream(destinationPath, { flags: "wx", mode: Number(metadata.mode & 4095n) }), ...(signal === undefined ? [] : [{ signal }]));
+            await chmod(destinationPath, Number(metadata.mode & 4095n));
+        }
+        else {
+            throw new Error(`Workspace contains an unsupported entry at "${entry.name}".`);
+        }
+    }
+}
+async function restoreWorkspaceTimestamps(source, destination, signal) {
+    assertNotAborted(signal);
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(source, entry.name);
+        const destinationPath = join(destination, entry.name);
+        const metadata = await lstat(sourcePath, { bigint: true });
+        if (metadata.isSymbolicLink())
+            throw new Error(`Workspace contains a symbolic link at "${entry.name}".`);
+        if (metadata.isDirectory()) {
+            await restoreWorkspaceTimestamps(sourcePath, destinationPath, signal);
+        }
+        else if (!metadata.isFile()) {
+            throw new Error(`Workspace contains an unsupported entry at "${entry.name}".`);
+        }
+        await utimes(destinationPath, timestampSeconds(metadata.atimeMs), timestampSeconds(metadata.mtimeMs));
+    }
+    const metadata = await lstat(source, { bigint: true });
+    await utimes(destination, timestampSeconds(metadata.atimeMs), timestampSeconds(metadata.mtimeMs));
+}
+function timestampSeconds(milliseconds) {
+    return Number(milliseconds) / 1_000 + 0.000001;
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw new Error("Verifier execution was aborted.");
+}
+function workspaceTimestamp(metadata) {
+    return process.platform === "win32" ? metadata.mtimeMs : metadata.mtimeNs;
+}
+/**
+ * Execute a digest-pinned verifier in a private staging directory.
+ *
+ * The verifier receives the staged implementation path followed by the
+ * evaluated workspace path. Its stdout is the assertion JSON protocol; stderr
+ * is retained as bounded diagnostic evidence.
+ */
+export async function executeVerifier(options) {
+    const startedAt = performance.now();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    validateOptions(options, timeoutMs, maxOutputBytes);
+    const workspacePath = await realpath(options.workspacePath);
+    const verifierRoot = await realpath(options.verifierRoot);
+    const artifactCandidate = await resolveRootPath(options.artifactRoot);
+    assertDisjointRoots(workspacePath, verifierRoot, "Verifier and workspace roots");
+    assertDisjointRoots(workspacePath, artifactCandidate, "Artifact and workspace roots");
+    assertDisjointRoots(verifierRoot, artifactCandidate, "Verifier and artifact roots");
+    if (options.workspaceFingerprint !== await digestWorkspace(workspacePath, options.signal)) {
+        throw new Error("Workspace fingerprint does not match the evaluated workspace.");
+    }
+    const artifactRoot = await prepareRoot(artifactCandidate);
+    const diagnosticDirectory = options.diagnosticDirectory ?? "diagnostics";
+    if (!isSafeArtifactRelativePath(diagnosticDirectory)) {
+        throw new Error(`Diagnostic directory "${diagnosticDirectory}" is unsafe.`);
+    }
+    if (hasPortablePathCollision(diagnosticDirectory.toLowerCase(), RESERVED_MANIFEST_PATHS)) {
+        throw new Error("Diagnostic directory collides with the reserved manifest path.");
+    }
+    const executionDiagnosticDirectory = posix.join(diagnosticDirectory, randomUUID());
+    const diagnosticSetup = await openDiagnosticFiles(artifactRoot, executionDiagnosticDirectory);
+    const diagnosticFiles = diagnosticSetup.files;
+    try {
+        let stdout = emptyOutput();
+        let stderr = emptyOutput();
+        let exitCode;
+        let status = "error";
+        let assertions = [];
+        let internalError = diagnosticSetup.error;
+        let stagingRoot;
+        let evaluatedWorkspaceFingerprint;
+        const verifierFormat = options.moduleFormat ?? inferredModuleFormat(options.verifier.locator);
+        let spawnAttempted = false;
+        try {
+            if (internalError === undefined) {
+                const verifierBytes = await readVerifiedArtifact(verifierRoot, options.verifier.locator, options.verifier.digest);
+                const workspaceContent = await captureWorkspaceContent(workspacePath, options.signal);
+                stagingRoot = await createStagingRoot(workspacePath);
+                const evaluatedWorkspacePath = join(stagingRoot, "workspace");
+                await copyWorkspaceSnapshot(workspacePath, evaluatedWorkspacePath, options.signal);
+                await assertWorkspaceSnapshotContent(evaluatedWorkspacePath, workspaceContent, options.signal);
+                if (await digestWorkspace(workspacePath, options.signal) !== options.workspaceFingerprint) {
+                    throw new Error("Workspace changed while its private evaluation snapshot was being created.");
+                }
+                evaluatedWorkspaceFingerprint = await digestWorkspace(evaluatedWorkspacePath, options.signal);
+                if (evaluatedWorkspaceFingerprint !== options.workspaceFingerprint) {
+                    throw new Error("Workspace snapshot metadata does not match the evaluated workspace.");
+                }
+                const trustedRoot = join(stagingRoot, "trusted");
+                await mkdir(trustedRoot, { recursive: true });
+                await mkdir(join(trustedRoot, "bin"));
+                const stagedVerifier = join(trustedRoot, stagedVerifierName(verifierFormat));
+                await writePrivateFile(stagedVerifier, verifierBytes);
+                const completionHookPath = join(trustedRoot, "completion-hook.cjs");
+                await writePrivateFile(completionHookPath, Buffer.from(VERIFIER_COMPLETION_HOOK));
+                const dependencyLoaderPath = join(trustedRoot, "dependency-loader.mjs");
+                await writePrivateFile(dependencyLoaderPath, Buffer.from(VERIFIER_DEPENDENCY_LOADER));
+                const processResult = await runProcess(options.command ?? process.execPath, ["--no-warnings", "--require", completionHookPath, "--loader", dependencyLoaderPath, stagedVerifier, evaluatedWorkspacePath], evaluatedWorkspacePath, options.env, timeoutMs, maxOutputBytes, diagnosticFiles, trustedRoot, options.signal);
+                stdout = processResult.stdout;
+                stderr = processResult.stderr;
+                exitCode = processResult.exitCode;
+                spawnAttempted = processResult.started;
+                if (processResult.error !== undefined)
+                    internalError = processResult.error;
+                if (processResult.started && !processResult.completed) {
+                    internalError = combineErrors(internalError, "Verifier did not complete normally.");
+                }
+                if (stdout.error !== undefined)
+                    internalError = combineErrors(internalError, `stdout capture failed: ${stdout.error}`);
+                if (stderr.error !== undefined)
+                    internalError = combineErrors(internalError, `stderr capture failed: ${stderr.error}`);
+                if (processResult.started && stdout.error === undefined) {
+                    if (stdout.truncated) {
+                        internalError = combineErrors(internalError, `Verifier stdout exceeded ${maxOutputBytes} bytes.`);
+                    }
+                    else {
+                        try {
+                            assertions = parseAssertions(stdout.bytes);
+                        }
+                        catch (error) {
+                            internalError = combineErrors(internalError, error instanceof Error ? error.message : "Verifier output is invalid.");
+                        }
+                    }
+                }
+                if (internalError === undefined && processResult.signal === undefined && exitCode !== undefined) {
+                    if (assertions.some((assertion) => assertion.status === "failed")) {
+                        if (exitCode === 0) {
+                            internalError = "Verifier exit status contradicts its failed assertions.";
+                        }
+                        else {
+                            status = "failed";
+                        }
+                    }
+                    else if (exitCode === 0 && assertions.every((assertion) => assertion.status === "passed")) {
+                        status = "passed";
+                    }
+                    else {
+                        internalError = "Verifier exit status contradicts its assertions.";
+                    }
+                }
+                if (processResult.timedOut)
+                    internalError = combineErrors(internalError, `Verifier timed out after ${timeoutMs} ms.`);
+                else if (processResult.signal !== undefined)
+                    internalError = combineErrors(internalError, `Verifier terminated by ${processResult.signal}.`);
+            }
+        }
+        catch (error) {
+            internalError = error instanceof Error ? error.message : "Verifier could not be executed.";
+        }
+        finally {
+            if (stagingRoot !== undefined) {
+                await rm(stagingRoot, { force: true, recursive: true }).catch((error) => {
+                    internalError = combineErrors(internalError, error instanceof Error ? error.message : "Verifier staging cleanup failed.");
+                });
+            }
+        }
+        if (internalError !== undefined)
+            status = "error";
+        await finalizeDiagnosticFiles(diagnosticFiles);
+        if (diagnosticFiles.some((file) => file.error !== undefined)) {
+            status = "error";
+            internalError = combineErrors(internalError, "Verifier diagnostics could not be persisted.");
+        }
+        let diagnostics = [];
+        if (!spawnAttempted) {
+            const cleanupError = await removeDiagnosticFiles(artifactRoot, diagnosticFiles);
+            if (cleanupError !== undefined) {
+                status = "error";
+                internalError = combineErrors(internalError, cleanupError);
+            }
+        }
+        else {
+            const references = await Promise.all(diagnosticFiles.map((file, index) => diagnosticReference(artifactRoot, file, index === 0 ? "stdout" : "stderr", index === 0 ? stdout : stderr)));
+            if (references.some((reference) => reference === undefined)) {
+                status = "error";
+                internalError = combineErrors(internalError, "Verifier diagnostics could not be verified.");
+            }
+            diagnostics = references.flatMap((reference) => reference === undefined ? [] : [reference]);
+        }
+        const result = {
+            schemaVersion: "verifier-result/v1",
+            bundleId: options.bundleId,
+            status,
+            verifier: {
+                locator: options.verifier.locator,
+                digest: `sha256:${options.verifier.digest.value}`,
+                format: verifierFormat,
+            },
+            durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+            ...(internalError === undefined ? {} : { error: internalError }),
+            ...(exitCode === undefined ? {} : { exitCode }),
+            workspace: {
+                ...options.workspace,
+                ...(evaluatedWorkspaceFingerprint === undefined ? {} : { fingerprint: evaluatedWorkspaceFingerprint }),
+            },
+            assertions,
+            diagnostics,
+        };
+        assertVerifierResult(result, "verifier-result");
+        return result;
+    }
+    finally {
+        await finalizeDiagnosticFiles(diagnosticFiles);
+    }
+}
+function combineErrors(current, next) {
+    return current === undefined ? next : `${current}; ${next}`;
+}
+export function serializeVerifierResult(result) {
+    assertVerifierResult(result, "verifier-result");
+    return canonicalizeMetadata(result);
+}
+export async function writeVerifierResult(artifactRoot, relativePath, result) {
+    assertVerifierResult(result, relativePath);
+    const resultLocator = relativePath.toLowerCase();
+    if (hasPortablePathCollision(resultLocator, RESERVED_MANIFEST_PATHS)) {
+        throw new Error("Verifier result path collides with the reserved manifest path.");
+    }
+    const diagnosticLocators = new Set((result.diagnostics ?? []).map((diagnostic) => diagnostic.locator.toLowerCase()));
+    if ([...diagnosticLocators].some((locator) => hasPortablePathCollision(locator, RESERVED_MANIFEST_PATHS))) {
+        throw new Error("Verifier diagnostic locator collides with the reserved manifest path.");
+    }
+    if (hasPortablePathCollision(resultLocator, diagnosticLocators)) {
+        throw new Error("Verifier result path collides with a diagnostic locator.");
+    }
+    for (const diagnostic of result.diagnostics ?? []) {
+        const bytes = await readVerifiedArtifact(artifactRoot, diagnostic.locator, {
+            algorithm: "sha256",
+            value: diagnostic.digest.slice("sha256:".length),
+        });
+        if (bytes.length !== diagnostic.sizeBytes) {
+            throw new Error(`Diagnostic "${diagnostic.locator}" size does not match its result reference.`);
+        }
+    }
+    return writeMetadataAtomically(artifactRoot, relativePath, result, undefined, { overwrite: false });
+}
+function validateOptions(options, timeoutMs, maxOutputBytes) {
+    if (!isValidIdentifier(options.bundleId))
+        throw new Error("Bundle ID is invalid.");
+    if (options.command !== undefined && options.command !== process.execPath) {
+        throw new Error("Verifier command must be the pinned Node runtime.");
+    }
+    if (options.moduleFormat !== undefined && !["commonjs", "module"].includes(options.moduleFormat)) {
+        throw new Error("Verifier module format is invalid.");
+    }
+    const locatorFormat = explicitModuleFormat(options.verifier.locator);
+    if (options.moduleFormat !== undefined && locatorFormat !== undefined && options.moduleFormat !== locatorFormat) {
+        throw new Error("Verifier module format conflicts with its locator.");
+    }
+    if (options.args !== undefined && options.args.length > 0) {
+        throw new Error("Verifier launcher arguments cannot replace the staged verifier.");
+    }
+    if (!isValidIdentifier(options.workspace.artifactId) || !/^sha256:[a-f0-9]{64}$/.test(options.workspace.digest)) {
+        throw new Error("Workspace reference is invalid.");
+    }
+    if (!/^sha256:[a-f0-9]{64}$/.test(options.workspaceFingerprint)
+        || !/^sha256:[a-f0-9]{64}$/.test(options.workspace.fingerprint)
+        || options.workspaceFingerprint !== options.workspace.fingerprint) {
+        throw new Error("Workspace fingerprint is invalid.");
+    }
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error(`Verifier timeout must be between 1 and ${MAX_TIMEOUT_MS} ms.`);
+    }
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > MAX_OUTPUT_BYTES) {
+        throw new Error(`Verifier output limit must be between 0 and ${MAX_OUTPUT_BYTES} bytes.`);
+    }
+}
+function isValidIdentifier(value) {
+    return typeof value === "string" && value.trim() !== "" && [...value].length <= 256;
+}
+function inferredModuleFormat(locator) {
+    const lowerLocator = locator.toLowerCase();
+    return lowerLocator.endsWith(".mjs") ? "module" : "commonjs";
+}
+function explicitModuleFormat(locator) {
+    const lowerLocator = locator.toLowerCase();
+    if (lowerLocator.endsWith(".mjs"))
+        return "module";
+    if (lowerLocator.endsWith(".cjs"))
+        return "commonjs";
+    return undefined;
+}
+function stagedVerifierName(format) {
+    return format === "module" ? "verifier.mjs" : "verifier.cjs";
+}
+async function prepareRoot(root) {
+    await mkdir(root, { recursive: true });
+    return realpath(root);
+}
+async function resolveRootPath(root) {
+    const absoluteRoot = resolve(root);
+    try {
+        return await realpath(absoluteRoot);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const parent = dirname(absoluteRoot);
+        if (parent === absoluteRoot)
+            return absoluteRoot;
+        return resolve(await resolveRootPath(parent), basename(absoluteRoot));
+    }
+}
+async function createStagingRoot(workspacePath) {
+    const candidates = [
+        tmpdir(),
+        ...(process.platform === "win32"
+            ? (process.env.SystemRoot === undefined ? [] : [join(process.env.SystemRoot, "Temp")])
+            : ["/tmp", "/var/tmp"]),
+    ];
+    let lastError;
+    for (const candidate of new Set(candidates)) {
+        let resolvedStagingRoot;
+        try {
+            const candidateRoot = await realpath(candidate);
+            if (isContained(workspacePath, candidateRoot)) {
+                lastError = new Error("temporary directory candidate is inside the evaluated workspace");
+                continue;
+            }
+            resolvedStagingRoot = await realpath(await mkdtemp(join(candidateRoot, "ebo-verifier-")));
+        }
+        catch (error) {
+            lastError = error;
+            continue;
+        }
+        if (isContained(workspacePath, resolvedStagingRoot) || isContained(resolvedStagingRoot, workspacePath)) {
+            await rm(resolvedStagingRoot, { force: true, recursive: true });
+            lastError = new Error("temporary directory is inside the evaluated workspace");
+            continue;
+        }
+        return resolvedStagingRoot;
+    }
+    throw new Error(`Could not create verifier staging outside the evaluated workspace: ${lastError instanceof Error ? lastError.message : "no separate temporary directory is available."}`);
+}
+function assertDisjointRoots(left, right, label) {
+    if (isContained(left, right) || isContained(right, left)) {
+        throw new Error(`${label} must be separate.`);
+    }
+}
+function isContained(root, path) {
+    const fromRoot = relative(root, path);
+    return fromRoot === "" || (!isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`));
+}
+async function writePrivateFile(path, bytes) {
+    const handle = await open(path, "wx", 0o700);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function runProcess(command, args, cwd, overrides, timeoutMs, maxOutputBytes, diagnosticFiles, verifierRoot, signal) {
+    const environment = overrides === undefined ? { PATH: "" } : cleanEnvironment(overrides);
+    environment.PATH = join(verifierRoot, "bin");
+    const child = spawn(command, args, {
+        cwd,
+        env: environment,
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const stdout = capture(child.stdout, maxOutputBytes, diagnosticFiles[0]);
+    const stderr = capture(child.stderr, maxOutputBytes, diagnosticFiles[1]);
+    const completionStream = child.stdio[3];
+    const completion = capture(completionStream, COMPLETION_MESSAGE.length);
+    let started = false;
+    let timedOut = false;
+    let termination;
+    const terminate = () => termination ??= killProcessTree(child);
+    return new Promise((resolveProcess) => {
+        let error;
+        let settled = false;
+        let timer;
+        const finish = async (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            abortSignal?.removeEventListener("abort", abort);
+            await terminate();
+            resolveProcess({
+                started,
+                completed: (await completion).bytes.equals(Buffer.from(COMPLETION_MESSAGE)),
+                stdout: await stdout,
+                stderr: await stderr,
+                ...(code === null ? {} : { exitCode: code }),
+                ...(signal === null ? {} : { signal }),
+                timedOut,
+                ...(error === undefined ? {} : { error }),
+            });
+        };
+        child.once("spawn", () => {
+            started = true;
+        });
+        child.once("error", (cause) => {
+            error = cause.message;
+        });
+        child.once("exit", () => {
+            void terminate().catch(() => undefined);
+        });
+        child.once("close", (code, signal) => {
+            void finish(code, signal);
+        });
+        timer = setTimeout(() => {
+            timedOut = true;
+            void terminate().catch(() => undefined);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            completionStream?.destroy?.();
+            void finish(null, null);
+        }, timeoutMs);
+        timer.unref();
+        const abortSignal = signal;
+        const abort = () => {
+            error ??= "Verifier execution was aborted.";
+            void terminate().catch(() => undefined);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            completionStream?.destroy?.();
+            void finish(null, null);
+        };
+        if (abortSignal?.aborted)
+            abort();
+        else
+            abortSignal?.addEventListener("abort", abort, { once: true });
+    });
+}
+async function killProcessTree(child) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        await new Promise((resolveKiller) => killer.once("close", () => resolveKiller()));
+        return;
+    }
+    try {
+        process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+function capture(stream, limit, diagnosticFile) {
+    if (stream === null)
+        return Promise.resolve(emptyOutput());
+    return new Promise((resolveCapture) => {
+        const chunks = [];
+        let size = 0;
+        let truncated = false;
+        let settled = false;
+        stream.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const retained = bytes.subarray(0, Math.max(0, limit - size));
+            if (retained.length > 0) {
+                chunks.push(retained);
+                size += retained.length;
+                if (diagnosticFile !== undefined)
+                    queueDiagnosticWrite(diagnosticFile, retained);
+            }
+            truncated ||= retained.length < bytes.length;
+        });
+        stream.once("error", (error) => {
+            if (!settled) {
+                settled = true;
+                resolveCapture({
+                    bytes: Buffer.concat(chunks),
+                    truncated,
+                    error: error instanceof Error ? error.message : "unknown stream error",
+                });
+            }
+        });
+        stream.once("end", () => {
+            if (!settled) {
+                settled = true;
+                resolveCapture({ bytes: Buffer.concat(chunks), truncated });
+            }
+        });
+        stream.once("close", () => {
+            if (!settled) {
+                settled = true;
+                resolveCapture({ bytes: Buffer.concat(chunks), truncated });
+            }
+        });
+    });
+}
+function emptyOutput() {
+    return { bytes: Buffer.alloc(0), truncated: false };
+}
+function parseAssertions(bytes) {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const parsed = JSON.parse(text);
+    assertNoDuplicateJsonKeys(text);
+    if (!isRecord(parsed) || !hasExactKeys(parsed, ["assertions"]) || !Array.isArray(parsed.assertions)
+        || parsed.assertions.length === 0) {
+        throw new Error("Verifier output must contain a non-empty assertions array.");
+    }
+    const identifiers = new Set();
+    return parsed.assertions.map((value) => {
+        if (!isRecord(value) || !hasExactKeys(value, ["id", "status"]) || typeof value.id !== "string"
+            || value.id.trim() === "" || [...value.id].length > 256
+            || typeof value.status !== "string" || !["passed", "failed", "not-run"].includes(value.status)
+            || identifiers.has(value.id)) {
+            throw new Error("Verifier output contains an invalid or duplicate assertion.");
+        }
+        identifiers.add(value.id);
+        return { id: value.id, status: value.status };
+    });
+}
+function hasExactKeys(value, expected) {
+    const keys = Object.keys(value);
+    return keys.length === expected.length && expected.every((key) => Object.hasOwn(value, key));
+}
+async function openDiagnosticFiles(root, directory) {
+    const files = [];
+    try {
+        for (const stream of ["stdout", "stderr"]) {
+            const locator = posix.join(directory, `${stream}.log`);
+            if (!isSafeArtifactRelativePath(locator))
+                throw new Error(`Diagnostic locator "${locator}" is unsafe.`);
+            const rootPath = await realpath(root);
+            const { path } = await prepareDiagnosticPath(rootPath, locator);
+            files.push({ locator, handle: await open(path, "wx", 0o600), writes: Promise.resolve(), closed: false });
+        }
+        return { files };
+    }
+    catch (error) {
+        await finalizeDiagnosticFiles(files);
+        let setupError = error instanceof Error ? error.message : "Verifier diagnostic setup failed.";
+        const cleanupError = await removeDiagnosticFiles(root, files);
+        if (cleanupError !== undefined)
+            setupError = combineErrors(setupError, cleanupError);
+        return {
+            files: [],
+            error: setupError,
+        };
+    }
+}
+async function removeDiagnosticFiles(root, files) {
+    let error;
+    for (const file of files) {
+        await rm(resolve(root, file.locator), { force: true }).catch((cleanupError) => {
+            error = combineErrors(error, cleanupError instanceof Error ? cleanupError.message : "Verifier diagnostic cleanup failed.");
+        });
+    }
+    return error;
+}
+function queueDiagnosticWrite(file, bytes) {
+    if (bytes.length === 0 || file.closed)
+        return;
+    file.writes = file.writes.then(async () => {
+        await file.handle.write(bytes);
+    }).catch((error) => {
+        file.error = error instanceof Error ? error.message : "Diagnostic write failed.";
+    });
+}
+async function finalizeDiagnosticFiles(files) {
+    await Promise.all(files.map(async (file) => {
+        if (file.closed)
+            return;
+        await file.writes;
+        await file.handle.sync().catch((error) => {
+            file.error ??= error instanceof Error ? error.message : "Diagnostic flush failed.";
+        });
+        await file.handle.close().catch((error) => {
+            file.error ??= error instanceof Error ? error.message : "Diagnostic close failed.";
+        });
+        file.closed = true;
+    }));
+}
+async function diagnosticReference(root, file, stream, output) {
+    const digest = digestBytes(output.bytes);
+    try {
+        const bytes = await readVerifiedArtifact(root, file.locator, digest);
+        return {
+            stream,
+            locator: file.locator,
+            digest: `sha256:${digest.value}`,
+            sizeBytes: bytes.length,
+            truncated: output.truncated,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasPortablePathCollision(path, existingPaths) {
+    return [...existingPaths].some((existing) => existing === path || existing.startsWith(`${path}/`) || path.startsWith(`${existing}/`));
+}
+async function prepareDiagnosticPath(root, locator) {
+    const segments = locator.split("/");
+    let parent = root;
+    for (const segment of segments.slice(0, -1)) {
+        parent = resolve(parent, segment);
+        await mkdir(parent, { recursive: true });
+        const entry = await lstat(parent);
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+            throw new Error(`Diagnostic locator "${locator}" crosses a symbolic link.`);
+        }
+    }
+    const path = resolve(parent, segments.at(-1));
+    try {
+        const entry = await lstat(path);
+        if (!entry.isFile() || entry.isSymbolicLink()) {
+            throw new Error(`Diagnostic locator "${locator}" is not an isolated regular file.`);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return { parent, path };
+}
+function assertVerifierResult(result, artifact) {
+    if (new Set(result.assertions.map((assertion) => assertion.id)).size !== result.assertions.length) {
+        throw new Error("Verifier assertion IDs must be unique.");
+    }
+    if (result.status === "failed" && (result.exitCode === undefined || result.exitCode === 0)
+        && result.assertions.some((assertion) => assertion.status === "failed")) {
+        throw new Error("Verifier exit status contradicts its failed assertions.");
+    }
+    const errors = validateArtifact(artifact, result);
+    if (errors.length > 0) {
+        throw new Error(errors.map((error) => `${error.field}: ${error.message}`).join("; "));
+    }
+}
+function cleanEnvironment(environment) {
+    void environment;
+    return {};
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}