@agen-ai/sandbox 0.0.0-stage → 0.4.4

package/dist/node/directories/ownership.js

@@ -0,0 +1,148 @@
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { SandboxOperationError } from "../../errors.js";
+import { parseSandboxRelativePath } from "../../files/paths.js";
+import { sameIdentity } from "../hostPath.js";
+import { closeAfter } from "./closing.js";
+function identityName(fileStats) {
+  return `${fileStats.dev}-${fileStats.ino}`;
+}
+function missing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+class DirectoryOwnership {
+  constructor(directory, token) {
+    this.directory = directory;
+    this.token = token;
+  }
+  handles = /* @__PURE__ */ new Set();
+  pending;
+  async open(path, flags, mode) {
+    const handle = await open(path, flags, mode);
+    this.handles.add(handle);
+    return handle;
+  }
+  async closeFile(handle) {
+    await handle.close();
+    this.handles.delete(handle);
+  }
+  async remember(path, fileStats, kind, file) {
+    const marker = join(this.directory, identityName(fileStats));
+    let handle;
+    try {
+      handle = await this.open(marker, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 384);
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+      await this.inspect(path, fileStats, kind);
+      return;
+    }
+    await closeAfter(async () => {
+      const own = await handle.stat({ bigint: true });
+      this.pending = { path: marker, fileStats: own };
+      const record = {
+        token: this.token,
+        path,
+        kind,
+        device: String(fileStats.dev),
+        inode: String(fileStats.ino),
+        markerDevice: String(own.dev),
+        markerInode: String(own.ino),
+        ...file
+      };
+      await handle.writeFile(JSON.stringify(record));
+      this.pending = void 0;
+    }, () => this.closeFile(handle));
+  }
+  async inspect(path, fileStats, kind) {
+    const record = await this.lookup(fileStats, kind);
+    if (record.path !== path || record.kind !== kind || record.device !== String(fileStats.dev) || record.inode !== String(fileStats.ino)) {
+      throw new SandboxOperationError("output_limit", "Host filesystem path aliases or replaces another owned entry.");
+    }
+    return record;
+  }
+  async lookup(fileStats, kind) {
+    const record = await this.readMarker(join(this.directory, identityName(fileStats)));
+    if (record.kind !== kind || record.device !== String(fileStats.dev) || record.inode !== String(fileStats.ino)) {
+      throw new Error("Output inode does not match its retained ownership marker.");
+    }
+    return record;
+  }
+  async forget(fileStats) {
+    const path = join(this.directory, identityName(fileStats));
+    await this.readMarker(path);
+    await unlink(path);
+  }
+  async readMarker(path) {
+    const handle = await this.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    return closeAfter(async () => {
+      const fileStats = await handle.stat({ bigint: true });
+      if (!fileStats.isFile() || fileStats.size < 1n || fileStats.size > 4096n) throw new Error("Unrecognized directory ownership marker.");
+      const bytes = new Uint8Array(Number(fileStats.size));
+      let offset = 0;
+      while (offset < bytes.byteLength) {
+        const { bytesRead } = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+        if (!bytesRead) throw new Error("Directory ownership marker is truncated.");
+        offset += bytesRead;
+      }
+      const record = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+      if (!record || typeof record !== "object" || !("token" in record) || record.token !== this.token || !("path" in record) || typeof record.path !== "string" || !("kind" in record) || record.kind !== "file" && record.kind !== "directory" || !("device" in record) || typeof record.device !== "string" || !/^[0-9]+$/u.test(record.device) || !("inode" in record) || typeof record.inode !== "string" || !/^[0-9]+$/u.test(record.inode) || !("markerDevice" in record) || record.markerDevice !== String(fileStats.dev) || !("markerInode" in record) || record.markerInode !== String(fileStats.ino)) throw new Error("Unrecognized directory ownership marker.");
+      const allowed = record.kind === "file" ? ["token", "path", "kind", "device", "inode", "markerDevice", "markerInode", "byteLength", "executable"] : ["token", "path", "kind", "device", "inode", "markerDevice", "markerInode"];
+      if (Object.keys(record).length !== allowed.length || Object.keys(record).some((key) => !allowed.includes(key))) {
+        throw new Error("Ownership marker has unrecognized fields.");
+      }
+      parseSandboxRelativePath(record.path);
+      if (record.kind === "file") {
+        if (!("byteLength" in record) || typeof record.byteLength !== "number" || !Number.isSafeInteger(record.byteLength) || record.byteLength < 0 || !("executable" in record) || typeof record.executable !== "boolean") throw new Error("Invalid file ownership marker.");
+        return {
+          token: this.token,
+          path: record.path,
+          kind: "file",
+          device: record.device,
+          inode: record.inode,
+          markerDevice: String(fileStats.dev),
+          markerInode: String(fileStats.ino),
+          byteLength: record.byteLength,
+          executable: record.executable
+        };
+      }
+      return {
+        token: this.token,
+        path: record.path,
+        kind: "directory",
+        device: record.device,
+        inode: record.inode,
+        markerDevice: String(fileStats.dev),
+        markerInode: String(fileStats.ino)
+      };
+    }, () => this.closeFile(handle));
+  }
+  async closeHandles() {
+    let failure;
+    for (const handle of this.handles) {
+      try {
+        await this.closeFile(handle);
+      } catch (error) {
+        failure ??= { error };
+      }
+    }
+    if (failure) throw failure.error;
+    const pending = this.pending;
+    if (pending) {
+      let fileStats;
+      try {
+        fileStats = await lstat(pending.path, { bigint: true });
+      } catch (error) {
+        if (!missing(error)) throw error;
+        this.pending = void 0;
+        return;
+      }
+      if (!fileStats.isFile() || !sameIdentity(fileStats, pending.fileStats)) throw new Error("Partial ownership marker was replaced; it is preserved.");
+      await unlink(pending.path);
+      this.pending = void 0;
+    }
+  }
+}
+export {
+  DirectoryOwnership
+};

