intentdna 1.9.0 → 1.9.3

package/dist/runtime/artifact-store.js

@@ -0,0 +1,1436 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readdir, realpath, rm, } from "node:fs/promises";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep, } from "node:path";
+import { promisify } from "node:util";
+import { canonicalizeJson } from "./canonical-json.js";
+export const DIRECTORY_ARTIFACT_SCHEMA_VERSION = "intentdna.directory_artifact.v1";
+export const GIT_COMMIT_ARTIFACT_SCHEMA_VERSION = "intentdna.git_commit_artifact.v1";
+export class ArtifactStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ArtifactStoreError";
+        this.code = code;
+    }
+}
+const DEFAULT_MAX_FILE_SIZE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_DIRECTORY_SIZE_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_DIRECTORY_ENTRIES = 10_000;
+const DEFAULT_MAX_MANIFEST_SIZE_BYTES = 8 * 1024 * 1024;
+const DIRECTORY_MODE = 0o700;
+const STORED_FILE_MODE = 0o444;
+const MATERIALIZED_DIRECTORY_MODE = 0o555;
+const MATERIALIZED_FILE_MODE = 0o444;
+const MAX_BINDING_ID_BYTES = 4_096;
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const GIT_SHA1_PATTERN = /^[0-9a-f]{40}$/;
+const GIT_SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const execFileAsync = promisify(execFile);
+function isErrno(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === code);
+}
+function assertPositiveSafeInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ArtifactStoreError("invalid_options", `${name} must be a positive safe integer`);
+    }
+}
+function assertNonEmpty(value, label) {
+    if (!value.trim()) {
+        throw new ArtifactStoreError("invalid_request", `${label} must be a non-empty string`);
+    }
+}
+function resolveOptions(options) {
+    if (!options.root_directory.trim()) {
+        throw new ArtifactStoreError("invalid_options", "root_directory must be a non-empty string");
+    }
+    const resolved = {
+        root_directory: resolve(options.root_directory),
+        max_file_size_bytes: options.max_file_size_bytes ?? DEFAULT_MAX_FILE_SIZE_BYTES,
+        max_directory_size_bytes: options.max_directory_size_bytes ?? DEFAULT_MAX_DIRECTORY_SIZE_BYTES,
+        max_directory_entries: options.max_directory_entries ?? DEFAULT_MAX_DIRECTORY_ENTRIES,
+        max_manifest_size_bytes: options.max_manifest_size_bytes ?? DEFAULT_MAX_MANIFEST_SIZE_BYTES,
+    };
+    assertPositiveSafeInteger("max_file_size_bytes", resolved.max_file_size_bytes);
+    assertPositiveSafeInteger("max_directory_size_bytes", resolved.max_directory_size_bytes);
+    assertPositiveSafeInteger("max_directory_entries", resolved.max_directory_entries);
+    assertPositiveSafeInteger("max_manifest_size_bytes", resolved.max_manifest_size_bytes);
+    return resolved;
+}
+function sha256(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function artifactHex(artifactId) {
+    if (typeof artifactId !== "string" || !SHA256_PATTERN.test(artifactId)) {
+        throw new ArtifactStoreError("invalid_request", `invalid artifact_id: ${artifactId}`);
+    }
+    return artifactId.slice("sha256:".length);
+}
+function assertArtifactKind(kind) {
+    if (!["file", "directory", "git_commit"].includes(kind)) {
+        throw new ArtifactStoreError("invalid_request", `invalid artifact kind: ${String(kind)}`);
+    }
+}
+function comparePosixPath(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+function isContained(root, candidate) {
+    const child = relative(root, candidate);
+    return (child === "" ||
+        (child !== ".." &&
+            !child.startsWith(`..${sep}`) &&
+            !isAbsolute(child)));
+}
+function signatureOf(stats) {
+    return {
+        device: stats.dev,
+        inode: stats.ino,
+        mode: stats.mode,
+        size: stats.size,
+        modified_ns: stats.mtimeNs,
+        changed_ns: stats.ctimeNs,
+    };
+}
+function signaturesEqual(left, right) {
+    return (left.device === right.device &&
+        left.inode === right.inode &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.modified_ns === right.modified_ns &&
+        left.changed_ns === right.changed_ns);
+}
+function stableObjectIdentityEqual(left, right) {
+    return (left.device === right.device &&
+        left.inode === right.inode &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.modified_ns === right.modified_ns);
+}
+function assertRegularNode(stats, path) {
+    if (stats.isSymbolicLink()) {
+        throw new ArtifactStoreError("symlink_not_allowed", `symbolic links are not capturable: ${path}`);
+    }
+    if (stats.isFile())
+        return "file";
+    if (stats.isDirectory())
+        return "directory";
+    throw new ArtifactStoreError("special_file_not_allowed", `special filesystem nodes are not capturable: ${path}`);
+}
+function assertManifestPath(path) {
+    if (!path ||
+        path.includes("\\") ||
+        path.includes("\0") ||
+        posix.isAbsolute(path) ||
+        posix.normalize(path) !== path ||
+        path.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new ArtifactStoreError("artifact_corrupt", `unsafe directory artifact path: ${JSON.stringify(path)}`);
+    }
+}
+function canonicalBytes(value) {
+    return Buffer.from(canonicalizeJson(value), "utf8");
+}
+function directoryIdentity(manifest) {
+    return sha256(canonicalBytes(manifest));
+}
+function gitCommitIdentity(stored) {
+    return sha256(canonicalBytes(stored));
+}
+function gitCommitPattern(objectFormat) {
+    return objectFormat === "sha1" ? GIT_SHA1_PATTERN : GIT_SHA256_PATTERN;
+}
+async function gitOutput(workspaceRoot, args, label, errorCode = "git_repository_invalid") {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", workspaceRoot, ...args], {
+            encoding: "utf8",
+            maxBuffer: 1024 * 1024,
+            env: {
+                PATH: process.env.PATH ?? "",
+                HOME: process.env.HOME ?? "",
+                GIT_CONFIG_NOSYSTEM: "1",
+                GIT_TERMINAL_PROMPT: "0",
+            },
+        });
+        return stdout.trim();
+    }
+    catch {
+        throw new ArtifactStoreError(errorCode, `failed to resolve ${label} from the declared workspace repository`);
+    }
+}
+async function gitBranchRef(workspaceRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", workspaceRoot, "symbolic-ref", "--quiet", "HEAD"], {
+            encoding: "utf8",
+            maxBuffer: 1024 * 1024,
+            env: {
+                PATH: process.env.PATH ?? "",
+                HOME: process.env.HOME ?? "",
+                GIT_CONFIG_NOSYSTEM: "1",
+                GIT_TERMINAL_PROMPT: "0",
+            },
+        });
+        return stdout.trim();
+    }
+    catch (error) {
+        if (error instanceof Error
+            && "code" in error
+            && error.code === 1) {
+            return null;
+        }
+        throw new ArtifactStoreError("source_drift", "failed to resolve current Git branch from the declared workspace repository");
+    }
+}
+function exactObjectKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    return actual.length === wanted.length &&
+        actual.every((key, index) => key === wanted[index]);
+}
+function validateManifest(manifest, expectedSize, maxEntries) {
+    if (!Array.isArray(manifest)) {
+        throw new ArtifactStoreError("artifact_corrupt", "directory artifact manifest must be an array");
+    }
+    if (manifest.length > maxEntries) {
+        throw new ArtifactStoreError("artifact_corrupt", "directory artifact manifest exceeds the configured entry limit");
+    }
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 0) {
+        throw new ArtifactStoreError("artifact_corrupt", "directory artifact size_bytes must be a non-negative safe integer");
+    }
+    const directories = new Set();
+    const seen = new Set();
+    const entries = [];
+    let totalSize = 0;
+    let previousPath = null;
+    for (const value of manifest) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new ArtifactStoreError("artifact_corrupt", "directory artifact contains a non-object entry");
+        }
+        const candidate = value;
+        if (typeof candidate.path !== "string") {
+            throw new ArtifactStoreError("artifact_corrupt", "directory artifact entry path must be a string");
+        }
+        assertManifestPath(candidate.path);
+        if (previousPath !== null &&
+            comparePosixPath(previousPath, candidate.path) >= 0) {
+            throw new ArtifactStoreError("artifact_corrupt", "directory artifact entries are not uniquely POSIX-sorted");
+        }
+        previousPath = candidate.path;
+        if (seen.has(candidate.path)) {
+            throw new ArtifactStoreError("artifact_corrupt", `duplicate directory artifact path: ${candidate.path}`);
+        }
+        seen.add(candidate.path);
+        const parent = posix.dirname(candidate.path);
+        if (parent !== "." && !directories.has(parent)) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact entry has missing parent: ${candidate.path}`);
+        }
+        if (candidate.kind === "directory") {
+            if (!exactObjectKeys(candidate, ["kind", "path"])) {
+                throw new ArtifactStoreError("artifact_corrupt", `directory entry has unknown fields: ${candidate.path}`);
+            }
+            directories.add(candidate.path);
+            entries.push({ kind: "directory", path: candidate.path });
+            continue;
+        }
+        if (candidate.kind !== "file") {
+            throw new ArtifactStoreError("artifact_corrupt", `unsupported directory entry kind at ${candidate.path}`);
+        }
+        if (!exactObjectKeys(candidate, [
+            "artifact_id",
+            "kind",
+            "path",
+            "size_bytes",
+        ]) ||
+            typeof candidate.artifact_id !== "string" ||
+            !SHA256_PATTERN.test(candidate.artifact_id) ||
+            !Number.isSafeInteger(candidate.size_bytes) ||
+            candidate.size_bytes < 0) {
+            throw new ArtifactStoreError("artifact_corrupt", `invalid file entry at ${candidate.path}`);
+        }
+        totalSize += candidate.size_bytes;
+        if (!Number.isSafeInteger(totalSize)) {
+            throw new ArtifactStoreError("artifact_corrupt", "directory artifact total size is not a safe integer");
+        }
+        entries.push({
+            kind: "file",
+            path: candidate.path,
+            artifact_id: candidate.artifact_id,
+            size_bytes: candidate.size_bytes,
+        });
+    }
+    if (totalSize !== expectedSize) {
+        throw new ArtifactStoreError("artifact_corrupt", "directory artifact size does not match its manifest");
+    }
+    return entries;
+}
+async function requireLstat(path) {
+    try {
+        return await lstat(path, { bigint: true });
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            throw new ArtifactStoreError("source_not_found", `artifact source does not exist: ${path}`);
+        }
+        throw error;
+    }
+}
+async function assertDirectoryPath(path, label) {
+    const stats = await lstat(path, { bigint: true });
+    if (stats.isSymbolicLink()) {
+        throw new ArtifactStoreError("symlink_not_allowed", `${label} must not be a symbolic link: ${path}`);
+    }
+    if (!stats.isDirectory()) {
+        throw new ArtifactStoreError("invalid_options", `${label} must be a directory: ${path}`);
+    }
+}
+function isUnsupportedDirectorySync(error) {
+    if (!(error instanceof Error) || !("code" in error))
+        return false;
+    const code = error.code;
+    return (code === "EINVAL" ||
+        code === "ENOTSUP" ||
+        code === "EISDIR" ||
+        (code === "EPERM" && process.platform === "win32"));
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY);
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isUnsupportedDirectorySync(error))
+            throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function stableFileRead(path, maxBytes) {
+    const before = await requireLstat(path);
+    if (assertRegularNode(before, path) !== "file") {
+        throw new ArtifactStoreError("source_kind_mismatch", `expected a file artifact source: ${path}`);
+    }
+    if (before.size > BigInt(maxBytes)) {
+        throw new ArtifactStoreError("limit_exceeded", `file artifact exceeds ${maxBytes} bytes: ${path}`);
+    }
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isErrno(error, "ELOOP")) {
+            throw new ArtifactStoreError("symlink_not_allowed", `symbolic links are not capturable: ${path}`);
+        }
+        throw error;
+    }
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile()) {
+            throw new ArtifactStoreError("special_file_not_allowed", `source is no longer a regular file: ${path}`);
+        }
+        if (!signaturesEqual(signatureOf(before), signatureOf(opened))) {
+            throw new ArtifactStoreError("source_drift", `source changed while it was opened: ${path}`);
+        }
+        const bytes = await readBounded(handle, maxBytes, path);
+        const afterHandle = await handle.stat({ bigint: true });
+        const afterPath = await requireLstat(path);
+        if (!signaturesEqual(signatureOf(opened), signatureOf(afterHandle)) ||
+            !signaturesEqual(signatureOf(opened), signatureOf(afterPath)) ||
+            BigInt(bytes.byteLength) !== afterHandle.size) {
+            throw new ArtifactStoreError("source_drift", `source changed while it was read: ${path}`);
+        }
+        return { bytes, signature: signatureOf(afterHandle) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readBounded(handle, maxBytes, path) {
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const remaining = maxBytes - total + 1;
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+        if (bytesRead === 0)
+            return Buffer.concat(chunks, total);
+        total += bytesRead;
+        if (total > maxBytes) {
+            throw new ArtifactStoreError("limit_exceeded", `file exceeds ${maxBytes} bytes: ${path}`);
+        }
+        chunks.push(buffer.subarray(0, bytesRead));
+    }
+}
+async function readForMaterializationVerification(path, maxBytes) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        throw new ArtifactStoreError("materialization_verification_failed", `materialized file cannot be opened safely: ${path}`);
+    }
+    try {
+        return await readBounded(handle, maxBytes, path);
+    }
+    catch {
+        throw new ArtifactStoreError("materialization_verification_failed", `materialized file exceeds its expected size: ${path}`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateCaptureRequest(request) {
+    assertNonEmpty(request.workspace_root, "workspace_root");
+    assertNonEmpty(request.source_path, "source_path");
+    assertNonEmpty(request.run_id, "run_id");
+    assertNonEmpty(request.activation_id, "activation_id");
+    assertNonEmpty(request.attempt_id, "attempt_id");
+    assertNonEmpty(request.output_name, "output_name");
+    assertNonEmpty(request.source_workspace_id, "source_workspace_id");
+    assertArtifactKind(request.kind);
+    if (isAbsolute(request.source_path) ||
+        request.source_path.split("/").includes("..")) {
+        throw new ArtifactStoreError("source_outside_workspace", "source_path must be relative to workspace_root");
+    }
+    if (request.source_path.includes("\0") ||
+        request.source_path.includes("\\")) {
+        throw new ArtifactStoreError("invalid_request", "source_path must be a portable relative path without NUL or backslash");
+    }
+}
+function captureRef(request, object, normalizedSourcePath, capturedAt) {
+    return {
+        capture_id: `capture:${randomUUID()}`,
+        artifact_id: object.artifact_id,
+        artifact_kind: object.kind,
+        run_id: request.run_id,
+        activation_id: request.activation_id,
+        attempt_id: request.attempt_id,
+        output_name: request.output_name,
+        source_workspace_id: request.source_workspace_id,
+        source_path: normalizedSourcePath,
+        captured_at: capturedAt,
+    };
+}
+export class ArtifactStore {
+    options;
+    now;
+    constructor(options) {
+        this.options = resolveOptions(options);
+        this.now = options.now ?? (() => new Date());
+    }
+    /**
+     * The caller must stop the producer and hold exclusive mutation authority for
+     * the workspace namespace until this promise settles.
+     */
+    async capture(request) {
+        validateCaptureRequest(request);
+        if (request.kind === "git_commit") {
+            await this.ensureLayout();
+            const object = await this.captureGitCommit(request.workspace_root, request.source_path);
+            return {
+                object,
+                capture: captureRef(request, object, object.commit_oid, this.now().toISOString()),
+            };
+        }
+        await this.ensureLayout();
+        const source = await this.resolveSource(request.workspace_root, request.source_path);
+        await this.assertSourceResolutionStable(source);
+        const stats = await requireLstat(source.absolute_path);
+        const actualKind = assertRegularNode(stats, source.absolute_path);
+        if (actualKind !== request.kind) {
+            throw new ArtifactStoreError("source_kind_mismatch", `expected ${request.kind}, found ${actualKind}: ${source.absolute_path}`);
+        }
+        const object = request.kind === "file"
+            ? await this.captureFile(source.absolute_path)
+            : await this.captureDirectory(source.absolute_path);
+        await this.assertSourceResolutionStable(source);
+        return {
+            object,
+            capture: captureRef(request, object, source.relative_path, this.now().toISOString()),
+        };
+    }
+    async captureExisting(request) {
+        validateCaptureRequest({
+            kind: request.artifact_kind,
+            workspace_root: ".",
+            source_path: request.source_path,
+            run_id: request.run_id,
+            activation_id: request.activation_id,
+            attempt_id: request.attempt_id,
+            output_name: request.output_name,
+            source_workspace_id: request.source_workspace_id,
+        });
+        const object = await this.require(request);
+        return {
+            object,
+            capture: captureRef({
+                kind: request.artifact_kind,
+                workspace_root: ".",
+                source_path: request.source_path,
+                run_id: request.run_id,
+                activation_id: request.activation_id,
+                attempt_id: request.attempt_id,
+                output_name: request.output_name,
+                source_workspace_id: request.source_workspace_id,
+            }, object, request.source_path, this.now().toISOString()),
+        };
+    }
+    async resolve(locator) {
+        await this.ensureLayout();
+        assertArtifactKind(locator.artifact_kind);
+        artifactHex(locator.artifact_id);
+        if (locator.artifact_kind === "git_commit") {
+            return this.readGitCommitObject(locator.artifact_id, false);
+        }
+        if (locator.artifact_kind === "file") {
+            const bytes = await this.readFileObject(locator.artifact_id, false);
+            return bytes === null
+                ? null
+                : {
+                    artifact_id: locator.artifact_id,
+                    kind: "file",
+                    size_bytes: bytes.byteLength,
+                };
+        }
+        return this.readDirectoryObject(locator.artifact_id, false);
+    }
+    async require(locator) {
+        const object = await this.resolve(locator);
+        if (!object) {
+            throw new ArtifactStoreError("artifact_not_found", `${locator.artifact_kind} artifact not found: ${locator.artifact_id}`);
+        }
+        return object;
+    }
+    async readFileBytes(artifactId) {
+        await this.ensureLayout();
+        const bytes = await this.readFileObject(artifactId, true);
+        if (bytes === null) {
+            throw new ArtifactStoreError("artifact_not_found", `file artifact not found: ${artifactId}`);
+        }
+        return Buffer.from(bytes);
+    }
+    async readGitCommitBytes(artifactId) {
+        const object = await this.readGitCommitObject(artifactId, true);
+        if (!object) {
+            throw new ArtifactStoreError("artifact_not_found", `git_commit artifact not found: ${artifactId}`);
+        }
+        return canonicalBytes({
+            schema_version: GIT_COMMIT_ARTIFACT_SCHEMA_VERSION,
+            kind: object.kind,
+            repository_id: object.repository_id,
+            object_format: object.object_format,
+            commit_oid: object.commit_oid,
+        });
+    }
+    async verifyGitCommitInWorkspace(locator, workspaceRoot) {
+        if (locator.artifact_kind !== "git_commit") {
+            throw new ArtifactStoreError("invalid_request", "verifyGitCommitInWorkspace requires a git_commit artifact");
+        }
+        const object = await this.require(locator);
+        if (object.kind !== "git_commit") {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit locator resolved to ${object.kind}`);
+        }
+        const observed = await this.inspectGitCommit(workspaceRoot, object.commit_oid);
+        if (observed.repository_id !== object.repository_id
+            || observed.object_format !== object.object_format
+            || observed.commit_oid !== object.commit_oid) {
+            throw new ArtifactStoreError("source_drift", "git_commit artifact does not belong to the target workspace repository");
+        }
+        return object;
+    }
+    async verifyGitCommitProducedByAttempt(locator, workspaceRoot, baselineCommitOid, expectedBranchRef) {
+        const object = await this.verifyGitCommitInWorkspace(locator, workspaceRoot);
+        if (!gitCommitPattern(object.object_format).test(baselineCommitOid)) {
+            throw new ArtifactStoreError("source_drift", "git_commit attempt baseline is not a full lowercase commit id");
+        }
+        const baseline = await this.inspectGitCommit(workspaceRoot, baselineCommitOid);
+        if (baseline.repository_id !== object.repository_id
+            || baseline.object_format !== object.object_format) {
+            throw new ArtifactStoreError("source_drift", "git_commit attempt baseline belongs to a different repository");
+        }
+        const currentHead = await gitOutput(workspaceRoot, ["rev-parse", "--verify", "HEAD"], "current Git HEAD", "source_drift");
+        if (currentHead !== object.commit_oid) {
+            throw new ArtifactStoreError("source_drift", "git_commit output does not match the stopped attempt workspace HEAD");
+        }
+        if (currentHead === baselineCommitOid) {
+            throw new ArtifactStoreError("source_drift", "git_commit output reuses the attempt workspace baseline commit");
+        }
+        const currentBranchRef = await gitBranchRef(workspaceRoot);
+        if (currentBranchRef !== expectedBranchRef) {
+            throw new ArtifactStoreError("source_drift", "git_commit output changed the committed attempt workspace branch");
+        }
+        await gitOutput(workspaceRoot, ["merge-base", "--is-ancestor", baselineCommitOid, currentHead], "Git commit ancestry", "source_drift");
+        return object;
+    }
+    async beforeSourceRevalidation(_sourcePath, _kind) { }
+    async ensureLayout() {
+        await mkdir(this.options.root_directory, {
+            recursive: true,
+            mode: DIRECTORY_MODE,
+        });
+        await assertDirectoryPath(this.options.root_directory, "artifact store root");
+        await chmod(this.options.root_directory, DIRECTORY_MODE);
+        const realRoot = await realpath(this.options.root_directory);
+        for (const path of [
+            join(this.options.root_directory, "objects"),
+            this.fileObjectsDirectory(),
+            this.directoryObjectsDirectory(),
+            this.gitCommitObjectsDirectory(),
+            this.temporaryDirectory(),
+        ]) {
+            try {
+                await mkdir(path, { mode: DIRECTORY_MODE });
+            }
+            catch (error) {
+                if (!isErrno(error, "EEXIST"))
+                    throw error;
+            }
+            await assertDirectoryPath(path, "artifact store directory");
+            await chmod(path, DIRECTORY_MODE);
+            if (!isContained(realRoot, await realpath(path))) {
+                throw new ArtifactStoreError("invalid_options", `artifact store directory escapes its root: ${path}`);
+            }
+        }
+    }
+    fileObjectsDirectory() {
+        return join(this.options.root_directory, "objects", "files");
+    }
+    directoryObjectsDirectory() {
+        return join(this.options.root_directory, "objects", "directories");
+    }
+    gitCommitObjectsDirectory() {
+        return join(this.options.root_directory, "objects", "git-commits");
+    }
+    temporaryDirectory() {
+        return join(this.options.root_directory, "tmp");
+    }
+    fileObjectPath(artifactId) {
+        return join(this.fileObjectsDirectory(), artifactHex(artifactId));
+    }
+    directoryObjectPath(artifactId) {
+        return join(this.directoryObjectsDirectory(), `${artifactHex(artifactId)}.json`);
+    }
+    gitCommitObjectPath(artifactId) {
+        return join(this.gitCommitObjectsDirectory(), `${artifactHex(artifactId)}.json`);
+    }
+    async resolveSource(workspaceRoot, sourcePath) {
+        const root = resolve(workspaceRoot);
+        const candidate = resolve(root, sourcePath);
+        if (!isContained(root, candidate)) {
+            throw new ArtifactStoreError("source_outside_workspace", `artifact source escapes its workspace: ${sourcePath}`);
+        }
+        const rootStats = await requireLstat(root);
+        if (assertRegularNode(rootStats, root) !== "directory") {
+            throw new ArtifactStoreError("source_kind_mismatch", `workspace_root must be a directory: ${root}`);
+        }
+        const child = relative(root, candidate);
+        let current = root;
+        for (const segment of child.split(sep).filter(Boolean)) {
+            current = join(current, segment);
+            const component = await requireLstat(current);
+            const kind = assertRegularNode(component, current);
+            if (current !== candidate && kind !== "directory") {
+                throw new ArtifactStoreError("source_not_found", `artifact source parent is not a directory: ${current}`);
+            }
+        }
+        const [realRoot, realCandidate] = await Promise.all([
+            realpath(root),
+            realpath(candidate),
+        ]);
+        if (!isContained(realRoot, realCandidate)) {
+            throw new ArtifactStoreError("source_outside_workspace", `artifact source resolves outside its workspace: ${sourcePath}`);
+        }
+        const normalized = relative(root, candidate).split(sep).join("/") || ".";
+        return {
+            workspace_path: root,
+            real_workspace_path: realRoot,
+            lexical_path: candidate,
+            absolute_path: realCandidate,
+            relative_path: normalized,
+        };
+    }
+    async assertSourceResolutionStable(source) {
+        try {
+            const workspaceStats = await lstat(source.workspace_path, { bigint: true });
+            if (assertRegularNode(workspaceStats, source.workspace_path) !== "directory") {
+                throw new Error("workspace root is no longer a directory");
+            }
+            const child = relative(source.workspace_path, source.lexical_path);
+            let current = source.workspace_path;
+            for (const segment of child.split(sep).filter(Boolean)) {
+                current = join(current, segment);
+                const stats = await lstat(current, { bigint: true });
+                const kind = assertRegularNode(stats, current);
+                if (current !== source.lexical_path && kind !== "directory") {
+                    throw new Error(`source parent is no longer a directory: ${current}`);
+                }
+            }
+            const [realWorkspace, realSource] = await Promise.all([
+                realpath(source.workspace_path),
+                realpath(source.lexical_path),
+            ]);
+            if (realWorkspace !== source.real_workspace_path ||
+                realSource !== source.absolute_path ||
+                !isContained(realWorkspace, realSource)) {
+                throw new Error("source realpath changed");
+            }
+        }
+        catch {
+            // Node has no openat-style descriptor-relative traversal. These repeated
+            // checks detect ordinary drift; the service must also keep the attempt
+            // workspace namespace quiescent for the entire capture transaction.
+            throw new ArtifactStoreError("source_drift", `artifact source resolution changed during capture: ${source.relative_path}`);
+        }
+    }
+    async captureGitCommit(workspaceRoot, commitOid) {
+        const observed = await this.inspectGitCommit(workspaceRoot, commitOid);
+        const stored = {
+            schema_version: GIT_COMMIT_ARTIFACT_SCHEMA_VERSION,
+            kind: "git_commit",
+            repository_id: observed.repository_id,
+            object_format: observed.object_format,
+            commit_oid: observed.commit_oid,
+        };
+        const bytes = canonicalBytes(stored);
+        const artifactId = gitCommitIdentity(stored);
+        await this.publishNoReplace(bytes, this.gitCommitObjectPath(artifactId));
+        return {
+            artifact_id: artifactId,
+            kind: "git_commit",
+            size_bytes: bytes.byteLength,
+            repository_id: observed.repository_id,
+            object_format: observed.object_format,
+            commit_oid: observed.commit_oid,
+        };
+    }
+    async inspectGitCommit(workspaceRoot, commitOid) {
+        const rootStats = await requireLstat(workspaceRoot);
+        if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+            throw new ArtifactStoreError("git_repository_invalid", "git_commit workspace_root must be a real directory");
+        }
+        const realWorkspaceRoot = await realpath(workspaceRoot);
+        const [worktreeRootValue, commonDirectoryValue, objectFormatValue] = await Promise.all([
+            gitOutput(realWorkspaceRoot, ["rev-parse", "--show-toplevel"], "Git worktree root"),
+            gitOutput(realWorkspaceRoot, ["rev-parse", "--git-common-dir"], "Git common directory"),
+            gitOutput(realWorkspaceRoot, ["rev-parse", "--show-object-format"], "Git object format"),
+        ]);
+        const realWorktreeRoot = await realpath(worktreeRootValue);
+        if (!isContained(realWorktreeRoot, realWorkspaceRoot)) {
+            throw new ArtifactStoreError("git_repository_invalid", "git_commit workspace_root is outside the resolved Git worktree");
+        }
+        if (objectFormatValue !== "sha1" && objectFormatValue !== "sha256") {
+            throw new ArtifactStoreError("git_repository_invalid", `unsupported Git object format: ${objectFormatValue}`);
+        }
+        const objectFormat = objectFormatValue;
+        if (!gitCommitPattern(objectFormat).test(commitOid)) {
+            throw new ArtifactStoreError("git_commit_invalid", `git_commit source_path must be a full lowercase ${objectFormat} commit id`);
+        }
+        const resolvedCommit = await gitOutput(realWorkspaceRoot, ["rev-parse", "--verify", `${commitOid}^{commit}`], "Git commit object", "git_commit_invalid");
+        if (resolvedCommit !== commitOid) {
+            throw new ArtifactStoreError("git_commit_invalid", "git_commit source_path must identify the exact commit object without indirection");
+        }
+        const objectType = await gitOutput(realWorkspaceRoot, ["cat-file", "-t", commitOid], "Git object type", "git_commit_invalid");
+        if (objectType !== "commit") {
+            throw new ArtifactStoreError("git_commit_invalid", "git_commit source_path does not identify a commit object");
+        }
+        const commonDirectory = isAbsolute(commonDirectoryValue)
+            ? commonDirectoryValue
+            : resolve(realWorkspaceRoot, commonDirectoryValue);
+        let realCommonDirectory;
+        try {
+            realCommonDirectory = await realpath(commonDirectory);
+        }
+        catch {
+            throw new ArtifactStoreError("git_repository_invalid", "resolved Git common directory is unavailable");
+        }
+        const repositoryId = sha256(canonicalBytes({
+            object_format: objectFormat,
+            common_directory: realCommonDirectory,
+        }));
+        return {
+            repository_id: repositoryId,
+            object_format: objectFormat,
+            commit_oid: commitOid,
+        };
+    }
+    async captureFile(path) {
+        const first = await stableFileRead(path, this.options.max_file_size_bytes);
+        await this.beforeSourceRevalidation(path, "file");
+        let second;
+        try {
+            second = await stableFileRead(path, this.options.max_file_size_bytes);
+        }
+        catch {
+            throw new ArtifactStoreError("source_drift", `file artifact source changed during capture: ${path}`);
+        }
+        if (!signaturesEqual(first.signature, second.signature) ||
+            !first.bytes.equals(second.bytes)) {
+            throw new ArtifactStoreError("source_drift", `file artifact source changed during capture: ${path}`);
+        }
+        const artifactId = sha256(first.bytes);
+        await this.publishNoReplace(first.bytes, this.fileObjectPath(artifactId));
+        return {
+            artifact_id: artifactId,
+            kind: "file",
+            size_bytes: first.bytes.byteLength,
+        };
+    }
+    async captureDirectory(path) {
+        const first = await this.scanDirectory(path, true);
+        await this.beforeSourceRevalidation(path, "directory");
+        let second;
+        try {
+            second = await this.scanDirectory(path, false);
+        }
+        catch (error) {
+            if (error instanceof ArtifactStoreError && error.code === "limit_exceeded") {
+                throw error;
+            }
+            throw new ArtifactStoreError("source_drift", `directory artifact source changed during capture: ${path}`);
+        }
+        if (canonicalizeJson(first.manifest) !== canonicalizeJson(second.manifest) ||
+            !this.signatureMapsEqual(first.signatures, second.signatures)) {
+            throw new ArtifactStoreError("source_drift", `directory artifact source changed during capture: ${path}`);
+        }
+        const artifactId = directoryIdentity(first.manifest);
+        const stored = {
+            schema_version: DIRECTORY_ARTIFACT_SCHEMA_VERSION,
+            kind: "directory",
+            size_bytes: first.size_bytes,
+            manifest: first.manifest,
+        };
+        const storedBytes = canonicalBytes(stored);
+        if (storedBytes.byteLength > this.options.max_manifest_size_bytes) {
+            throw new ArtifactStoreError("limit_exceeded", "directory artifact manifest exceeds the configured size limit");
+        }
+        await this.publishNoReplace(storedBytes, this.directoryObjectPath(artifactId));
+        return {
+            artifact_id: artifactId,
+            kind: "directory",
+            size_bytes: first.size_bytes,
+            manifest: first.manifest,
+        };
+    }
+    async scanDirectory(root, publishFiles) {
+        const entries = [];
+        const signatures = new Map();
+        let sizeBytes = 0;
+        const walk = async (directory, relativeDirectory) => {
+            const before = await requireLstat(directory);
+            if (assertRegularNode(before, directory) !== "directory") {
+                throw new ArtifactStoreError("source_kind_mismatch", `expected a directory artifact source: ${directory}`);
+            }
+            const names = await readdir(directory);
+            names.sort(comparePosixPath);
+            for (const name of names) {
+                if (name.includes("\\")) {
+                    throw new ArtifactStoreError("special_file_not_allowed", `backslash is not allowed in portable artifact paths: ${join(directory, name)}`);
+                }
+                const absolutePath = join(directory, name);
+                const relativePath = relativeDirectory
+                    ? `${relativeDirectory}/${name}`
+                    : name;
+                const nodeStats = await requireLstat(absolutePath);
+                const kind = assertRegularNode(nodeStats, absolutePath);
+                if (entries.length >= this.options.max_directory_entries) {
+                    throw new ArtifactStoreError("limit_exceeded", `directory artifact exceeds ${this.options.max_directory_entries} entries`);
+                }
+                if (kind === "directory") {
+                    entries.push({ kind: "directory", path: relativePath });
+                    await walk(absolutePath, relativePath);
+                    continue;
+                }
+                const file = await stableFileRead(absolutePath, this.options.max_file_size_bytes);
+                const artifactId = sha256(file.bytes);
+                if (publishFiles) {
+                    await this.publishNoReplace(file.bytes, this.fileObjectPath(artifactId));
+                }
+                sizeBytes += file.bytes.byteLength;
+                if (!Number.isSafeInteger(sizeBytes) ||
+                    sizeBytes > this.options.max_directory_size_bytes) {
+                    throw new ArtifactStoreError("limit_exceeded", `directory artifact exceeds ${this.options.max_directory_size_bytes} bytes`);
+                }
+                entries.push({
+                    kind: "file",
+                    path: relativePath,
+                    artifact_id: artifactId,
+                    size_bytes: file.bytes.byteLength,
+                });
+                signatures.set(relativePath, file.signature);
+            }
+            const after = await requireLstat(directory);
+            if (!signaturesEqual(signatureOf(before), signatureOf(after))) {
+                throw new ArtifactStoreError("source_drift", `directory changed while it was read: ${directory}`);
+            }
+            signatures.set(relativeDirectory || ".", signatureOf(after));
+        };
+        await walk(root, "");
+        entries.sort((left, right) => comparePosixPath(left.path, right.path));
+        return { manifest: entries, size_bytes: sizeBytes, signatures };
+    }
+    signatureMapsEqual(left, right) {
+        if (left.size !== right.size)
+            return false;
+        for (const [path, signature] of left) {
+            const other = right.get(path);
+            if (!other || !signaturesEqual(signature, other))
+                return false;
+        }
+        return true;
+    }
+    async publishNoReplace(bytes, target) {
+        const temporary = join(this.temporaryDirectory(), `${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporary, "wx", 0o600);
+            await handle.writeFile(bytes);
+            await handle.chmod(STORED_FILE_MODE);
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            while (true) {
+                try {
+                    await link(temporary, target);
+                    await syncDirectory(dirname(target));
+                    return;
+                }
+                catch (error) {
+                    if (!isErrno(error, "EEXIST"))
+                        throw error;
+                    await syncDirectory(dirname(target));
+                    let existingStats;
+                    try {
+                        existingStats = await lstat(target, { bigint: true });
+                    }
+                    catch (readError) {
+                        if (isErrno(readError, "ENOENT"))
+                            continue;
+                        throw readError;
+                    }
+                    if (!existingStats.isFile() ||
+                        existingStats.isSymbolicLink() ||
+                        (existingStats.mode & 146n) !== 0n) {
+                        throw new ArtifactStoreError("artifact_corrupt", `artifact object path is not a regular file: ${target}`);
+                    }
+                    let existingHandle;
+                    try {
+                        existingHandle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+                    }
+                    catch (readError) {
+                        if (isErrno(readError, "ENOENT"))
+                            continue;
+                        throw new ArtifactStoreError("artifact_corrupt", `artifact object cannot be opened safely: ${target}`);
+                    }
+                    let existing;
+                    try {
+                        const openedBefore = await existingHandle.stat({ bigint: true });
+                        if (!openedBefore.isFile() ||
+                            (openedBefore.mode & 146n) !== 0n ||
+                            !stableObjectIdentityEqual(signatureOf(existingStats), signatureOf(openedBefore))) {
+                            throw new ArtifactStoreError("artifact_corrupt", `artifact object changed before CAS validation: ${target}`);
+                        }
+                        try {
+                            existing = await readBounded(existingHandle, bytes.byteLength, target);
+                        }
+                        catch {
+                            throw new ArtifactStoreError("artifact_corrupt", `artifact object conflicts with immutable content: ${target}`);
+                        }
+                        const openedAfter = await existingHandle.stat({ bigint: true });
+                        let afterPath;
+                        try {
+                            afterPath = await lstat(target, { bigint: true });
+                        }
+                        catch (readError) {
+                            if (isErrno(readError, "ENOENT"))
+                                continue;
+                            throw readError;
+                        }
+                        if (!afterPath.isFile() ||
+                            afterPath.isSymbolicLink() ||
+                            (afterPath.mode & 146n) !== 0n ||
+                            !stableObjectIdentityEqual(signatureOf(openedBefore), signatureOf(openedAfter)) ||
+                            !stableObjectIdentityEqual(signatureOf(openedAfter), signatureOf(afterPath))) {
+                            throw new ArtifactStoreError("artifact_corrupt", `artifact object changed during CAS validation: ${target}`);
+                        }
+                    }
+                    finally {
+                        await existingHandle.close();
+                    }
+                    if (!existing.equals(bytes)) {
+                        throw new ArtifactStoreError("artifact_corrupt", `artifact object conflicts with immutable content: ${target}`);
+                    }
+                    return;
+                }
+            }
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+            await rm(temporary, { force: true });
+        }
+    }
+    async readFileObject(artifactId, required) {
+        const path = this.fileObjectPath(artifactId);
+        let stats;
+        try {
+            stats = await lstat(path, { bigint: true });
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT") && !required)
+                return null;
+            if (isErrno(error, "ENOENT")) {
+                throw new ArtifactStoreError("artifact_not_found", `file artifact not found: ${artifactId}`);
+            }
+            throw error;
+        }
+        if (!stats.isFile() ||
+            stats.isSymbolicLink() ||
+            (stats.mode & 146n) !== 0n) {
+            throw new ArtifactStoreError("artifact_corrupt", `file artifact object is not a regular file: ${artifactId}`);
+        }
+        if (stats.size > BigInt(this.options.max_file_size_bytes)) {
+            throw new ArtifactStoreError("artifact_corrupt", `file artifact exceeds the configured size limit: ${artifactId}`);
+        }
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            bytes = await readBounded(handle, this.options.max_file_size_bytes, path);
+            const after = await handle.stat({ bigint: true });
+            if (!signaturesEqual(signatureOf(stats), signatureOf(after))) {
+                throw new ArtifactStoreError("artifact_corrupt", `file artifact changed while it was read: ${artifactId}`);
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        if (sha256(bytes) !== artifactId) {
+            throw new ArtifactStoreError("artifact_corrupt", `file artifact digest mismatch: ${artifactId}`);
+        }
+        return bytes;
+    }
+    async readDirectoryObject(artifactId, required) {
+        const path = this.directoryObjectPath(artifactId);
+        let stats;
+        try {
+            stats = await lstat(path, { bigint: true });
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT") && !required)
+                return null;
+            if (isErrno(error, "ENOENT")) {
+                throw new ArtifactStoreError("artifact_not_found", `directory artifact not found: ${artifactId}`);
+            }
+            throw error;
+        }
+        if (!stats.isFile() ||
+            stats.isSymbolicLink() ||
+            (stats.mode & 146n) !== 0n) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact object is not a regular file: ${artifactId}`);
+        }
+        if (stats.size > BigInt(this.options.max_manifest_size_bytes)) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact manifest exceeds the configured size limit: ${artifactId}`);
+        }
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            bytes = await readBounded(handle, this.options.max_manifest_size_bytes, path);
+            const after = await handle.stat({ bigint: true });
+            if (!signaturesEqual(signatureOf(stats), signatureOf(after))) {
+                throw new ArtifactStoreError("artifact_corrupt", `directory artifact changed while it was read: ${artifactId}`);
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact manifest is not valid JSON: ${artifactId}`);
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact wrapper is invalid: ${artifactId}`);
+        }
+        const candidate = parsed;
+        if (!exactObjectKeys(candidate, [
+            "kind",
+            "manifest",
+            "schema_version",
+            "size_bytes",
+        ]) ||
+            candidate.schema_version !== DIRECTORY_ARTIFACT_SCHEMA_VERSION ||
+            candidate.kind !== "directory") {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact wrapper schema is invalid: ${artifactId}`);
+        }
+        let canonical;
+        try {
+            canonical = canonicalBytes(parsed);
+        }
+        catch {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact wrapper is not canonical JSON: ${artifactId}`);
+        }
+        if (!bytes.equals(canonical)) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact wrapper bytes are not canonical: ${artifactId}`);
+        }
+        const manifest = validateManifest(candidate.manifest, candidate.size_bytes, this.options.max_directory_entries);
+        if (candidate.size_bytes > this.options.max_directory_size_bytes) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact exceeds the configured size limit: ${artifactId}`);
+        }
+        if (directoryIdentity(manifest) !== artifactId) {
+            throw new ArtifactStoreError("artifact_corrupt", `directory artifact digest mismatch: ${artifactId}`);
+        }
+        for (const entry of manifest) {
+            if (entry.kind !== "file")
+                continue;
+            let file;
+            try {
+                file = await this.readFileBytes(entry.artifact_id);
+            }
+            catch (error) {
+                if (error instanceof ArtifactStoreError) {
+                    throw new ArtifactStoreError("artifact_corrupt", `directory artifact references an invalid file object at ${entry.path}`);
+                }
+                throw error;
+            }
+            if (file.byteLength !== entry.size_bytes) {
+                throw new ArtifactStoreError("artifact_corrupt", `directory artifact file size mismatch at ${entry.path}`);
+            }
+        }
+        return {
+            artifact_id: artifactId,
+            kind: "directory",
+            size_bytes: candidate.size_bytes,
+            manifest,
+        };
+    }
+    async readGitCommitObject(artifactId, required) {
+        const path = this.gitCommitObjectPath(artifactId);
+        let stats;
+        try {
+            stats = await lstat(path, { bigint: true });
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT") && !required)
+                return null;
+            if (isErrno(error, "ENOENT")) {
+                throw new ArtifactStoreError("artifact_not_found", `git_commit artifact not found: ${artifactId}`);
+            }
+            throw error;
+        }
+        if (!stats.isFile()
+            || stats.isSymbolicLink()
+            || (stats.mode & 146n) !== 0n) {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact object is not a regular file: ${artifactId}`);
+        }
+        if (stats.size > BigInt(this.options.max_manifest_size_bytes)) {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact exceeds the configured size limit: ${artifactId}`);
+        }
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            bytes = await readBounded(handle, this.options.max_manifest_size_bytes, path);
+            const after = await handle.stat({ bigint: true });
+            if (!signaturesEqual(signatureOf(stats), signatureOf(after))) {
+                throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact changed while it was read: ${artifactId}`);
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact wrapper is not JSON: ${artifactId}`);
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact wrapper schema is invalid: ${artifactId}`);
+        }
+        const candidate = parsed;
+        if (!exactObjectKeys(candidate, [
+            "commit_oid",
+            "kind",
+            "object_format",
+            "repository_id",
+            "schema_version",
+        ])
+            || candidate.schema_version !== GIT_COMMIT_ARTIFACT_SCHEMA_VERSION
+            || candidate.kind !== "git_commit"
+            || (candidate.object_format !== "sha1" && candidate.object_format !== "sha256")
+            || typeof candidate.repository_id !== "string"
+            || !SHA256_PATTERN.test(candidate.repository_id)
+            || typeof candidate.commit_oid !== "string"
+            || !gitCommitPattern(candidate.object_format).test(candidate.commit_oid)) {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact wrapper schema is invalid: ${artifactId}`);
+        }
+        const stored = candidate;
+        const canonical = canonicalBytes(stored);
+        if (!bytes.equals(canonical) || gitCommitIdentity(stored) !== artifactId) {
+            throw new ArtifactStoreError("artifact_corrupt", `git_commit artifact digest mismatch: ${artifactId}`);
+        }
+        return {
+            artifact_id: artifactId,
+            kind: "git_commit",
+            size_bytes: bytes.byteLength,
+            repository_id: stored.repository_id,
+            object_format: stored.object_format,
+            commit_oid: stored.commit_oid,
+        };
+    }
+}
+export class ArtifactMaterializer {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async materialize(request) {
+        return this.materializeWithExistingTargetPolicy(request, "conflict");
+    }
+    /** Reuses an existing target only after verifying the complete immutable artifact. */
+    async materializeReplaySafe(request) {
+        return this.materializeWithExistingTargetPolicy(request, "reuse_if_identical");
+    }
+    async materializeWithExistingTargetPolicy(request, existingTargetPolicy) {
+        assertArtifactKind(request.artifact_kind);
+        if (!request.destination_root.trim()) {
+            throw new ArtifactStoreError("invalid_request", "destination_root must be a non-empty string");
+        }
+        if (!request.binding_id.trim()
+            || Buffer.byteLength(request.binding_id, "utf8") > MAX_BINDING_ID_BYTES
+            || /[\u0000-\u001f\u007f]/u.test(request.binding_id)) {
+            throw new ArtifactStoreError("invalid_request", "binding_id must be a non-empty printable identifier within the size limit");
+        }
+        if (request.artifact_kind === "git_commit") {
+            throw new ArtifactStoreError("unsupported_artifact_kind", "git_commit artifacts are not supported in S1");
+        }
+        const destinationRoot = resolve(request.destination_root);
+        await mkdir(destinationRoot, { recursive: true, mode: DIRECTORY_MODE });
+        const rootStats = await lstat(destinationRoot, { bigint: true });
+        if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+            throw new ArtifactStoreError("unsafe_destination", `materialization root must be a real directory: ${destinationRoot}`);
+        }
+        await chmod(destinationRoot, DIRECTORY_MODE);
+        const realRoot = await realpath(destinationRoot);
+        const bindingPathSegment = `binding-${createHash("sha256")
+            .update(request.binding_id, "utf8")
+            .digest("hex")}`;
+        const target = join(realRoot, bindingPathSegment);
+        if (!isContained(realRoot, target)) {
+            throw new ArtifactStoreError("unsafe_destination", `materialized path escapes its destination root: ${target}`);
+        }
+        const object = await this.store.require(request);
+        if (object.kind === "file") {
+            await this.materializeFile(object, target, existingTargetPolicy);
+        }
+        else if (object.kind === "directory") {
+            await this.materializeDirectory(object, target, existingTargetPolicy);
+        }
+        else {
+            throw new ArtifactStoreError("unsupported_artifact_kind", "git_commit artifacts are delivered as typed identities, not filesystem materializations");
+        }
+        return {
+            artifact_id: object.artifact_id,
+            artifact_kind: object.kind,
+            materialized_path: target,
+        };
+    }
+    async beforePostCopyVerification(_materializedPath, _object) { }
+    async materializeFile(object, target, existingTargetPolicy) {
+        const bytes = await this.store.readFileBytes(object.artifact_id);
+        let handle;
+        try {
+            handle = await open(target, "wx", MATERIALIZED_FILE_MODE);
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST")) {
+                if (existingTargetPolicy === "reuse_if_identical") {
+                    await this.verifyExistingMaterialization(target, object);
+                    return;
+                }
+                throw new ArtifactStoreError("materialization_conflict", `materialized artifact path already exists: ${target}`);
+            }
+            throw error;
+        }
+        try {
+            try {
+                await handle.writeFile(bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await chmod(target, MATERIALIZED_FILE_MODE);
+            await this.beforePostCopyVerification(target, object);
+            await this.verifyMaterializedFile(target, object);
+        }
+        catch (error) {
+            await handle.close().catch(() => undefined);
+            await rm(target, { force: true });
+            throw error;
+        }
+    }
+    async materializeDirectory(object, target, existingTargetPolicy) {
+        try {
+            await mkdir(target, { mode: DIRECTORY_MODE });
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST")) {
+                if (existingTargetPolicy === "reuse_if_identical") {
+                    await this.verifyExistingMaterialization(target, object);
+                    return;
+                }
+                throw new ArtifactStoreError("materialization_conflict", `materialized artifact path already exists: ${target}`);
+            }
+            throw error;
+        }
+        try {
+            const manifest = object.manifest ?? [];
+            const directories = [];
+            for (const entry of manifest) {
+                const path = join(target, ...entry.path.split("/"));
+                if (entry.kind === "directory") {
+                    await mkdir(path, { mode: DIRECTORY_MODE });
+                    directories.push(path);
+                    continue;
+                }
+                const bytes = await this.store.readFileBytes(entry.artifact_id);
+                const handle = await open(path, "wx", MATERIALIZED_FILE_MODE);
+                try {
+                    await handle.writeFile(bytes);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await chmod(path, MATERIALIZED_FILE_MODE);
+            }
+            directories.sort((left, right) => right.length - left.length);
+            for (const directory of directories) {
+                await chmod(directory, MATERIALIZED_DIRECTORY_MODE);
+            }
+            await chmod(target, MATERIALIZED_DIRECTORY_MODE);
+            await this.beforePostCopyVerification(target, object);
+            await this.verifyMaterializedDirectory(target, object);
+        }
+        catch (error) {
+            await removeMaterializedTree(target);
+            throw error;
+        }
+    }
+    async verifyExistingMaterialization(target, object) {
+        try {
+            if (object.kind === "file") {
+                await this.verifyMaterializedFile(target, object);
+            }
+            else if (object.kind === "directory") {
+                await this.verifyMaterializedDirectory(target, object);
+            }
+            else {
+                throw new ArtifactStoreError("unsupported_artifact_kind", "git_commit artifacts do not use filesystem materialization");
+            }
+        }
+        catch {
+            throw new ArtifactStoreError("materialization_conflict", `existing materialization does not match ${object.kind} artifact ${object.artifact_id}: ${target}`);
+        }
+    }
+    async verifyMaterializedFile(path, object) {
+        const stats = await lstat(path, { bigint: true });
+        if (!stats.isFile() ||
+            stats.isSymbolicLink() ||
+            (stats.mode & 146n) !== 0n) {
+            throw new ArtifactStoreError("materialization_verification_failed", `materialized file is not a read-only regular file: ${path}`);
+        }
+        const bytes = await readForMaterializationVerification(path, object.size_bytes);
+        if (bytes.byteLength !== object.size_bytes ||
+            sha256(bytes) !== object.artifact_id) {
+            throw new ArtifactStoreError("materialization_verification_failed", `materialized file content does not match ${object.artifact_id}`);
+        }
+    }
+    async verifyMaterializedDirectory(root, object) {
+        const entries = [];
+        let sizeBytes = 0;
+        const walk = async (directory, relativeDirectory) => {
+            const directoryStats = await lstat(directory, { bigint: true });
+            if (!directoryStats.isDirectory() ||
+                directoryStats.isSymbolicLink() ||
+                (directoryStats.mode & 146n) !== 0n) {
+                throw new ArtifactStoreError("materialization_verification_failed", `materialized directory is not read-only: ${directory}`);
+            }
+            const names = await readdir(directory);
+            names.sort(comparePosixPath);
+            for (const name of names) {
+                if (entries.length >= (object.manifest?.length ?? 0)) {
+                    throw new ArtifactStoreError("materialization_verification_failed", `materialized directory contains unexpected entries: ${root}`);
+                }
+                const path = join(directory, name);
+                const relativePath = relativeDirectory
+                    ? `${relativeDirectory}/${name}`
+                    : name;
+                const stats = await lstat(path, { bigint: true });
+                if (stats.isSymbolicLink()) {
+                    throw new ArtifactStoreError("materialization_verification_failed", `materialized artifact contains a symbolic link: ${path}`);
+                }
+                if (stats.isDirectory()) {
+                    entries.push({ kind: "directory", path: relativePath });
+                    await walk(path, relativePath);
+                    continue;
+                }
+                if (!stats.isFile() || (stats.mode & 146n) !== 0n) {
+                    throw new ArtifactStoreError("materialization_verification_failed", `materialized artifact contains an invalid file: ${path}`);
+                }
+                const bytes = await readForMaterializationVerification(path, object.size_bytes - sizeBytes);
+                sizeBytes += bytes.byteLength;
+                if (sizeBytes > object.size_bytes) {
+                    throw new ArtifactStoreError("materialization_verification_failed", `materialized directory exceeds expected size: ${root}`);
+                }
+                entries.push({
+                    kind: "file",
+                    path: relativePath,
+                    artifact_id: sha256(bytes),
+                    size_bytes: bytes.byteLength,
+                });
+            }
+        };
+        await walk(root, "");
+        entries.sort((left, right) => comparePosixPath(left.path, right.path));
+        if (sizeBytes !== object.size_bytes ||
+            canonicalizeJson(entries) !== canonicalizeJson(object.manifest ?? []) ||
+            directoryIdentity(entries) !== object.artifact_id) {
+            throw new ArtifactStoreError("materialization_verification_failed", `materialized directory content does not match ${object.artifact_id}`);
+        }
+    }
+}
+async function removeMaterializedTree(path) {
+    const makeWritable = async (candidate) => {
+        let stats;
+        try {
+            stats = await lstat(candidate, { bigint: true });
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return;
+            throw error;
+        }
+        if (stats.isSymbolicLink())
+            return;
+        if (!stats.isDirectory()) {
+            await chmod(candidate, 0o600);
+            return;
+        }
+        await chmod(candidate, DIRECTORY_MODE);
+        for (const name of await readdir(candidate)) {
+            await makeWritable(join(candidate, name));
+        }
+    };
+    try {
+        await makeWritable(path);
+        await rm(path, { recursive: true, force: true });
+    }
+    catch {
+        // Cleanup must not replace the integrity error that caused it.
+    }
+}
+export { ArtifactStore as ImmutableArtifactStore };