@agen-ai/sandbox 0.0.0-stage → 0.4.4

package/dist/files/bytes.js

@@ -0,0 +1,134 @@
+import { SandboxOperationError } from "../errors.js";
+import { SANDBOX_LIMITS } from "../policy/limits.js";
+import { parseTreeMetadata, transferData } from "./parse.js";
+import { TransferIterator } from "./iterator.js";
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const byteLengthGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")?.get;
+const bufferGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")?.get;
+const byteOffsetGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")?.get;
+function actualByteLength(bytes) {
+  if (!byteLengthGetter) throw new TypeError("Typed-array byte length is unavailable.");
+  return Reflect.apply(byteLengthGetter, bytes, []);
+}
+class TransferBody {
+  constructor(byteLength, chunkBytes, requireEof, signal, open, interrupt) {
+    this.chunkBytes = chunkBytes;
+    this.requireEof = requireEof;
+    this.signal = signal;
+    this.open = open;
+    this.interrupt = interrupt;
+    this.remaining = byteLength;
+  }
+  source;
+  used = false;
+  retired = false;
+  remaining;
+  eof = false;
+  pending;
+  failure;
+  get complete() {
+    return this.remaining === 0 && (!this.requireEof || this.eof) && !this.pending && !this.failure;
+  }
+  [Symbol.asyncIterator]() {
+    if (this.used || this.retired) return this.rejectIterator("File bodies are single-use and scoped to their entry.");
+    this.used = true;
+    return { next: () => this.next(), return: async () => {
+      await this.close();
+      return { done: true, value: void 0 };
+    } };
+  }
+  rejectIterator(message) {
+    const error = new SandboxOperationError("driver_failure", message);
+    this.failure ??= { error };
+    this.interrupt(error);
+    throw error;
+  }
+  next() {
+    if (this.pending) {
+      try {
+        this.rejectIterator("Concurrent file body pulls are forbidden.");
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    }
+    if (this.retired) return Promise.reject(new SandboxOperationError("driver_failure", "File body scope has ended."));
+    const actual = (async () => {
+      this.signal.throwIfAborted();
+      if (this.remaining === 0 && (!this.requireEof || this.eof)) return { done: true, value: void 0 };
+      const open = this.open;
+      if (!open) throw new SandboxOperationError("driver_failure", "File body scope has ended.");
+      this.source ??= new TransferIterator(open());
+      const result = await this.source.next();
+      this.signal.throwIfAborted();
+      if (result.done) {
+        if (this.remaining !== 0) throw new SandboxOperationError("driver_failure", "File body ended before its declared byteLength.");
+        this.eof = true;
+        return { done: true, value: void 0 };
+      }
+      const chunk = result.value;
+      if (!(chunk instanceof Uint8Array)) throw new SandboxOperationError("driver_failure", "File bodies require Uint8Array chunks.");
+      const length = actualByteLength(chunk);
+      if (length > this.chunkBytes || length > this.remaining) throw new SandboxOperationError("driver_failure", "File body chunk exceeds its bounded buffer or declared byteLength.");
+      const bytes = new Uint8Array(length);
+      Uint8Array.prototype.set.call(bytes, chunk);
+      this.remaining -= bytes.byteLength;
+      return { done: false, value: bytes };
+    })();
+    this.pending = actual;
+    void actual.then(() => {
+      this.pending = void 0;
+    }, (error) => {
+      this.pending = void 0;
+      this.failure ??= { error };
+      this.interrupt(error);
+    });
+    return actual;
+  }
+  assertComplete() {
+    if (this.failure) throw this.failure.error;
+    if (!this.complete) throw new SandboxOperationError("driver_failure", "File body was not completely consumed before its owner returned.");
+  }
+  rejectReuse() {
+    return this.rejectIterator("Input file open is once-only.");
+  }
+  async close(retry = false) {
+    this.retired = true;
+    await this.pending?.catch(() => {
+    });
+    await this.source?.close(retry);
+    this.source = void 0;
+    this.open = void 0;
+  }
+}
+function fileFromBytes(path, bytes, options = {}) {
+  if (!(bytes instanceof Uint8Array)) throw new SandboxOperationError("input_limit", "fileFromBytes requires a byte array.");
+  const selected = transferData(options, ["executable", "chunkBytes"]);
+  const chunkBytes = selected.chunkBytes ?? SANDBOX_LIMITS.maxTransferChunkBytes;
+  if (typeof chunkBytes !== "number" || !Number.isSafeInteger(chunkBytes) || chunkBytes < 1 || chunkBytes > SANDBOX_LIMITS.maxTransferChunkBytes) throw new SandboxOperationError("input_limit", "fileFromBytes chunkBytes must fit the transfer buffer bound.");
+  const byteLength = actualByteLength(bytes);
+  if (!bufferGetter || !byteOffsetGetter) throw new TypeError("Typed-array backing storage is unavailable.");
+  const buffer = Reflect.apply(bufferGetter, bytes, []);
+  const byteOffset = Reflect.apply(byteOffsetGetter, bytes, []);
+  const executable = selected.executable ?? false;
+  if (typeof executable !== "boolean") throw new SandboxOperationError("input_limit", "fileFromBytes executable must be boolean.");
+  const candidate = {
+    kind: "file",
+    path,
+    executable,
+    byteLength,
+    open({ signal }) {
+      return { *[Symbol.iterator]() {
+        for (let offset = 0; offset < byteLength; offset += chunkBytes) {
+          signal.throwIfAborted();
+          yield new Uint8Array(buffer, byteOffset + offset, Math.min(chunkBytes, byteLength - offset));
+        }
+      } };
+    }
+  };
+  parseTreeMetadata(candidate, "open");
+  return Object.freeze(candidate);
+}
+export {
+  TransferBody,
+  fileFromBytes
+};

package/dist/files/iterator.d.ts

@@ -0,0 +1,13 @@
+export declare class TransferIterator<Value> {
+    private readonly iterator;
+    private pending;
+    private closing;
+    private closeFailed;
+    private ended;
+    constructor(source: Iterable<Value> | AsyncIterable<Value>);
+    get done(): boolean;
+    get pulling(): boolean;
+    next(): Promise<IteratorResult<Value>>;
+    close(retry?: boolean): Promise<void>;
+}
+//# sourceMappingURL=iterator.d.ts.map

package/dist/files/iterator.js

@@ -0,0 +1,59 @@
+import { SandboxOperationError } from "../errors.js";
+class TransferIterator {
+  iterator;
+  pending;
+  closing;
+  closeFailed = false;
+  ended = false;
+  constructor(source) {
+    if (source === null || typeof source !== "object" && typeof source !== "function") throw new SandboxOperationError("driver_failure", "Expected an iterable transfer source.");
+    const asyncMethod = source[Symbol.asyncIterator];
+    const method = asyncMethod ?? source[Symbol.iterator];
+    if (typeof method !== "function") throw new SandboxOperationError("driver_failure", "Expected an iterable transfer source.");
+    this.iterator = Reflect.apply(method, source, []);
+    if (this.iterator === null || typeof this.iterator !== "object" && typeof this.iterator !== "function") throw new SandboxOperationError("driver_failure", "Transfer iterator construction failed.");
+  }
+  get done() {
+    return this.ended;
+  }
+  get pulling() {
+    return this.pending !== void 0;
+  }
+  next() {
+    if (this.pending || this.closing) return Promise.reject(new SandboxOperationError("driver_failure", "Concurrent or retired transfer pulls are forbidden."));
+    if (this.ended) return Promise.resolve({ done: true, value: void 0 });
+    const actual = Promise.resolve().then(() => this.iterator.next()).then((result) => {
+      if (result === null || typeof result !== "object") throw new SandboxOperationError("driver_failure", "Transfer iterator returned an invalid result.");
+      if (result.done) {
+        this.ended = true;
+        return { done: true, value: void 0 };
+      }
+      return { done: false, value: result.value };
+    });
+    this.pending = actual;
+    void actual.then(() => {
+      this.pending = void 0;
+    }, () => {
+      this.pending = void 0;
+    });
+    return actual;
+  }
+  close(retry = false) {
+    if (this.closing && (!retry || !this.closeFailed)) return this.closing;
+    this.closeFailed = false;
+    const closing = (async () => {
+      await this.pending?.catch(() => {
+      });
+      if (!this.ended && this.iterator.return !== void 0) await this.iterator.return();
+      this.ended = true;
+    })();
+    this.closing = closing;
+    void closing.catch(() => {
+      this.closeFailed = true;
+    });
+    return closing;
+  }
+}
+export {
+  TransferIterator
+};

package/dist/files/metadata/index.d.ts

@@ -0,0 +1,12 @@
+import type { MetadataLedger, MetadataLedgerOptions } from './types.js';
+export type { MetadataLedger, MetadataLedgerOptions, MetadataRecord } from './types.js';
+export { MetadataConflictError } from './records.js';
+export declare class MetadataCleanupError extends Error {
+    readonly primaryError: unknown;
+    readonly cleanupError: unknown;
+    private readonly owner;
+    constructor(primaryError: unknown, cleanupError: unknown, owner: MetadataLedger);
+    retryCleanup(): Promise<void>;
+}
+export declare function createMetadataLedger(options: MetadataLedgerOptions): Promise<MetadataLedger>;
+//# sourceMappingURL=index.d.ts.map

package/dist/files/metadata/index.js

@@ -0,0 +1,193 @@
+import { SandboxStateError } from "../../errors.js";
+import { compareRecords, decodeRecord, MAX_RECORD_BYTES, RECORD_HEADER_BYTES } from "./records.js";
+import { encodeRecord } from "./records.js";
+import { mergePass, validateRun } from "./sort.js";
+import { address, readRecord, writeDescriptor, writeRecord } from "./storage.js";
+import { MetadataConflictError } from "./records.js";
+class MetadataCleanupError extends Error {
+  constructor(primaryError, cleanupError, owner) {
+    super("Metadata spill cleanup remains owned.", { cause: primaryError });
+    this.primaryError = primaryError;
+    this.cleanupError = cleanupError;
+    this.owner = owner;
+    this.name = "MetadataCleanupError";
+  }
+  retryCleanup() {
+    return this.owner.close();
+  }
+}
+class Ledger {
+  constructor(options) {
+    this.options = options;
+    this.signal = options.signal ? AbortSignal.any([this.controller.signal, options.signal]) : this.controller.signal;
+    this.acquiring = this.acquire();
+  }
+  phase = "open";
+  controller = new AbortController();
+  signal;
+  acquiring;
+  store;
+  files;
+  active;
+  closing;
+  batch = [];
+  batchSize = 0;
+  state = { runs: 0, end: 0, descriptorEnd: 0 };
+  reader;
+  async acquire() {
+    this.signal.throwIfAborted();
+    const store = await this.options.openSpill();
+    this.store = store;
+    this.signal.throwIfAborted();
+    const first = await store.createFile();
+    this.signal.throwIfAborted();
+    const second = await store.createFile();
+    this.signal.throwIfAborted();
+    const third = await store.createFile();
+    this.signal.throwIfAborted();
+    const fourth = await store.createFile();
+    this.signal.throwIfAborted();
+    this.files = { data: [first, second], descriptors: [third, fourth] };
+  }
+  async initialized() {
+    await this.acquiring;
+  }
+  append(record) {
+    if (this.phase !== "open" || this.active) return Promise.reject(new SandboxStateError("Metadata append requires an idle open ledger."));
+    const captured = encodeRecord(record);
+    return this.enter(async () => {
+      const size = RECORD_HEADER_BYTES + captured.key.length;
+      if (this.batchSize + size > this.options.batchBytes) await this.flush();
+      this.signal.throwIfAborted();
+      this.batch.push(captured);
+      this.batchSize += size;
+    });
+  }
+  finish() {
+    if (this.phase !== "open" || this.active) return Promise.reject(new SandboxStateError("Metadata sealing requires an idle open ledger."));
+    this.phase = "finishing";
+    return this.enter(async () => {
+      await this.flush();
+      const files = this.readyFiles();
+      while (this.state.runs > 1) this.state = await mergePass(files, this.state, this.options.fanIn, this.signal);
+      await validateRun(files.data[0], this.state.end, this.signal);
+      this.signal.throwIfAborted();
+      this.phase = "sealed";
+    });
+  }
+  records() {
+    if (this.phase !== "sealed" || this.active || this.reader) throw new SandboxStateError("Metadata records require a sealed ledger and one exclusive reader.");
+    const identity = {};
+    this.reader = identity;
+    const cursor = { position: 0, end: this.state.end };
+    let returned = false;
+    let iterated = false;
+    let pending;
+    const release = () => {
+      if (this.reader === identity) this.reader = void 0;
+    };
+    const iterator = {
+      [Symbol.asyncIterator]() {
+        if (iterated) throw new SandboxStateError("Metadata records admit one iterator.");
+        iterated = true;
+        return iterator;
+      },
+      next: () => {
+        if (returned) return Promise.resolve({ done: true, value: void 0 });
+        if (this.phase !== "sealed" || this.active) return Promise.reject(new SandboxStateError("Metadata reads require an idle sealed ledger."));
+        pending = this.enter(async () => {
+          const record = await readRecord(this.readyFiles().data[0], cursor);
+          this.signal.throwIfAborted();
+          if (!record) {
+            returned = true;
+            release();
+            return { done: true, value: void 0 };
+          }
+          return { done: false, value: decodeRecord(record) };
+        });
+        return pending;
+      },
+      return: async () => {
+        returned = true;
+        await pending?.catch(() => {
+        });
+        release();
+        return { done: true, value: void 0 };
+      }
+    };
+    return iterator;
+  }
+  close() {
+    if (this.phase === "closed") return Promise.resolve();
+    if (this.closing) return this.closing;
+    this.phase = "closing";
+    this.controller.abort(new SandboxStateError("Metadata ledger is closing."));
+    this.closing = (async () => {
+      await this.acquiring.catch(() => {
+      });
+      await this.active?.catch(() => {
+      });
+      this.batch = [];
+      this.batchSize = 0;
+      await this.store?.close();
+      this.phase = "closed";
+    })().finally(() => {
+      this.closing = void 0;
+    });
+    return this.closing;
+  }
+  enter(perform) {
+    const actual = Promise.resolve().then(() => {
+      this.signal.throwIfAborted();
+      return perform();
+    }).catch((error) => {
+      if (this.phase !== "closing" && this.phase !== "closed") this.phase = "failed";
+      throw error;
+    }).finally(() => {
+      if (this.active === actual) this.active = void 0;
+    });
+    this.active = actual;
+    return actual;
+  }
+  async flush() {
+    if (!this.batch.length) return;
+    const files = this.readyFiles();
+    this.batch.sort(compareRecords);
+    let end = this.state.end;
+    for (const record of this.batch) {
+      this.signal.throwIfAborted();
+      end = await writeRecord(files.data[0], record, end);
+    }
+    const descriptorEnd = await writeDescriptor(files.descriptors[0], this.state.descriptorEnd, this.state.end, end);
+    this.state = { runs: address(this.state.runs + 1), end, descriptorEnd };
+    this.batch = [];
+    this.batchSize = 0;
+  }
+  readyFiles() {
+    if (!this.files) throw new SandboxStateError("Metadata spill acquisition has not settled.");
+    return this.files;
+  }
+}
+async function createMetadataLedger(options) {
+  if (!Number.isSafeInteger(options.batchBytes) || options.batchBytes < MAX_RECORD_BYTES || options.batchBytes > 4 * 1024 * 1024) {
+    throw new RangeError("Metadata batch working set must be between 1029 bytes and 4 MiB.");
+  }
+  if (!Number.isSafeInteger(options.fanIn) || options.fanIn < 2 || options.fanIn > 32) throw new RangeError("Metadata merge fan-in must be between 2 and 32.");
+  const ledger = new Ledger(options);
+  try {
+    await ledger.initialized();
+    return ledger;
+  } catch (primaryError) {
+    try {
+      await ledger.close();
+    } catch (cleanupError) {
+      throw new MetadataCleanupError(primaryError, cleanupError, ledger);
+    }
+    throw primaryError;
+  }
+}
+export {
+  MetadataCleanupError,
+  MetadataConflictError,
+  createMetadataLedger
+};

package/dist/files/metadata/records.d.ts

@@ -0,0 +1,21 @@
+import { Buffer } from 'node:buffer';
+import { SandboxValidationError } from '../../errors.js';
+import type { MetadataRecord } from './types.js';
+export declare const RECORD_HEADER_BYTES = 5;
+export declare const DESCRIPTOR_BYTES = 16;
+export declare const MAX_RECORD_BYTES: number;
+export interface EncodedRecord {
+    readonly kind: MetadataRecord['kind'];
+    readonly key: Buffer;
+}
+export declare class MetadataConflictError extends SandboxValidationError {
+    readonly code: 'duplicate_path' | 'file_ancestor';
+    readonly path: string;
+    constructor(code: 'duplicate_path' | 'file_ancestor', path: string);
+}
+export declare function encodeRecord(record: MetadataRecord): EncodedRecord;
+export declare function decodeRecord(record: EncodedRecord): MetadataRecord;
+export declare function compareRecords(left: EncodedRecord, right: EncodedRecord): number;
+export declare function isDescendant(record: EncodedRecord, ancestor: EncodedRecord): boolean;
+export declare function recordHeader(record: EncodedRecord): Buffer;
+//# sourceMappingURL=records.d.ts.map

package/dist/files/metadata/records.js

@@ -0,0 +1,50 @@
+import { Buffer } from "node:buffer";
+import { SandboxValidationError } from "../../errors.js";
+import { SANDBOX_LIMITS } from "../../policy/limits.js";
+import { parseSandboxRelativePath } from "../paths.js";
+const RECORD_HEADER_BYTES = 5;
+const DESCRIPTOR_BYTES = 16;
+const MAX_RECORD_BYTES = SANDBOX_LIMITS.maxPathBytes + RECORD_HEADER_BYTES;
+class MetadataConflictError extends SandboxValidationError {
+  constructor(code, path) {
+    super([{ code: "invalid_input", path: ["path"], message: `Metadata ${code}: ${path}` }]);
+    this.code = code;
+    this.path = path;
+    this.name = "MetadataConflictError";
+  }
+}
+function encodeRecord(record) {
+  const key = Buffer.from(record.path, "utf8");
+  for (let index = 0; index < key.length; index += 1) if (key[index] === 47) key[index] = 0;
+  return { kind: record.kind, key };
+}
+function decodeRecord(record) {
+  const encoded = record.key.toString("utf8");
+  if (record.key.includes(47) || !Buffer.from(encoded, "utf8").equals(record.key)) {
+    throw new Error("Spill path encoding is invalid.");
+  }
+  return Object.freeze({ kind: record.kind, path: parseSandboxRelativePath(encoded.replaceAll("\0", "/")) });
+}
+function compareRecords(left, right) {
+  return Buffer.compare(left.key, right.key);
+}
+function isDescendant(record, ancestor) {
+  return record.key.length > ancestor.key.length && record.key[ancestor.key.length] === 0 && record.key.subarray(0, ancestor.key.length).equals(ancestor.key);
+}
+function recordHeader(record) {
+  const header = Buffer.alloc(RECORD_HEADER_BYTES);
+  header.writeUInt32BE(record.key.length);
+  header[4] = record.kind === "file" ? 1 : 2;
+  return header;
+}
+export {
+  DESCRIPTOR_BYTES,
+  MAX_RECORD_BYTES,
+  MetadataConflictError,
+  RECORD_HEADER_BYTES,
+  compareRecords,
+  decodeRecord,
+  encodeRecord,
+  isDescendant,
+  recordHeader
+};

package/dist/files/metadata/sort.d.ts

@@ -0,0 +1,13 @@
+import type { SandboxDriverSpillFile } from '../../backend/spill.js';
+export interface SpillFiles {
+    data: [SandboxDriverSpillFile, SandboxDriverSpillFile];
+    descriptors: [SandboxDriverSpillFile, SandboxDriverSpillFile];
+}
+export interface SortState {
+    readonly runs: number;
+    readonly end: number;
+    readonly descriptorEnd: number;
+}
+export declare function mergePass(files: SpillFiles, input: SortState, fanIn: number, signal: AbortSignal): Promise<SortState>;
+export declare function validateRun(file: SandboxDriverSpillFile, end: number, signal: AbortSignal): Promise<void>;
+//# sourceMappingURL=sort.d.ts.map

package/dist/files/metadata/sort.js

@@ -0,0 +1,63 @@
+import { compareRecords, decodeRecord, DESCRIPTOR_BYTES, isDescendant, MetadataConflictError } from "./records.js";
+import { address, readDescriptor, readRecord, writeDescriptor, writeRecord } from "./storage.js";
+async function mergePass(files, input, fanIn, signal) {
+  await files.data[1].truncate(0);
+  await files.descriptors[1].truncate(0);
+  let end = 0;
+  let descriptorEnd = 0;
+  let runs = 0;
+  let index = 0;
+  while (index < input.runs) {
+    signal.throwIfAborted();
+    const heads = [];
+    const count = Math.min(fanIn, input.runs - index);
+    for (let item = 0; item < count; item += 1) {
+      const cursor = await readDescriptor(files.descriptors[0], address(index * DESCRIPTOR_BYTES));
+      heads.push({ cursor, record: await readRecord(files.data[0], cursor) });
+      index += 1;
+    }
+    const start = end;
+    for (; ; ) {
+      signal.throwIfAborted();
+      let selected;
+      for (const head2 of heads) {
+        const record = head2.record;
+        if (record && (!selected || compareRecords(record, selected.record) < 0)) selected = { head: head2, record };
+      }
+      if (!selected) break;
+      end = await writeRecord(files.data[1], selected.record, end);
+      const head = selected.head;
+      head.record = void 0;
+      head.record = await readRecord(files.data[0], head.cursor);
+    }
+    descriptorEnd = await writeDescriptor(files.descriptors[1], descriptorEnd, start, end);
+    runs = address(runs + 1);
+  }
+  files.data = [files.data[1], files.data[0]];
+  files.descriptors = [files.descriptors[1], files.descriptors[0]];
+  return { runs, end, descriptorEnd };
+}
+async function validateRun(file, end, signal) {
+  const cursor = { position: 0, end };
+  const ancestors = [];
+  for (; ; ) {
+    signal.throwIfAborted();
+    const record = await readRecord(file, cursor);
+    if (!record) break;
+    const decoded = decodeRecord(record);
+    const previous = ancestors.at(-1);
+    if (previous && compareRecords(previous, record) === 0) throw new MetadataConflictError("duplicate_path", decoded.path);
+    for (; ; ) {
+      const ancestor = ancestors.at(-1);
+      if (!ancestor || isDescendant(record, ancestor)) break;
+      ancestors.pop();
+    }
+    if (ancestors.at(-1)?.kind === "file") throw new MetadataConflictError("file_ancestor", decoded.path);
+    ancestors.push(record);
+  }
+  signal.throwIfAborted();
+}
+export {
+  mergePass,
+  validateRun
+};

package/dist/files/metadata/storage.d.ts

@@ -0,0 +1,12 @@
+import type { SandboxDriverSpillFile } from '../../backend/spill.js';
+import type { EncodedRecord } from './records.js';
+export interface RunCursor {
+    position: number;
+    readonly end: number;
+}
+export declare function address(value: number): number;
+export declare function writeRecord(file: SandboxDriverSpillFile, record: EncodedRecord, position: number): Promise<number>;
+export declare function readRecord(file: SandboxDriverSpillFile, cursor: RunCursor): Promise<EncodedRecord | undefined>;
+export declare function writeDescriptor(file: SandboxDriverSpillFile, position: number, start: number, end: number): Promise<number>;
+export declare function readDescriptor(file: SandboxDriverSpillFile, position: number): Promise<RunCursor>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/files/metadata/storage.js

@@ -0,0 +1,69 @@
+import { Buffer } from "node:buffer";
+import { SANDBOX_LIMITS } from "../../policy/limits.js";
+import { DESCRIPTOR_BYTES, RECORD_HEADER_BYTES, recordHeader } from "./records.js";
+function address(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new RangeError("Spill address exceeds its safe-integer representation.");
+  return value;
+}
+async function writeAll(file, bytes, position) {
+  address(position + bytes.length);
+  let written = 0;
+  while (written < bytes.length) {
+    const remaining = bytes.length - written;
+    const { bytesWritten } = await file.write(bytes, written, remaining, position + written);
+    if (!Number.isSafeInteger(bytesWritten) || bytesWritten <= 0 || bytesWritten > remaining) {
+      throw new Error("Spill write returned an invalid progress receipt.");
+    }
+    written += bytesWritten;
+  }
+  return position + written;
+}
+async function readExact(file, length, position) {
+  address(position + length);
+  const buffer = Buffer.alloc(length);
+  let read = 0;
+  while (read < length) {
+    const remaining = length - read;
+    const { bytesRead } = await file.read(buffer, read, remaining, position + read);
+    if (!Number.isSafeInteger(bytesRead) || bytesRead <= 0 || bytesRead > remaining) {
+      throw new Error("Spill read returned truncated data or an invalid progress receipt.");
+    }
+    read += bytesRead;
+  }
+  return buffer;
+}
+async function writeRecord(file, record, position) {
+  return writeAll(file, record.key, await writeAll(file, recordHeader(record), position));
+}
+async function readRecord(file, cursor) {
+  if (cursor.position === cursor.end) return void 0;
+  if (cursor.end - cursor.position < RECORD_HEADER_BYTES) throw new Error("Spill record header is truncated.");
+  const header = await readExact(file, RECORD_HEADER_BYTES, cursor.position);
+  const length = header.readUInt32BE(0);
+  if (length < 1 || length > SANDBOX_LIMITS.maxPathBytes || header[4] !== 1 && header[4] !== 2 || cursor.end - cursor.position - RECORD_HEADER_BYTES < length) throw new Error("Spill record metadata is invalid.");
+  const key = await readExact(file, length, cursor.position + RECORD_HEADER_BYTES);
+  cursor.position = address(cursor.position + RECORD_HEADER_BYTES + length);
+  return { kind: header[4] === 1 ? "file" : "directory", key };
+}
+async function writeDescriptor(file, position, start, end) {
+  const buffer = Buffer.alloc(DESCRIPTOR_BYTES);
+  buffer.writeBigUInt64BE(BigInt(address(start)));
+  buffer.writeBigUInt64BE(BigInt(address(end)), 8);
+  return writeAll(file, buffer, position);
+}
+async function readDescriptor(file, position) {
+  const buffer = await readExact(file, DESCRIPTOR_BYTES, position);
+  const first = buffer.readBigUInt64BE(0);
+  const last = buffer.readBigUInt64BE(8);
+  if (first > BigInt(Number.MAX_SAFE_INTEGER) || last > BigInt(Number.MAX_SAFE_INTEGER) || last <= first) {
+    throw new Error("Spill run descriptor exceeds its safe address representation.");
+  }
+  return { position: Number(first), end: Number(last) };
+}
+export {
+  address,
+  readDescriptor,
+  readRecord,
+  writeDescriptor,
+  writeRecord
+};

package/dist/files/metadata/types.d.ts

@@ -0,0 +1,19 @@
+import type { SandboxDriverSpillStore } from '../../backend/spill.js';
+import type { SandboxRelativePath } from '../types.js';
+export interface MetadataRecord {
+    readonly path: SandboxRelativePath;
+    readonly kind: 'file' | 'directory';
+}
+export interface MetadataLedgerOptions {
+    readonly openSpill: () => Promise<SandboxDriverSpillStore>;
+    readonly batchBytes: number;
+    readonly fanIn: number;
+    readonly signal?: AbortSignal;
+}
+export interface MetadataLedger {
+    append(record: MetadataRecord): Promise<void>;
+    finish(): Promise<void>;
+    records(): AsyncIterable<MetadataRecord>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map