package/dist/node/directories/source.d.ts

@@ -0,0 +1,25 @@
+import type { BigIntStats } from 'node:fs';
+import type { SandboxTreeEntry } from '../../files/types.js';
+export declare class DirectorySource implements AsyncIterable<SandboxTreeEntry> {
+    private readonly root;
+    private readonly rootMetadata;
+    private readonly chunkBytes;
+    private readonly controller;
+    private readonly signal;
+    private readonly directories;
+    private file;
+    private opening;
+    private pending;
+    private closing;
+    private phase;
+    private iterated;
+    constructor(root: string, rootMetadata: BigIntStats, chunkBytes: number, signal?: AbortSignal);
+    [Symbol.asyncIterator](): AsyncIterator<SandboxTreeEntry>;
+    private next;
+    private pull;
+    private openDirectory;
+    private verifyParents;
+    close(): Promise<void>;
+    private check;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/node/directories/source.js

@@ -0,0 +1,143 @@
+import { lstat, opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { SandboxOperationError, SandboxStateError } from "../../errors.js";
+import { parseSandboxRelativePath } from "../../files/paths.js";
+import { verifyDirectoryIdentity } from "../hostPath.js";
+import { DirectoryFile } from "./file.js";
+class DirectorySource {
+  constructor(root, rootMetadata, chunkBytes, signal) {
+    this.root = root;
+    this.rootMetadata = rootMetadata;
+    this.chunkBytes = chunkBytes;
+    this.signal = signal ? AbortSignal.any([signal, this.controller.signal]) : this.controller.signal;
+  }
+  controller = new AbortController();
+  signal;
+  directories = [];
+  file;
+  opening;
+  pending;
+  closing;
+  phase = "ready";
+  iterated = false;
+  [Symbol.asyncIterator]() {
+    if (this.iterated || this.phase !== "ready") throw new SandboxStateError("Host directory sources admit one transfer iterator.");
+    this.iterated = true;
+    this.phase = "reading";
+    return { next: () => this.next(), return: async () => {
+      await this.close();
+      return { done: true, value: void 0 };
+    } };
+  }
+  next() {
+    if (this.phase !== "reading" || this.pending) return Promise.reject(new SandboxStateError("Host traversal requires one active iterator pull."));
+    const actual = this.pull();
+    this.pending = actual;
+    void actual.then(() => {
+      this.pending = void 0;
+    }, () => {
+      this.pending = void 0;
+    });
+    return actual;
+  }
+  async pull() {
+    this.check();
+    if (this.file) {
+      await this.file.close();
+      this.file = void 0;
+    }
+    if (!this.opening) this.opening = this.openDirectory(this.root, "", this.rootMetadata);
+    await this.opening;
+    this.check();
+    while (true) {
+      const current = this.directories.at(-1);
+      if (!current) return { done: true, value: void 0 };
+      await this.verifyParents();
+      this.check();
+      const entry = await current.directory.read();
+      this.check();
+      if (!entry) {
+        await current.directory.close();
+        this.directories.pop();
+        continue;
+      }
+      const relative = parseSandboxRelativePath(current.relative ? `${current.relative}/${entry.name}` : entry.name);
+      const path = join(current.path, entry.name);
+      const metadata = await lstat(path, { bigint: true });
+      this.check();
+      if (metadata.isDirectory()) {
+        await this.openDirectory(path, relative, metadata);
+        return { done: false, value: Object.freeze({ kind: "directory", path: relative }) };
+      }
+      if (!metadata.isFile() || metadata.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new SandboxOperationError("input_limit", "Host imports require regular files and directories with representable lengths; links and special files are rejected.");
+      }
+      const file = new DirectoryFile(path, metadata, this.signal, this.chunkBytes, () => this.verifyParents());
+      this.file = file;
+      return { done: false, value: Object.freeze({
+        kind: "file",
+        path: relative,
+        byteLength: Number(metadata.size),
+        executable: (metadata.mode & 0o111n) !== 0n,
+        open: (input) => file.open(input)
+      }) };
+    }
+  }
+  async openDirectory(path, relative, metadata) {
+    this.check();
+    await verifyDirectoryIdentity(path, metadata);
+    this.check();
+    const directory = await opendir(path, { bufferSize: 32 });
+    this.directories.push({ path, relative, metadata, directory });
+    await verifyDirectoryIdentity(path, metadata);
+    this.check();
+  }
+  async verifyParents() {
+    this.check();
+    for (const directory of this.directories) {
+      await verifyDirectoryIdentity(directory.path, directory.metadata);
+      this.check();
+    }
+  }
+  close() {
+    if (this.phase === "closed") return Promise.resolve();
+    if (this.closing) return this.closing;
+    this.phase = "closing";
+    this.controller.abort(new SandboxStateError("Host directory source is closing."));
+    this.closing = (async () => {
+      await this.pending?.catch(() => {
+      });
+      const failures = [];
+      if (this.file) {
+        try {
+          await this.file.close();
+          this.file = void 0;
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      for (let index = this.directories.length - 1; index >= 0; index -= 1) {
+        const directory = this.directories[index];
+        if (!directory) continue;
+        try {
+          await directory.directory.close();
+          this.directories.splice(index, 1);
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      if (failures.length) throw new AggregateError(failures, "Host source handles retain cleanup ownership.");
+      this.phase = "closed";
+    })().finally(() => {
+      this.closing = void 0;
+    });
+    return this.closing;
+  }
+  check() {
+    this.signal.throwIfAborted();
+    if (this.phase !== "reading") throw new SandboxStateError("Host directory source admission is closed.");
+  }
+}
+export {
+  DirectorySource
+};

package/dist/node/directories/stage.d.ts

@@ -0,0 +1,43 @@
+import type { BigIntStats } from 'node:fs';
+import type { SandboxExportEntry } from '../../files/types.js';
+export declare class DirectoryStage {
+    readonly destination: string;
+    private readonly parent;
+    private readonly controller;
+    private readonly signal;
+    private readonly token;
+    private namespace;
+    private stage;
+    private markers;
+    private ownership;
+    private unregistered;
+    private active;
+    private closing;
+    private accepting;
+    private published;
+    private closed;
+    private readonly unverified;
+    private readonly directoryHandles;
+    readonly directory: string;
+    constructor(destination: string, parent: BigIntStats, signal?: AbortSignal);
+    get publishedDirectory(): string | undefined;
+    initialize(): Promise<void>;
+    consume(entry: SandboxExportEntry, input: Readonly<{
+        signal: AbortSignal;
+    }>): Promise<void>;
+    private write;
+    fence(reason: unknown): void;
+    publish(): Promise<void>;
+    close(): Promise<void>;
+    private walk;
+    private removeMarkers;
+    private verifyMarkers;
+    private openDirectory;
+    private closeDirectory;
+    private closeDirectories;
+    private verifyRoots;
+    private readyStage;
+    private readyOwnership;
+    private check;
+}
+//# sourceMappingURL=stage.d.ts.map

package/dist/node/directories/stage.js

@@ -0,0 +1,302 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, opendir, rename, rmdir, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { SandboxOperationError, SandboxStateError } from "../../errors.js";
+import { parseSandboxRelativePath } from "../../files/paths.js";
+import { sameIdentity, verifyDirectoryIdentity } from "../hostPath.js";
+import { DirectoryOwnership } from "./ownership.js";
+import { closeAfter } from "./closing.js";
+function missing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+class DirectoryStage {
+  constructor(destination, parent, signal) {
+    this.destination = destination;
+    this.parent = parent;
+    this.signal = signal ? AbortSignal.any([signal, this.controller.signal]) : this.controller.signal;
+    this.directory = join(destination, "files");
+  }
+  controller = new AbortController();
+  signal;
+  token = randomUUID();
+  namespace;
+  stage;
+  markers;
+  ownership;
+  unregistered;
+  active;
+  closing;
+  accepting = true;
+  published = false;
+  closed = false;
+  unverified = /* @__PURE__ */ new Set();
+  directoryHandles = /* @__PURE__ */ new Set();
+  directory;
+  get publishedDirectory() {
+    return this.published ? this.directory : void 0;
+  }
+  async initialize() {
+    this.check();
+    await verifyDirectoryIdentity(dirname(this.destination), this.parent);
+    await mkdir(this.destination, { mode: 448 });
+    this.unverified.add(this.destination);
+    this.namespace = { path: this.destination, metadata: await lstat(this.destination, { bigint: true }) };
+    this.unverified.delete(this.destination);
+    this.check();
+    const stage = join(this.destination, `.staging-${this.token}`);
+    await mkdir(stage, { mode: 448 });
+    this.unverified.add(stage);
+    this.stage = { path: stage, metadata: await lstat(stage, { bigint: true }) };
+    this.unverified.delete(stage);
+    this.check();
+    const markers = join(this.destination, `.metadata-${this.token}`);
+    await mkdir(markers, { mode: 448 });
+    this.unverified.add(markers);
+    this.markers = { path: markers, metadata: await lstat(markers, { bigint: true }) };
+    this.unverified.delete(markers);
+    this.ownership = new DirectoryOwnership(markers, this.token);
+    this.check();
+  }
+  consume(entry, input) {
+    if (!this.accepting || this.active) return Promise.reject(new SandboxStateError("Directory sink is closed or already consuming an entry."));
+    const actual = Promise.resolve().then(() => this.write(entry, AbortSignal.any([input.signal, this.signal])));
+    this.active = actual;
+    void actual.then(() => {
+      this.active = void 0;
+    }, (error) => {
+      this.active = void 0;
+      this.fence(error);
+    });
+    return actual;
+  }
+  async write(entry, signal) {
+    this.check();
+    signal.throwIfAborted();
+    await this.verifyRoots();
+    this.check();
+    signal.throwIfAborted();
+    const relative = parseSandboxRelativePath(entry.path);
+    const stage = this.readyStage();
+    const ownership = this.readyOwnership();
+    const segments = relative.split("/");
+    const directories = entry.kind === "directory" ? segments : segments.slice(0, -1);
+    let parent = stage.path;
+    let logical = "";
+    for (const segment of directories) {
+      this.check();
+      signal.throwIfAborted();
+      logical = logical ? `${logical}/${segment}` : segment;
+      parent = join(parent, segment);
+      let created = false;
+      try {
+        await mkdir(parent, { mode: 448 });
+        created = true;
+      } catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+      }
+      const metadata = await lstat(parent, { bigint: true });
+      if (!metadata.isDirectory()) throw new SandboxOperationError("output_limit", "Export directory was replaced by a link or non-directory.");
+      if (created) this.unregistered = { path: parent, metadata, kind: "directory" };
+      await ownership.remember(logical, metadata, "directory");
+      this.unregistered = void 0;
+    }
+    if (entry.kind === "directory") return;
+    this.check();
+    signal.throwIfAborted();
+    const path = join(stage.path, ...segments);
+    const handle = await ownership.open(
+      path,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+      entry.executable ? 448 : 384
+    );
+    await closeAfter(async () => {
+      const metadata = await handle.stat({ bigint: true });
+      this.unregistered = { path, metadata, kind: "file" };
+      await ownership.remember(relative, metadata, "file", { byteLength: entry.byteLength, executable: entry.executable });
+      this.unregistered = void 0;
+      let offset = 0;
+      for await (const chunk of entry.bytes) {
+        this.check();
+        signal.throwIfAborted();
+        if (!(chunk instanceof Uint8Array) || chunk.byteLength > entry.byteLength - offset) throw new Error("Export file body exceeds its declared length.");
+        let written = 0;
+        while (written < chunk.byteLength) {
+          const result = await handle.write(chunk, written, chunk.byteLength - written, offset);
+          if (!result.bytesWritten) throw new Error("Export file write made no progress.");
+          written += result.bytesWritten;
+          offset += result.bytesWritten;
+          this.check();
+          signal.throwIfAborted();
+        }
+      }
+      if (offset !== entry.byteLength) throw new Error("Export file body ended before its declared length.");
+      this.check();
+      signal.throwIfAborted();
+    }, () => ownership.closeFile(handle));
+  }
+  fence(reason) {
+    this.accepting = false;
+    if (!this.controller.signal.aborted) this.controller.abort(reason);
+  }
+  async publish() {
+    await this.active;
+    this.check();
+    await this.verifyRoots();
+    await this.readyOwnership().closeHandles();
+    await this.walk(this.readyStage().path, "", false);
+    await this.verifyMarkers();
+    this.check();
+    try {
+      await lstat(this.directory);
+      throw new Error("Published child already exists and is preserved.");
+    } catch (error) {
+      if (!missing(error)) throw error;
+    }
+    await rename(this.readyStage().path, this.directory);
+    this.published = true;
+    this.stage = void 0;
+    this.accepting = false;
+  }
+  close() {
+    if (this.closed) return Promise.resolve();
+    if (this.closing) return this.closing;
+    this.fence(new SandboxStateError("Directory sink is closing."));
+    this.closing = (async () => {
+      await this.active?.catch(() => {
+      });
+      await this.ownership?.closeHandles();
+      await this.closeDirectories();
+      if (this.unverified.size) throw new Error("An acquired output directory has no verified identity and is preserved.");
+      if (!this.namespace) {
+        this.closed = true;
+        return;
+      }
+      await this.verifyRoots();
+      if (this.unregistered) {
+        const entry = this.unregistered;
+        const current = await lstat(entry.path, { bigint: true });
+        if (!sameIdentity(current, entry.metadata)) throw new Error("Partially acquired output entry was replaced and is preserved.");
+        if (entry.kind === "file") await unlink(entry.path);
+        else await rmdir(entry.path);
+        this.unregistered = void 0;
+      }
+      if (this.stage) {
+        if (this.ownership) await this.walk(this.stage.path, "", true);
+        await rmdir(this.stage.path);
+        this.stage = void 0;
+      }
+      await this.removeMarkers();
+      if (!this.published) await rmdir(this.namespace.path);
+      this.closed = true;
+    })().finally(() => {
+      this.closing = void 0;
+    });
+    return this.closing;
+  }
+  async walk(path, relative, remove) {
+    const directory = await this.openDirectory(path);
+    await closeAfter(async () => {
+      while (true) {
+        const entry = await directory.read();
+        if (!entry) break;
+        const child = join(path, entry.name);
+        const metadata = await lstat(child, { bigint: true });
+        const kind = metadata.isDirectory() ? "directory" : metadata.isFile() ? "file" : void 0;
+        if (!kind) throw new Error("Unknown link or special output entry is preserved.");
+        const record = await this.readyOwnership().lookup(metadata, kind);
+        const separator = record.path.lastIndexOf("/");
+        const parent = separator < 0 ? "" : record.path.slice(0, separator);
+        const declared = await lstat(join(this.readyStage().path, ...record.path.split("/")), { bigint: true });
+        if (parent !== relative || !sameIdentity(declared, metadata) || kind === "file" && metadata.nlink !== 1n) {
+          throw new Error("An unexpected alias or relocated output entry is preserved.");
+        }
+        if (kind === "directory") await this.walk(child, record.path, remove);
+        else if (!remove && (metadata.size !== BigInt(record.byteLength ?? -1) || (metadata.mode & 0o111n) !== 0n !== record.executable)) {
+          throw new Error("Staged output file length or executable mode changed.");
+        }
+        if (remove) {
+          if (kind === "directory") await rmdir(child);
+          else await unlink(child);
+          await this.readyOwnership().forget(metadata);
+        }
+      }
+    }, () => this.closeDirectory(directory));
+  }
+  async removeMarkers() {
+    if (!this.markers) return;
+    const markers = this.markers;
+    const directory = await this.openDirectory(markers.path);
+    await closeAfter(async () => {
+      while (true) {
+        const entry = await directory.read();
+        if (!entry) break;
+        const path = join(markers.path, entry.name);
+        const record = await this.readyOwnership().readMarker(path);
+        if (entry.name !== `${record.device}-${record.inode}`) throw new Error("Unexpected control entry is preserved.");
+        await unlink(path);
+      }
+    }, () => this.closeDirectory(directory));
+    await rmdir(markers.path);
+    this.markers = void 0;
+  }
+  async verifyMarkers() {
+    if (!this.markers) throw new SandboxStateError("Directory ownership storage is not acquired.");
+    const markers = this.markers;
+    const directory = await this.openDirectory(markers.path);
+    await closeAfter(async () => {
+      while (true) {
+        this.check();
+        const entry = await directory.read();
+        if (!entry) break;
+        const record = await this.readyOwnership().readMarker(join(markers.path, entry.name));
+        if (entry.name !== `${record.device}-${record.inode}`) throw new Error("Unexpected control entry is preserved.");
+        const metadata = await lstat(join(this.readyStage().path, ...record.path.split("/")), { bigint: true });
+        if (String(metadata.dev) !== record.device || String(metadata.ino) !== record.inode || (record.kind === "directory" ? !metadata.isDirectory() : !metadata.isFile() || metadata.size !== BigInt(record.byteLength ?? -1) || metadata.nlink !== 1n || (metadata.mode & 0o111n) !== 0n !== record.executable)) {
+          throw new Error("An expected staged entry was changed or replaced before publication.");
+        }
+      }
+    }, () => this.closeDirectory(directory));
+  }
+  async openDirectory(path) {
+    const directory = await opendir(path, { bufferSize: 32 });
+    this.directoryHandles.add(directory);
+    return directory;
+  }
+  async closeDirectory(directory) {
+    await directory.close();
+    this.directoryHandles.delete(directory);
+  }
+  async closeDirectories() {
+    let failure;
+    for (const directory of this.directoryHandles) {
+      try {
+        await this.closeDirectory(directory);
+      } catch (error) {
+        failure ??= { error };
+      }
+    }
+    if (failure) throw failure.error;
+  }
+  async verifyRoots() {
+    await verifyDirectoryIdentity(dirname(this.destination), this.parent);
+    if (this.namespace) await verifyDirectoryIdentity(this.namespace.path, this.namespace.metadata);
+    if (this.stage) await verifyDirectoryIdentity(this.stage.path, this.stage.metadata);
+    if (this.markers) await verifyDirectoryIdentity(this.markers.path, this.markers.metadata);
+  }
+  readyStage() {
+    if (!this.stage) throw new SandboxStateError("Directory staging is not acquired.");
+    return this.stage;
+  }
+  readyOwnership() {
+    if (!this.ownership) throw new SandboxStateError("Directory ownership storage is not acquired.");
+    return this.ownership;
+  }
+  check() {
+    this.signal.throwIfAborted();
+    if (!this.accepting) throw new SandboxStateError("Directory sink admission is closed.");
+  }
+}
+export {
+  DirectoryStage
+};

package/dist/node/directories/types.d.ts

@@ -0,0 +1,23 @@
+import type { SandboxTransferOptions, SandboxTransferSummary } from '../../files/types.js';
+export interface SandboxDirectoryImportOptions extends SandboxTransferOptions {
+    /** Match a smaller explicitly configured sandbox buffer. Defaults to 64 KiB. */
+    readonly chunkBytes?: number;
+}
+export interface SandboxDirectoryExportResult {
+    /** Published child of the exclusively created caller-selected destination namespace. */
+    readonly directory: string;
+    readonly summary: SandboxTransferSummary;
+}
+export interface DirectoryCleanupOwner {
+    close(): Promise<void>;
+}
+export declare class SandboxDirectoryCleanupError extends Error {
+    readonly primaryError: unknown;
+    readonly cleanupError: unknown;
+    readonly directory: string;
+    private readonly owner;
+    readonly publishedDirectory?: string | undefined;
+    constructor(primaryError: unknown, cleanupError: unknown, directory: string, owner: DirectoryCleanupOwner, publishedDirectory?: string | undefined);
+    retryCleanup(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map