@guilz-dev/belay 0.8.0 → 0.9.0

package/dist/core/contained-execution/mirror.js

@@ -0,0 +1,587 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, open, opendir, readlink, realpath, rm, symlink, } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { inspectGitResourceIdentity } from '../git-resource-identity.js';
+import { canonicalPath } from '../path-utils.js';
+import { computeTreeHash, FILE_CHECKPOINT_HARDLINK_UNSUPPORTED, FILE_CHECKPOINT_PREPARE_TIMEOUT, FILE_CHECKPOINT_QUOTA_EXCEEDED, FILE_CHECKPOINT_UNSUPPORTED_NODE, FileCheckpointDiagnosticError, } from '../transactional/file-tree.js';
+import { compareRelativePathsBytewise, joinRelativePath } from '../transactional/file-tree-path.js';
+import { hashDirectoryNode, hashFileNode, hashSymlinkTarget, } from '../transactional/snapshot-node.js';
+import { ContainedExecutionFailureError } from './failure.js';
+export const CONTAINED_EXECUTION_CLEANUP_UNCONFIRMED = 'contained_execution_cleanup_unconfirmed';
+export const CONTAINED_EXECUTION_SOURCE_CHANGED = 'contained_execution_source_changed';
+export const CONTAINED_EXECUTION_UNSAFE_SYMLINK = 'contained_execution_unsafe_symlink';
+export class ContainedExecutionCleanupUnconfirmedError extends ContainedExecutionFailureError {
+    mirrorRoot;
+    constructor(mirrorRoot, options) {
+        super(CONTAINED_EXECUTION_CLEANUP_UNCONFIRMED, options);
+        this.mirrorRoot = mirrorRoot;
+        this.name = 'ContainedExecutionCleanupUnconfirmedError';
+    }
+}
+function canonicalRootSet(roots) {
+    return [...new Set(roots.map(canonicalPath))].sort();
+}
+const mirrorLeases = new WeakMap();
+/** Internal execution-boundary check; the public core index deliberately does not re-export it. */
+export function validateContainedExecutionMirrorLease(handle, expected) {
+    const lease = mirrorLeases.get(handle);
+    const protectedRoots = canonicalRootSet(expected.protectedRoots);
+    return Boolean(lease?.live &&
+        lease.sourceRoot === canonicalPath(expected.sourceRoot) &&
+        lease.hostMirrorRoot === handle.hostMirrorRoot &&
+        lease.guestWorkspacePath === handle.guestWorkspacePath &&
+        lease.backend === handle.backend &&
+        lease.protectedRoots.length === protectedRoots.length &&
+        lease.protectedRoots.every((root, index) => root === protectedRoots[index]));
+}
+const productionDependencies = {
+    makeTempRoot: () => mkdtemp(path.join(os.tmpdir(), 'belay-contained-mirror-')),
+    removeRoot: (root) => rm(root, { recursive: true, force: true }),
+    now: () => Date.now(),
+};
+function dependenciesForTests(overrides) {
+    return {
+        makeTempRoot: overrides.makeTempRoot ?? productionDependencies.makeTempRoot,
+        removeRoot: overrides.removeRoot ?? productionDependencies.removeRoot,
+        now: overrides.now ?? productionDependencies.now,
+        afterSnapshotCaptured: overrides.afterSnapshotCaptured,
+        beforeCopyOpen: overrides.beforeCopyOpen,
+        afterCopyRead: overrides.afterCopyRead,
+    };
+}
+function isAtOrWithin(root, target) {
+    const relative = path.relative(root, target);
+    return (relative === '' ||
+        (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`)));
+}
+function isGitMetadataRelativePath(relativePath) {
+    return relativePath.split(path.sep).some((segment) => segment.toLowerCase() === '.git');
+}
+function identityFromStats(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mode: stats.mode,
+        size: stats.size,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+    };
+}
+function identitiesEqual(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function safePermissionMode(mode) {
+    return Number(mode) & 0o777;
+}
+function assertDeadline(deadlineMs, now) {
+    if (now() > deadlineMs) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_PREPARE_TIMEOUT, `mirror preparation exceeded deadlineMs=${deadlineMs}`);
+    }
+}
+function throwQuota(detail) {
+    throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, detail);
+}
+function addSnapshotNode(context) {
+    context.fileCount += 1;
+    if (context.fileCount > context.limits.maxFiles) {
+        throwQuota(`mirror nodeCount=${context.fileCount} exceeds maxFiles=${context.limits.maxFiles}`);
+    }
+}
+function addSourceBytes(context, bytes) {
+    context.sourceBytes += bytes;
+    if (context.sourceBytes > context.limits.maxSourceBytes) {
+        throwQuota(`mirror sourceBytes=${context.sourceBytes} exceeds maxSourceBytes=${context.limits.maxSourceBytes}`);
+    }
+}
+function addWorkspaceBytes(context, bytes) {
+    context.workspaceBytes += bytes;
+    if (context.workspaceBytes > context.limits.maxWorkspaceBytes) {
+        throwQuota(`mirror workspaceBytes=${context.workspaceBytes} exceeds maxWorkspaceBytes=${context.limits.maxWorkspaceBytes}`);
+    }
+}
+function safeReadFlags() {
+    if (fsConstants.O_NOFOLLOW === undefined || fsConstants.O_NONBLOCK === undefined) {
+        throw new ContainedExecutionFailureError('contained_execution_safe_open_unavailable');
+    }
+    return fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
+}
+function assertRegularSingleLink(stats) {
+    if (!stats.isFile()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (stats.nlink > 1) {
+        throw new Error(FILE_CHECKPOINT_HARDLINK_UNSUPPORTED);
+    }
+}
+function assertRegularSingleLinkBigInt(stats) {
+    if (!stats.isFile()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (stats.nlink > 1n) {
+        throw new Error(FILE_CHECKPOINT_HARDLINK_UNSUPPORTED);
+    }
+}
+async function readStableFile(absolutePath, context) {
+    assertDeadline(context.deadlineMs, context.now);
+    const before = await lstat(absolutePath, { bigint: true });
+    if (!before.isFile()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (before.nlink > 1n) {
+        throw new Error(FILE_CHECKPOINT_HARDLINK_UNSUPPORTED);
+    }
+    const source = await open(absolutePath, safeReadFlags());
+    try {
+        const opened = await source.stat({ bigint: true });
+        assertRegularSingleLinkBigInt(opened);
+        const openedIdentity = identityFromStats(opened);
+        if (!identitiesEqual(identityFromStats(before), openedIdentity)) {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        const hash = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (true) {
+            assertDeadline(context.deadlineMs, context.now);
+            const { bytesRead } = await source.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0) {
+                break;
+            }
+            addSourceBytes(context, bytesRead);
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        const after = await source.stat({ bigint: true });
+        assertRegularSingleLinkBigInt(after);
+        if (!identitiesEqual(openedIdentity, identityFromStats(after)) ||
+            BigInt(position) !== after.size) {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        const mode = Number(after.mode);
+        return {
+            node: {
+                kind: 'file',
+                mode,
+                size: position,
+                hash: hashFileNode(mode, hash.digest('hex')),
+            },
+            identity: openedIdentity,
+        };
+    }
+    finally {
+        await source.close();
+    }
+}
+function addMetadataRoots(context, directoryPath) {
+    const inspection = inspectGitResourceIdentity(directoryPath);
+    if (inspection.status === 'invalid') {
+        for (const root of inspection.metadataRoots) {
+            context.metadataRoots.add(canonicalPath(root));
+        }
+        return;
+    }
+    if (inspection.status === 'resolved' &&
+        canonicalPath(inspection.identity.repositoryRoot) === canonicalPath(directoryPath)) {
+        context.metadataRoots.add(canonicalPath(inspection.identity.gitEntryPath));
+        context.metadataRoots.add(canonicalPath(inspection.identity.gitDir));
+        context.metadataRoots.add(canonicalPath(inspection.identity.commonDir));
+    }
+}
+function pathMatchesRoots(absolutePath, roots) {
+    const lexical = path.resolve(absolutePath);
+    const canonical = canonicalPath(absolutePath);
+    for (const root of roots) {
+        if (isAtOrWithin(root, lexical) || isAtOrWithin(root, canonical)) {
+            return true;
+        }
+    }
+    return false;
+}
+function pathLexicallyMatchesRoots(absolutePath, roots) {
+    const lexical = path.resolve(absolutePath);
+    for (const root of roots) {
+        if (isAtOrWithin(root, lexical)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isLexicallyExcludedLocation(absolutePath, relativePath, context) {
+    return (isGitMetadataRelativePath(relativePath) ||
+        pathLexicallyMatchesRoots(absolutePath, context.protectedRoots) ||
+        pathLexicallyMatchesRoots(absolutePath, context.metadataRoots));
+}
+function isExcludedLocation(absolutePath, relativePath, context) {
+    return (isGitMetadataRelativePath(relativePath) ||
+        pathMatchesRoots(absolutePath, context.protectedRoots) ||
+        pathMatchesRoots(absolutePath, context.metadataRoots));
+}
+async function readSafeSymlink(absolutePath, context) {
+    const before = await lstat(absolutePath, { bigint: true });
+    if (!before.isSymbolicLink()) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+    const identity = identityFromStats(before);
+    const target = await readlink(absolutePath);
+    if (path.isAbsolute(target)) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_UNSAFE_SYMLINK);
+    }
+    const lexicalTarget = path.resolve(path.dirname(absolutePath), target);
+    if (!isAtOrWithin(context.sourceRoot, lexicalTarget) ||
+        isGitMetadataRelativePath(path.relative(context.sourceRoot, lexicalTarget)) ||
+        pathMatchesRoots(lexicalTarget, context.protectedRoots) ||
+        pathMatchesRoots(lexicalTarget, context.metadataRoots)) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_UNSAFE_SYMLINK);
+    }
+    let resolvedTarget;
+    try {
+        resolvedTarget = await realpath(absolutePath);
+    }
+    catch {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_UNSAFE_SYMLINK);
+    }
+    if (!isAtOrWithin(context.sourceRoot, resolvedTarget) ||
+        pathMatchesRoots(resolvedTarget, context.protectedRoots) ||
+        pathMatchesRoots(resolvedTarget, context.metadataRoots)) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_UNSAFE_SYMLINK);
+    }
+    const after = await lstat(absolutePath, { bigint: true });
+    const targetAfter = await readlink(absolutePath);
+    if (!after.isSymbolicLink() ||
+        !identitiesEqual(identity, identityFromStats(after)) ||
+        targetAfter !== target) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+    return {
+        node: { kind: 'symlink', target, hash: hashSymlinkTarget(target) },
+        identity,
+    };
+}
+async function walkDirectory(relativeDirectory, entries, context) {
+    assertDeadline(context.deadlineMs, context.now);
+    const absoluteDirectory = relativeDirectory
+        ? joinRelativePath(context.sourceRoot, relativeDirectory)
+        : context.sourceRoot;
+    addMetadataRoots(context, absoluteDirectory);
+    const before = await lstat(absoluteDirectory, { bigint: true });
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+    const beforeIdentity = identityFromStats(before);
+    const resolvedDirectory = await realpath(absoluteDirectory);
+    if (!isAtOrWithin(context.sourceRoot, resolvedDirectory)) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+    const directoryFlags = safeReadFlags() | (fsConstants.O_DIRECTORY ?? 0);
+    const directory = await open(absoluteDirectory, directoryFlags);
+    try {
+        const opened = await directory.stat({ bigint: true });
+        if (!opened.isDirectory() || !identitiesEqual(beforeIdentity, identityFromStats(opened))) {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        const entriesDirectory = await opendir(absoluteDirectory, { bufferSize: 32 });
+        for await (const directoryEntry of entriesDirectory) {
+            assertDeadline(context.deadlineMs, context.now);
+            const relativePath = relativeDirectory
+                ? path.join(relativeDirectory, directoryEntry.name)
+                : directoryEntry.name;
+            const absolutePath = joinRelativePath(context.sourceRoot, relativePath);
+            const info = await lstat(absolutePath);
+            if (info.isSymbolicLink()) {
+                if (isLexicallyExcludedLocation(absolutePath, relativePath, context)) {
+                    continue;
+                }
+                addSnapshotNode(context);
+                const captured = await readSafeSymlink(absolutePath, context);
+                entries.push({ relativePath, ...captured });
+                continue;
+            }
+            if (isExcludedLocation(absolutePath, relativePath, context)) {
+                continue;
+            }
+            if (info.isDirectory()) {
+                addSnapshotNode(context);
+                const node = {
+                    kind: 'directory',
+                    mode: info.mode,
+                    hash: hashDirectoryNode(info.mode),
+                };
+                entries.push({
+                    relativePath,
+                    node,
+                    identity: identityFromStats(await lstat(absolutePath, { bigint: true })),
+                });
+                await walkDirectory(relativePath, entries, context);
+                continue;
+            }
+            if (info.isFile()) {
+                assertRegularSingleLink(info);
+                addSnapshotNode(context);
+                const captured = await readStableFile(absolutePath, context);
+                entries.push({ relativePath, ...captured });
+                continue;
+            }
+            throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+        }
+        const after = await directory.stat({ bigint: true });
+        const pathAfter = await lstat(absoluteDirectory, { bigint: true });
+        if (!identitiesEqual(beforeIdentity, identityFromStats(after)) ||
+            !identitiesEqual(beforeIdentity, identityFromStats(pathAfter))) {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function buildSafeMirrorSnapshot(sourceRoot, protectedRoots, limits, deadlineMs, now) {
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const rootInfo = await lstat(canonicalSourceRoot);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+        throw new ContainedExecutionFailureError('contained_execution_source_not_directory');
+    }
+    const context = {
+        sourceRoot: canonicalSourceRoot,
+        protectedRoots,
+        metadataRoots: new Set(),
+        limits,
+        deadlineMs,
+        now,
+        fileCount: 0,
+        sourceBytes: 0,
+    };
+    const entries = [];
+    await walkDirectory('', entries, context);
+    entries.sort((left, right) => compareRelativePathsBytewise(left.relativePath, right.relativePath));
+    return { entries, treeHash: computeTreeHash(entries) };
+}
+function assertEntryIdentity(entry, identity) {
+    if (!identitiesEqual(entry.identity, identity)) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+}
+async function copyStableRegularFile(sourcePath, destinationPath, entry, context) {
+    const before = await lstat(sourcePath, { bigint: true });
+    if (!before.isFile()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (before.nlink > 1n) {
+        throw new Error(FILE_CHECKPOINT_HARDLINK_UNSUPPORTED);
+    }
+    assertEntryIdentity(entry, identityFromStats(before));
+    await context.beforeCopyOpen?.(sourcePath);
+    const source = await open(sourcePath, safeReadFlags());
+    let destination;
+    try {
+        const opened = await source.stat({ bigint: true });
+        assertRegularSingleLinkBigInt(opened);
+        const openedIdentity = identityFromStats(opened);
+        assertEntryIdentity(entry, openedIdentity);
+        if (entry.node.kind !== 'file') {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        await mkdir(path.dirname(destinationPath), { recursive: true, mode: 0o700 });
+        destination = await open(destinationPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, safePermissionMode(opened.mode));
+        const hash = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (true) {
+            assertDeadline(context.deadlineMs, context.now);
+            const { bytesRead } = await source.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0) {
+                break;
+            }
+            addSourceBytes(context, bytesRead);
+            addWorkspaceBytes(context, bytesRead);
+            hash.update(buffer.subarray(0, bytesRead));
+            let written = 0;
+            while (written < bytesRead) {
+                const result = await destination.write(buffer, written, bytesRead - written, position + written);
+                written += result.bytesWritten;
+            }
+            position += bytesRead;
+            await context.afterCopyRead?.(sourcePath, bytesRead, position);
+        }
+        const after = await source.stat({ bigint: true });
+        assertRegularSingleLinkBigInt(after);
+        if (!identitiesEqual(openedIdentity, identityFromStats(after)) ||
+            BigInt(position) !== after.size ||
+            hashFileNode(Number(after.mode), hash.digest('hex')) !== entry.node.hash) {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        await destination.sync();
+    }
+    finally {
+        await Promise.allSettled([source.close(), destination?.close() ?? Promise.resolve()]);
+    }
+    if (entry.node.kind !== 'file') {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+    await chmod(destinationPath, safePermissionMode(entry.node.mode));
+}
+async function materializeSnapshot(sourceRoot, destinationRoot, snapshot, context) {
+    const directoryEntries = [];
+    for (const entry of snapshot.entries) {
+        assertDeadline(context.deadlineMs, context.now);
+        const sourcePath = joinRelativePath(sourceRoot, entry.relativePath);
+        const destinationPath = joinRelativePath(destinationRoot, entry.relativePath);
+        if (entry.node.kind === 'directory') {
+            await mkdir(destinationPath, { recursive: true, mode: 0o700 });
+            directoryEntries.push(entry);
+            continue;
+        }
+        if (entry.node.kind === 'symlink') {
+            addWorkspaceBytes(context, Buffer.byteLength(entry.node.target));
+            const current = await readlink(sourcePath);
+            const currentInfo = await lstat(sourcePath, { bigint: true });
+            assertEntryIdentity(entry, identityFromStats(currentInfo));
+            if (current !== entry.node.target) {
+                throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+            }
+            await mkdir(path.dirname(destinationPath), { recursive: true, mode: 0o700 });
+            await symlink(entry.node.target, destinationPath);
+            continue;
+        }
+        await copyStableRegularFile(sourcePath, destinationPath, entry, context);
+    }
+    for (const entry of directoryEntries.reverse()) {
+        if (entry.node.kind !== 'directory') {
+            throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+        }
+        await chmod(joinRelativePath(destinationRoot, entry.relativePath), safePermissionMode(entry.node.mode));
+    }
+    await chmod(destinationRoot, 0o700);
+}
+async function assertStableCopiedSnapshot(sourceRoot, destinationRoot, protectedRoots, limits, deadlineMs, now, before) {
+    const [after, copied] = await Promise.all([
+        buildSafeMirrorSnapshot(sourceRoot, protectedRoots, limits, deadlineMs, now),
+        buildSafeMirrorSnapshot(destinationRoot, [], limits, deadlineMs, now),
+    ]);
+    if (before.treeHash !== after.treeHash || before.treeHash !== copied.treeHash) {
+        throw new ContainedExecutionFailureError(CONTAINED_EXECUTION_SOURCE_CHANGED);
+    }
+}
+function validateOptions(options) {
+    if (!Array.isArray(options.controlPlaneRoots)) {
+        throw new ContainedExecutionFailureError('contained_execution_control_plane_roots_required');
+    }
+    const values = [
+        options.limits?.maxFiles,
+        options.limits?.maxSourceBytes,
+        options.limits?.maxWorkspaceBytes,
+        options.limits?.prepareTimeoutMs,
+    ];
+    if (values.some((value) => !Number.isSafeInteger(value) || (value ?? 0) <= 0)) {
+        throw new ContainedExecutionFailureError('contained_execution_mirror_limits_invalid');
+    }
+}
+async function pathIsAbsent(targetPath) {
+    try {
+        await lstat(targetPath);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ENOENT';
+    }
+}
+async function cleanupOwnedRoot(root, dependencies) {
+    try {
+        await dependencies.removeRoot(root);
+    }
+    catch (error) {
+        throw new ContainedExecutionCleanupUnconfirmedError(root, { cause: error });
+    }
+    if (!(await pathIsAbsent(root))) {
+        throw new ContainedExecutionCleanupUnconfirmedError(root);
+    }
+}
+async function prepareWithDependencies(options, dependencies) {
+    validateOptions(options);
+    const guestWorkspacePath = path.resolve(options.sourceRoot);
+    const sourceRoot = canonicalPath(options.sourceRoot);
+    const protectedRoots = options.controlPlaneRoots.map((root) => canonicalPath(root));
+    if (pathMatchesRoots(sourceRoot, protectedRoots)) {
+        throw new ContainedExecutionFailureError('contained_execution_source_is_protected');
+    }
+    const guestRoot = await dependencies.makeTempRoot();
+    try {
+        await chmod(guestRoot, 0o700);
+        const deadlineMs = dependencies.now() + options.limits.prepareTimeoutMs;
+        const before = await buildSafeMirrorSnapshot(sourceRoot, protectedRoots, options.limits, deadlineMs, dependencies.now);
+        await dependencies.afterSnapshotCaptured?.();
+        await materializeSnapshot(sourceRoot, guestRoot, before, {
+            limits: options.limits,
+            deadlineMs,
+            now: dependencies.now,
+            sourceBytes: 0,
+            workspaceBytes: 0,
+            beforeCopyOpen: dependencies.beforeCopyOpen,
+            afterCopyRead: dependencies.afterCopyRead,
+        });
+        await assertStableCopiedSnapshot(sourceRoot, guestRoot, protectedRoots, options.limits, deadlineMs, dependencies.now, before);
+        await chmod(guestRoot, 0o700);
+        const lease = {
+            sourceRoot,
+            hostMirrorRoot: guestRoot,
+            guestWorkspacePath,
+            backend: 'file_copy',
+            protectedRoots: canonicalRootSet(protectedRoots),
+            live: true,
+        };
+        const handle = {
+            hostMirrorRoot: guestRoot,
+            guestWorkspacePath,
+            backend: 'file_copy',
+            async cleanup() {
+                lease.live = false;
+                await cleanupOwnedRoot(guestRoot, dependencies);
+            },
+        };
+        mirrorLeases.set(handle, lease);
+        return handle;
+    }
+    catch (error) {
+        try {
+            await cleanupOwnedRoot(guestRoot, dependencies);
+        }
+        catch (cleanupError) {
+            throw new ContainedExecutionCleanupUnconfirmedError(guestRoot, { cause: cleanupError });
+        }
+        throw error;
+    }
+}
+/**
+ * Non-atomic acceptance rule: the current source tree is read, copied, then read again. A mirror
+ * is returned only when both source observations and the copied tree have the same content/mode
+ * hash. This detects ordinary concurrent changes but does not claim an atomic filesystem snapshot.
+ */
+export function prepareContainedExecutionMirror(options) {
+    return prepareWithDependencies(options, productionDependencies);
+}
+/** Narrow test seam for deterministic allocation, race, deadline, and removal failures. */
+export function prepareContainedExecutionMirrorForTests(options, overrides) {
+    return prepareWithDependencies(options, dependenciesForTests(overrides));
+}
+async function withMirror(options, operation, dependencies) {
+    const mirror = await prepareWithDependencies(options, dependencies);
+    try {
+        return await operation(mirror);
+    }
+    finally {
+        await mirror.cleanup();
+    }
+}
+export function withContainedExecutionMirror(options, operation) {
+    return withMirror(options, operation, productionDependencies);
+}
+/** Narrow test seam matching prepareContainedExecutionMirrorForTests. */
+export function withContainedExecutionMirrorForTests(options, operation, overrides) {
+    return withMirror(options, operation, dependenciesForTests(overrides));
+}

package/dist/core/contained-execution/policy.d.ts

@@ -0,0 +1,10 @@
+import type { ScrubOptions } from '../types.js';
+/**
+ * The only pre-execution failures that may return to the ordinary one-shot approval path.
+ * Every other contained-execution failure is terminal and denies the original host command.
+ */
+export declare const CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS: readonly ["contained_execution_docker_substrate_unavailable", "contained_execution_docker_daemon_unavailable"];
+export type ContainedExecutionApprovalFallbackReason = (typeof CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS)[number];
+export declare function isContainedExecutionApprovalFallbackReason(reason: string): reason is ContainedExecutionApprovalFallbackReason;
+/** Contained guest output is a security boundary and cannot inherit user-disableable audit flags. */
+export declare const CONTAINED_EXECUTION_OUTPUT_SCRUB_OPTIONS: Readonly<Required<ScrubOptions>>;

package/dist/core/contained-execution/policy.js

@@ -0,0 +1,20 @@
+/**
+ * The only pre-execution failures that may return to the ordinary one-shot approval path.
+ * Every other contained-execution failure is terminal and denies the original host command.
+ */
+export const CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS = [
+    'contained_execution_docker_substrate_unavailable',
+    'contained_execution_docker_daemon_unavailable',
+];
+const approvalFallbackReasons = new Set(CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS);
+export function isContainedExecutionApprovalFallbackReason(reason) {
+    return approvalFallbackReasons.has(reason);
+}
+/** Contained guest output is a security boundary and cannot inherit user-disableable audit flags. */
+export const CONTAINED_EXECUTION_OUTPUT_SCRUB_OPTIONS = Object.freeze({
+    maskApprovalIds: true,
+    maskBearerTokens: true,
+    maskAuthHeaders: true,
+    maskKeyValueSecrets: true,
+    maskHighEntropyStrings: true,
+});

package/dist/core/effect-ir/index.d.ts

@@ -1,7 +1,7 @@
 export type { GitRefScope, NetworkMode, NetworkPayload, ProcessOperation, } from '../capability/request.js';
 export { effectPlanAuditFields, hashEffectPlan } from './audit.js';
 export { buildCapabilityEffectPlan, buildEffectPlan, buildPackageExecEffectNode, collectRequirements, flattenRequirementsToCapabilityRequests, } from './build.js';
-export { mergeEffectPlans, mergeRequirements, normalizeEffectTags } from './normalize.js';
+export { joinEffectOpacity, mergeEffectPlans, mergeRequirements, normalizeEffectTags, } from './normalize.js';
 export { innerRecipeFromPeel, isPackageExecLauncher, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
 export { evaluatePackageExecSegment } from './package-exec-eval.js';
 export { capabilityRequestsFromEffectPlan, capabilityRequestsToEffectRequirements, effectPlanPolicyLegacyReason, effectPlanPolicyRequiresAsk, evaluateEffectPlanPolicy, } from './policy.js';

package/dist/core/effect-ir/index.js

@@ -1,6 +1,6 @@
 export { effectPlanAuditFields, hashEffectPlan } from './audit.js';
 export { buildCapabilityEffectPlan, buildEffectPlan, buildPackageExecEffectNode, collectRequirements, flattenRequirementsToCapabilityRequests, } from './build.js';
-export { mergeEffectPlans, mergeRequirements, normalizeEffectTags } from './normalize.js';
+export { joinEffectOpacity, mergeEffectPlans, mergeRequirements, normalizeEffectTags, } from './normalize.js';
 export { innerRecipeFromPeel, isPackageExecLauncher, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
 export { evaluatePackageExecSegment } from './package-exec-eval.js';
 export { capabilityRequestsFromEffectPlan, capabilityRequestsToEffectRequirements, effectPlanPolicyLegacyReason, effectPlanPolicyRequiresAsk, evaluateEffectPlanPolicy, } from './policy.js';

package/dist/core/effect-ir/normalize.d.ts

@@ -1,4 +1,9 @@
 import type { EffectPlan, EffectRequirement, EffectTag } from './types.js';
 export declare function normalizeEffectTags(tags: Iterable<EffectTag>): readonly EffectTag[];
+/**
+ * Joins opacity evidence without allowing a later analysis stage to weaken an
+ * earlier uncertainty classification.
+ */
+export declare function joinEffectOpacity(...opacities: readonly EffectPlan['opacity'][]): EffectPlan['opacity'];
 export declare function mergeRequirements(...groups: readonly (readonly EffectRequirement[])[]): EffectRequirement[];
 export declare function mergeEffectPlans(...plans: readonly (EffectPlan | null | undefined)[]): EffectPlan | undefined;