@poe-platform/safe-bash 0.1.825 → 0.1.827

package/dist/safe-bash/command-chunks/chunk-JADJ4BMN.js

@@ -0,0 +1,1519 @@
+import {
+  createPythonRecordReader,
+  readBackedPythonManifest,
+  withPythonManifestPublication
+} from "./chunk-HS2L7I4N.js";
+import {
+  openPythonPackageFile
+} from "./chunk-UCE77LYV.js";
+
+// packages/safe-bash-command-python/src/manifest-file.ts
+import { jsonValues } from "../../safe-bash-query-engine/input.js";
+import { Budget, resolveJqLimits } from "../../safe-bash-query-engine/limits.js";
+import { compareIdentity, compareFileVersion } from "@poe-platform/safe-fs/core";
+import { FsError } from "../../safe-bash-contracts/index.js";
+import { createBufferedOutput } from "../../safe-bash-contracts/io.js";
+import { resolvePath } from "../../safe-bash-contracts/path.js";
+import { yieldTurn } from "../../safe-bash-contracts/yield.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "../../safe-bash-io-engine/byte-encoding.js";
+
+// packages/safe-bash-command-python/src/manifest.ts
+import { serializeLlmJsonValue } from "../../safe-bash-command-llm/index.js";
+import { toByteSource } from "../../safe-bash-contracts/io.js";
+function readPackageManifest(value) {
+  const strings = (values) => Array.isArray(values) && values.every((item) => typeof item === "string");
+  if (Array.isArray(value)) return strings(value) ? value : void 0;
+  if (!value || typeof value !== "object") return;
+  const record = value, version = record.version;
+  if (![1, 2, 3].includes(version) || Object.keys(value).length !== (version === 1 ? 2 : 3)) return;
+  if (version !== 1 && (!Array.isArray(record.records) || !record.records.every((row) => Array.isArray(row) && row.length === version + 3 && row.every((part, index) => index > 2 && index < 5 ? strings(part) : typeof part === "string" || index === 5 && part === null)))) return;
+  return strings(record.installed) ? record.installed : void 0;
+}
+function createPythonPackageStreamingManifestStore(store) {
+  const publish = async (scope, revision, input, options) => {
+    let consumed = false;
+    const source = (async function* () {
+      let size = 0;
+      for await (const bytes of input) {
+        options.signal.throwIfAborted();
+        size += bytes.length;
+        if (size > options.maxBytes) throw Object.assign(new Error("Python package manifest exceeds maxManifestBytes"), { code: "EPACKAGE" });
+        yield bytes;
+      }
+      consumed = true;
+    })();
+    try {
+      const committed = await store.compareAndSet(scope, revision, source, options);
+      options.signal.throwIfAborted();
+      if (committed === true && !consumed) throw new Error("Python manifest store returned before consuming its source");
+      return committed;
+    } finally {
+      await source.return();
+    }
+  };
+  return {
+    get: store.get.bind(store),
+    compareAndSet(scope, revision, bytes, options) {
+      return store.compareAndSet(scope, revision, toByteSource(bytes), options);
+    },
+    compareAndSetSource: publish,
+    compareAndSetSnapshot(scope, revision, snapshot, options) {
+      return publish(scope, revision, serializeLlmJsonValue(snapshot, options.signal), options);
+    }
+  };
+}
+var PythonPackageConflictError = class extends Error {
+  code = "EPACKAGECONFLICT";
+  retryable = true;
+  constructor() {
+    super("Python package environment changed during installation; retry the command");
+    this.name = "PythonPackageConflictError";
+  }
+};
+function createPythonPackageManifestStore(options = {}) {
+  const maxBytes = options.maxBytes ?? Infinity;
+  const maxEntries = options.maxEntries ?? Infinity;
+  const maxScopeLength = options.maxScopeLength ?? Infinity;
+  for (const [name, value] of Object.entries({ maxBytes, maxEntries, maxScopeLength })) {
+    if (value !== Infinity && (!Number.isSafeInteger(value) || value < 1)) {
+      throw new RangeError(`Python manifest ${name} must be a positive safe integer or Infinity`);
+    }
+  }
+  const manifests = /* @__PURE__ */ new Map();
+  let retainedBytes = 0;
+  let revision = 0n;
+  let disposed = false;
+  const check = (scope, signal) => {
+    signal.throwIfAborted();
+    if (disposed) throw new Error("Python manifest store is disposed");
+    if (typeof scope !== "string" || !scope) throw new TypeError("Invalid Python manifest scope");
+    if (scope.length > maxScopeLength) throw new RangeError("Python manifest scope budget exhausted");
+  };
+  return {
+    async get(scope, { signal }) {
+      check(scope, signal);
+      const value = manifests.get(scope);
+      return value ? { revision: value.revision, bytes: value.bytes.slice() } : void 0;
+    },
+    async compareAndSet(scope, expected, bytes, { signal }) {
+      check(scope, signal);
+      const current = manifests.get(scope);
+      if (current?.revision !== expected) return false;
+      if (!(bytes instanceof Uint8Array)) throw new TypeError("Python manifest must contain bytes");
+      const nextBytes = retainedBytes - (current?.bytes.length ?? 0) + bytes.length;
+      if (nextBytes > maxBytes || !current && manifests.size >= maxEntries) {
+        throw new RangeError("Python manifest store budget exhausted");
+      }
+      manifests.set(scope, { revision: String(++revision), bytes: Uint8Array.from(bytes) });
+      retainedBytes = nextBytes;
+      return true;
+    },
+    dispose() {
+      disposed = true;
+      manifests.clear();
+      retainedBytes = 0;
+    }
+  };
+}
+
+// packages/safe-bash-command-python/src/manifest-file.ts
+function createPythonPackageFileManifestStore({ fs, directory, maxCacheBytes = Infinity, filename }) {
+  if (maxCacheBytes !== Infinity && (!Number.isSafeInteger(maxCacheBytes) || maxCacheBytes < 1)) throw new RangeError("Python manifest maxCacheBytes must be positive");
+  const root = resolvePath("/", directory);
+  const observations = /* @__PURE__ */ new Map();
+  const path = (scope) => {
+    if (typeof scope !== "string" || !scope) throw new TypeError("Invalid Python manifest scope");
+    return resolvePath(root, filename ?? bytesToHex(sha256(new TextEncoder().encode(scope))) + ".json");
+  };
+  async function read(scope, { signal, maxBytes = Infinity }, consume) {
+    signal.throwIfAborted();
+    let stat;
+    try {
+      stat = await fs.lstat(path(scope), { signal });
+    } catch (error) {
+      signal.throwIfAborted();
+      if (error instanceof FsError && error.code === "ENOENT") {
+        observations.delete(scope);
+        return void 0;
+      }
+      throw error;
+    }
+    if (stat.size > maxBytes) throw new Error("Python package manifest exceeds maxManifestBytes");
+    const file = await openPythonPackageFile({ fs, signal, cwd: root }, path(scope), Infinity, stat);
+    if (!file) throw new Error("Python manifests require retained caller reads");
+    try {
+      const value = await consume(file);
+      signal.throwIfAborted();
+      let observed = observations.get(scope);
+      if (!observed || compareIdentity(observed.stat, stat) !== "same" || !compareFileVersion(observed.stat, stat)) observed = { revision: crypto.randomUUID(), stat };
+      observations.set(scope, observed);
+      return { revision: observed.revision, value };
+    } finally {
+      await file.close();
+    }
+  }
+  async function* chunks(file) {
+    for (let offset = 0; offset < file.size; ) {
+      const bytes = await file.read(offset, Math.min(65536, file.size - offset));
+      offset += bytes.length;
+      yield bytes;
+    }
+  }
+  const store = createPythonPackageStreamingManifestStore({
+    async get(scope, options) {
+      const result = await read(scope, options, async (file) => {
+        const bytes = new Uint8Array(file.size);
+        let offset = 0;
+        for await (const chunk of chunks(file)) {
+          bytes.set(chunk, offset);
+          offset += chunk.length;
+        }
+        return bytes;
+      });
+      return result && { revision: result.revision, bytes: result.value };
+    },
+    async compareAndSet(scope, expected, source, { signal }) {
+      signal.throwIfAborted();
+      const filename2 = path(scope), observed = observations.get(scope), settings = { signal };
+      if (observed?.revision !== expected) return false;
+      await fs.mkdir(root, { recursive: true, signal });
+      const caps = await fs.capabilitiesFor?.(root, { signal, create: true }) ?? fs.capabilities;
+      if (!caps.atomicFileStaging || !caps.retainedStagingWrite || !caps.retainedStagingCleanup || !caps.guardedStagingPublication || !fs.createStagedFile || !fs.publishStagedFile || !fs.prepareStagingResolution) throw new Error("Python manifests require guarded retained atomic staging");
+      const resolution = await fs.prepareStagingResolution(filename2, settings);
+      if (observed ? !resolution.destination || compareIdentity(observed.stat, resolution.destination) !== "same" || !compareFileVersion(observed.stat, resolution.destination) : resolution.destination !== null) return false;
+      let stage;
+      for (let attempt = 0; attempt < 16; attempt++) {
+        try {
+          stage = await fs.createStagedFile(resolvePath(root, ".python-manifest-" + crypto.randomUUID()), "snapshot", { type: "file", data: new Uint8Array() }, { parent: resolution.parent, mode: 384, retainCleanup: true, signal });
+          break;
+        } catch (error) {
+          signal.throwIfAborted();
+          if (!(error instanceof FsError) || error.code !== "EEXIST") throw error;
+        }
+      }
+      if (!stage) throw new Error("Python manifest staging names exhausted");
+      const owned = stage;
+      try {
+        if (!owned.writer || !owned.cleanup) throw new Error("Python manifest staging handles missing");
+        const writer = owned.writer;
+        const output = createBufferedOutput({ async write(bytes) {
+          await writer.write(bytes, settings);
+          await yieldTurn(signal);
+        } }, signal, 65536);
+        for await (const bytes of source) await output.write(bytes);
+        await output.flush();
+        const stat = await writer.finish(settings);
+        if (stat.size > maxCacheBytes) throw new RangeError("Python package manifest exceeds maxCacheBytes");
+        try {
+          await fs.publishStagedFile({ ...owned, file: { ...owned.file, stat } }, filename2, { parent: resolution.parent, destination: observed?.stat ?? null, ancestors: resolution.ancestors, commitGuard: resolution.validate, signal });
+        } catch (error) {
+          signal.throwIfAborted();
+          if (error instanceof FsError && ["EAGAIN", "EEXIST"].includes(error.code)) return false;
+          throw error;
+        }
+        if (observations.get(scope) === observed) observations.delete(scope);
+        return true;
+      } finally {
+        try {
+          await owned.cleanup?.remove();
+        } finally {
+          await owned.cleanup?.close();
+        }
+      }
+    }
+  });
+  return { ...store, async openSnapshot(scope, options) {
+    let snapshot;
+    try {
+      const result = await read(scope, options, async (file) => snapshot = await readBackedPythonManifest(fs, root, options.signal, chunks(file)));
+      return result && { ...result.value, revision: result.revision };
+    } catch (error) {
+      await snapshot?.close();
+      throw error;
+    }
+  }, getSnapshot(scope, options) {
+    return read(scope, options, async (file) => {
+      let value;
+      for await (const item of jsonValues(chunks(file), new Budget(resolveJqLimits({ maxInputBytes: options.maxBytes }), options.signal), { profile: "javascript" })) value = item;
+      return value;
+    });
+  } };
+}
+
+// packages/safe-bash-command-python/src/manifest-configured.ts
+import { bytesToHex as bytesToHex2 } from "../../safe-bash-io-engine/byte-encoding.js";
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+import { FsError as FsError2 } from "../../safe-bash-contracts/index.js";
+import { dirname } from "../../safe-bash-contracts/path.js";
+async function createConfiguredPythonManifestStore(context, directory, filename, maxBytes, maxCacheBytes) {
+  const { fs, signal, cwd } = context;
+  let caps;
+  for (let path = directory; ; path = dirname(path)) {
+    try {
+      caps = await fs.capabilitiesFor?.(path, { signal, create: true }) ?? fs.capabilities;
+      break;
+    } catch (error) {
+      if (!(error instanceof FsError2) || error.code !== "ENOENT" || path === "/") throw error;
+    }
+  }
+  const native = caps.atomicFileStaging && caps.retainedStagingWrite && caps.retainedStagingCleanup && caps.guardedStagingPublication && fs.prepareStagingResolution;
+  const root = native ? directory : cwd + "/.python-packages/manifests/" + bytesToHex2(sha2562(new TextEncoder().encode(directory)));
+  const store = createPythonPackageFileManifestStore({ fs, directory: root, filename, ...maxCacheBytes === void 0 ? {} : { maxCacheBytes } });
+  if (!native) {
+    const stat = async (path) => {
+      try {
+        return await fs.lstat(path, { signal });
+      } catch (error) {
+        if (!(error instanceof FsError2) || error.code !== "ENOENT") throw error;
+        return void 0;
+      }
+    };
+    if (await stat(root + "/" + filename)) return store;
+    const legacy = await stat(directory + "/" + filename);
+    if (!legacy) return store;
+    if (legacy.type !== "file" || legacy.size > maxBytes) throw new Error("Invalid legacy Python package manifest");
+    if (!fs.readStream) throw new Error("Legacy Python manifest migration requires streaming reads");
+    await store.compareAndSetSource(filename, void 0, fs.readStream(directory + "/" + filename, { signal }), { signal, maxBytes });
+  }
+  return store;
+}
+
+// packages/safe-bash-command-python/src/provisioning.ts
+import { serializeLlmJsonValue as serializeLlmJsonValue2 } from "../../safe-bash-command-llm/index.js";
+
+// packages/safe-bash-command-python/src/installation-root.ts
+import { compareIdentity as compareIdentity2 } from "@poe-platform/safe-fs/core";
+import { retainFileSystemCleanup } from "@poe-platform/safe-fs/core";
+import { resolvePath as resolvePath2 } from "../../safe-bash-contracts/path.js";
+var serial = 0;
+var PythonInstallationRoot = class {
+  constructor(context) {
+    this.context = context;
+  }
+  context;
+  initializing;
+  closing;
+  cleanup;
+  owned;
+  path(context) {
+    if (this.closing) return Promise.reject(new Error("Python installation root is closed"));
+    const initialized = this.initializing ??= (async () => {
+      const { fs, signal, cwd } = this.context;
+      signal.throwIfAborted();
+      this.cleanup = retainFileSystemCleanup(fs, async (view) => {
+        if (!this.owned) return;
+        const { path, parent: parent2, identity } = this.owned, current = await view.lstat(path);
+        if (compareIdentity2(identity, current) !== "same") throw new Error("Python installation root identity changed");
+        await view.removeTreeConditional(path, { parent: parent2, expected: current });
+        this.owned = void 0;
+      });
+      await fs.mkdir(cwd, { recursive: true, signal });
+      const parentPath = await fs.realpath(cwd, { signal });
+      const parent = await fs.stat(parentPath, { signal });
+      const capabilities = await fs.capabilitiesFor?.(parentPath, { signal }) ?? fs.capabilities;
+      if (!fs.prepareDirectory || !fs.removeTreeConditional || !capabilities.atomicTreeRemoval) throw new Error("Python extracted packages require conditional caller-owned directories");
+      for (let attempt = 0; attempt < 16; attempt++) {
+        const path = resolvePath2(parentPath, ".python-install-" + ++serial);
+        try {
+          const identity = await fs.prepareDirectory(path, { parent, expected: null, mode: 448, signal });
+          this.owned = { path, parent, identity };
+          signal.throwIfAborted();
+          return path;
+        } catch (error) {
+          signal.throwIfAborted();
+          if (!error || typeof error !== "object" || !("code" in error) || !["EEXIST", "EAGAIN"].includes(String(error.code))) throw error;
+        }
+      }
+      throw new Error("Python installation root names exhausted");
+    })();
+    return context ? initialized.then(async (path) => {
+      if (compareIdentity2(this.owned.identity, await context.fs.lstat(path, { signal: context.signal })) !== "same") throw new Error("Python installation root identity changed");
+      return path;
+    }) : initialized;
+  }
+  close() {
+    return this.closing ??= (async () => {
+      await this.initializing?.catch(() => {
+      });
+      await this.cleanup?.();
+    })();
+  }
+};
+
+// packages/safe-bash-command-python/src/manifest-default.ts
+function createDefaultPythonManifestStore(maxCacheBytes) {
+  let root;
+  return {
+    forContext(context) {
+      let store;
+      const writable = () => store ??= (async () => {
+        const owned = root ??= new PythonInstallationRoot(context);
+        let directory;
+        try {
+          directory = await owned.path();
+        } catch (error) {
+          await owned.close();
+          if (root === owned) root = void 0;
+          throw error;
+        }
+        await owned.path(context);
+        return createPythonPackageFileManifestStore({ fs: context.fs, directory, ...maxCacheBytes === void 0 ? {} : { maxCacheBytes } });
+      })();
+      return {
+        async get(scope, options) {
+          return root ? (await writable()).get(scope, options) : void 0;
+        },
+        async openSnapshot(scope, options) {
+          return root ? (await writable()).openSnapshot(scope, options) : void 0;
+        },
+        async getSnapshot(scope, options) {
+          return root ? (await writable()).getSnapshot(scope, options) : void 0;
+        },
+        async compareAndSet(scope, revision, bytes, options) {
+          return (await writable()).compareAndSet(scope, revision, bytes, options);
+        },
+        async compareAndSetSource(scope, revision, source, options) {
+          return (await writable()).compareAndSetSource(scope, revision, source, options);
+        },
+        async compareAndSetSnapshot(scope, revision, snapshot, options) {
+          return (await writable()).compareAndSetSnapshot(scope, revision, snapshot, options);
+        }
+      };
+    },
+    async close() {
+      await root?.close();
+    }
+  };
+}
+
+// packages/safe-bash-command-python/src/provisioning.ts
+import { header } from "../../safe-bash-network-engine/shared.js";
+import { bytesToHex as bytesToHex3 } from "../../safe-bash-io-engine/byte-encoding.js";
+
+// packages/safe-bash-command-python/src/package-index.ts
+import { ArchiveMetadataMap } from "../../safe-bash-io-engine/commands/archive/metadata.js";
+import { createArchiveScratchFactory } from "../../safe-bash-io-engine/commands/archive/scratch.js";
+import { DEFAULT_ARCHIVE_LIMITS } from "../../safe-bash-io-engine/commands/archive/internal.js";
+import { toByteSource as toByteSource2 } from "../../safe-bash-contracts/index.js";
+async function exact(source, offset, length) {
+  const bytes = new Uint8Array(length);
+  for (let position = 0; position < length; ) {
+    const chunk = await source.read(offset + position, Math.min(65536, length - position));
+    if (!chunk.length || chunk.length > length - position) throw new Error("Invalid native ZIP index read");
+    bytes.set(chunk, position);
+    position += chunk.length;
+  }
+  return bytes;
+}
+var PythonPackageIndex = class {
+  #scratch;
+  #spool;
+  #data;
+  #offsets;
+  #dataSource;
+  #offsetSource;
+  #ends;
+  #size = 0;
+  #pages = [];
+  #cached;
+  #names;
+  #headers;
+  #boundaries;
+  #count = 0;
+  #sealed = false;
+  #failed;
+  #tail = Promise.resolve();
+  #closing;
+  #context;
+  #mode;
+  constructor(context, mode = "wheel") {
+    this.#context = context;
+    this.#mode = mode;
+    const discard = { async write() {
+    } };
+    this.#scratch = createArchiveScratchFactory({ context: { ...context, command: "python", args: [], env: {}, stdin: toByteSource2(""), stdout: discard, stderr: discard }, limits: DEFAULT_ARCHIVE_LIMITS, operation: (action) => Promise.resolve().then(action) }, context.cwd);
+    const metadata = this.#spool = async () => {
+      const spool = await this.#scratch();
+      let buffer = new Uint8Array(16384), used = 0;
+      const flush = async () => {
+        if (used) {
+          await spool.append(buffer.subarray(0, used));
+          used = 0;
+        }
+      };
+      return { append: async (bytes) => {
+        if (!buffer) throw new Error("Python wheel scratch is sealed");
+        for (let at = 0; at < bytes.length; ) {
+          const length = Math.min(buffer.length - used, bytes.length - at);
+          buffer.set(bytes.subarray(at, at + length), used);
+          used += length;
+          at += length;
+          if (used === buffer.length) await flush();
+        }
+      }, close: async () => {
+        buffer = void 0;
+        used = 0;
+        await spool.close();
+      }, finish: async () => {
+        await flush();
+        buffer = void 0;
+        const source = await spool.finish();
+        return { size: source.size, read: async (offset, length) => {
+          if (offset >= source.size) return new Uint8Array();
+          const base = Math.floor(offset / 16384) * 16384;
+          const found = this.#pages.findIndex((page2) => page2.source === source && page2.offset === base);
+          const page = found < 0 ? { source, offset: base, bytes: await exact(source, base, Math.min(16384, source.size - base)) } : this.#pages.splice(found, 1)[0];
+          this.#pages.push(page);
+          if (this.#pages.length > 4) this.#pages.shift();
+          return page.bytes.subarray(offset - base, Math.min(page.bytes.length, offset - base + length));
+        } };
+      } };
+    };
+    this.#boundaries = new ArchiveMetadataMap(metadata, context.signal);
+    this.#names = new ArchiveMetadataMap(metadata, context.signal);
+    this.#headers = new ArchiveMetadataMap(metadata, context.signal);
+  }
+  execute(operation, args) {
+    if (this.#closing) return Promise.reject(new Error("Python wheel index is closed"));
+    const work = this.#tail.then(async () => {
+      this.#context.signal.throwIfAborted();
+      if (this.#failed) throw this.#failed.error;
+      if (this.#mode !== "wheel") {
+        const name = args[0];
+        if (operation === "has" && (this.#sealed || this.#mode === "records") && typeof name === "string") return this.#names.has(name);
+        if (operation === "get" && this.#mode === "records" && this.#sealed && typeof name === "string") return await this.#names.get(name) ?? null;
+        if (this.#sealed) throw new Error("Python package names are sealed");
+        if (operation === "add" && typeof name === "string") {
+          const value = this.#mode === "records" ? args[1] : 0;
+          if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid package record ordinal");
+          await this.#names.set(name, value);
+          return null;
+        }
+        if (operation === "seal") {
+          this.#sealed = true;
+          return null;
+        }
+        throw new Error("Invalid Python package name operation");
+      }
+      if (operation === "append") {
+        if (this.#sealed) throw new Error("Python wheel index is sealed");
+        const [name, offset, payload] = args;
+        if (typeof name !== "string" || typeof offset !== "string" || typeof payload !== "string") throw new Error("Invalid native ZIP entry");
+        const header2 = BigInt(offset), ordinal = this.#count++;
+        if (!Number.isSafeInteger(this.#count) || header2 <= -(1n << 128n) || header2 >= 1n << 128n) throw new Error("Invalid native ZIP coordinate");
+        this.#data ??= await this.#spool();
+        this.#offsets ??= await this.#spool();
+        const bytes = new TextEncoder().encode(payload), pointer = new Uint8Array(16), view = new DataView(pointer.buffer);
+        view.setBigUint64(0, BigInt(this.#size), true);
+        view.setBigUint64(8, BigInt(bytes.length), true);
+        for (let at = 0; at < bytes.length; at += 65536) await this.#data.append(bytes.subarray(at, at + 65536));
+        await this.#offsets.append(pointer);
+        this.#size += bytes.length;
+        if (!Number.isSafeInteger(this.#size)) throw new Error("Native ZIP index size overflow");
+        await this.#names.set(name, ordinal);
+        const order = ((1n << 128n) - header2).toString().padStart(40, "0") + ":" + String(Number.MAX_SAFE_INTEGER - ordinal).padStart(16, "0");
+        await this.#headers.set(order, { ordinal, offset });
+        return null;
+      }
+      if (operation === "seal") {
+        if (this.#sealed) throw new Error("Python wheel index is sealed");
+        if (typeof args[0] !== "string") throw new Error("Invalid native ZIP directory offset");
+        let end = args[0];
+        BigInt(end);
+        for await (const [, entry] of this.#headers.sortedEntries()) {
+          await this.#boundaries.set(String(entry.ordinal).padStart(16, "0"), end);
+          end = entry.offset;
+        }
+        const boundaries = await this.#spool();
+        for await (const [, end2] of this.#boundaries.sortedEntries()) {
+          const value = BigInt.asUintN(128, BigInt(end2)), bytes = new Uint8Array(16), view = new DataView(bytes.buffer);
+          view.setBigUint64(0, value & (1n << 64n) - 1n, true);
+          view.setBigUint64(8, value >> 64n, true);
+          await boundaries.append(bytes);
+        }
+        this.#ends = await boundaries.finish();
+        this.#dataSource = await this.#data?.finish();
+        this.#offsetSource = await this.#offsets?.finish();
+        this.#sealed = true;
+        await Promise.all([this.#headers.close(), this.#boundaries.close()]);
+        return null;
+      }
+      if (operation === "get" || operation === "name") {
+        if (!this.#sealed) throw new Error("Python wheel index is not sealed");
+        const ordinal = operation === "name" && typeof args[0] === "string" ? await this.#names.get(args[0]) : args[0];
+        const offset = args[1];
+        if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("Invalid native ZIP response offset");
+        if (ordinal === void 0) return "null".slice(offset, offset + 8192);
+        if (!Number.isSafeInteger(ordinal) || ordinal < 0 || ordinal >= this.#count) throw new Error("Invalid native ZIP entry ordinal");
+        if (this.#cached?.ordinal === ordinal) return this.#cached.response.slice(offset, offset + 8192);
+        const pointer = await exact(this.#offsetSource, ordinal * 16, 16), view = new DataView(pointer.buffer);
+        const payload = new TextDecoder("utf-8", { fatal: true }).decode(await exact(this.#dataSource, Number(view.getBigUint64(0, true)), Number(view.getBigUint64(8, true))));
+        const boundary = await exact(this.#ends, ordinal * 16, 16), endView = new DataView(boundary.buffer);
+        const end = BigInt.asIntN(128, endView.getBigUint64(0, true) | endView.getBigUint64(8, true) << 64n).toString();
+        this.#cached = { ordinal, response: JSON.stringify([payload, end]) };
+        return this.#cached.response.slice(offset, offset + 8192);
+      }
+      throw new Error("Invalid native ZIP index operation");
+    });
+    this.#tail = work.catch((error) => {
+      this.#failed ??= { error };
+    });
+    return work;
+  }
+  close() {
+    return this.#closing ??= this.#tail.then(async () => {
+      this.#cached = void 0;
+      this.#pages.length = 0;
+      const results = await Promise.allSettled([this.#boundaries.close(), this.#names.close(), this.#headers.close()]);
+      try {
+        await this.#scratch.close();
+      } catch (reason) {
+        results.push({ status: "rejected", reason });
+      }
+      const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+      if (errors.length === 1) throw errors[0];
+      if (errors.length) throw new AggregateError(errors, "Python wheel index cleanup failed");
+    });
+  }
+};
+
+// packages/safe-bash-command-python/src/build-wheel.ts
+import { FsError as FsError4 } from "../../safe-bash-contracts/index.js";
+import { resolvePath as resolvePath4, basename } from "../../safe-bash-contracts/path.js";
+
+// packages/safe-bash-command-python/src/package-download.ts
+import { FsError as FsError3 } from "../../safe-bash-contracts/index.js";
+import { resolvePath as resolvePath3 } from "../../safe-bash-contracts/path.js";
+import { interruptible } from "../../safe-bash-contracts/runtime-control.js";
+import { yieldTurn as yieldTurn2 } from "../../safe-bash-contracts/yield.js";
+var serial2 = 0;
+async function stagePythonPackage(context, directory, body, maxBytes, progress, verify, publish) {
+  const { fs, signal } = context, settings = { signal };
+  const caps = await fs.capabilitiesFor?.(directory, settings) ?? fs.capabilities;
+  if (!caps.retainedStagingWrite || !caps.retainedStagingCleanup || !caps.retainedRead || !fs.createStagedFile || !fs.openReadFile || publish && (!caps.atomicFileStaging || !fs.publishStagedFile)) return void 0;
+  const parent = await fs.stat(directory, settings);
+  let stage;
+  for (let attempt = 0; attempt < 16; attempt++) {
+    try {
+      stage = await fs.createStagedFile(resolvePath3(directory, ".python-package-" + ++serial2), "wheel", { type: "file", data: new Uint8Array(0) }, { parent, mode: 384, retainCleanup: true, signal });
+      break;
+    } catch (error) {
+      signal.throwIfAborted();
+      if (!(error instanceof FsError3) || error.code !== "EEXIST") throw error;
+    }
+  }
+  if (!stage) throw new Error("Python package staging names exhausted");
+  const owner = stage;
+  let artifact;
+  let closing;
+  const close = () => closing ??= (async () => {
+    try {
+      await artifact?.close();
+    } finally {
+      try {
+        await owner.cleanup?.remove();
+      } finally {
+        await owner.cleanup?.close();
+      }
+    }
+  })();
+  try {
+    if (!owner.cleanup || !owner.writer) throw new Error("Python package staging handles missing");
+    let count = 0;
+    const iterator = body[Symbol.asyncIterator]();
+    let ended = false;
+    try {
+      while (true) {
+        const next = await interruptible(Promise.resolve().then(() => {
+          signal.throwIfAborted();
+          return iterator.next();
+        }), signal);
+        signal.throwIfAborted();
+        if (next.done) {
+          ended = true;
+          break;
+        }
+        const bytes = next.value;
+        if (!(bytes instanceof Uint8Array)) throw new TypeError("Python package body must yield bytes");
+        if (count + bytes.length > maxBytes) throw new Error("Package download exceeds maxDownloadBytes");
+        for (let offset = 0; offset < bytes.length; offset += 65536) {
+          const chunk = Uint8Array.from(bytes.subarray(offset, offset + 65536));
+          await owner.writer.write(chunk, settings);
+          count += chunk.length;
+          await yieldTurn2(signal);
+        }
+        if (bytes.length) progress?.(count);
+      }
+    } finally {
+      if (!ended) {
+        const returned = Promise.resolve().then(() => iterator.return?.());
+        if (signal.aborted) void returned.catch(() => {
+        });
+        else await interruptible(returned, signal);
+      }
+    }
+    const stat = await owner.writer.finish(settings);
+    if (stat.size !== count) throw new Error("Python package staging size mismatch");
+    artifact = await openPythonPackageFile(context, owner.file.path, maxBytes, stat);
+    if (!artifact) throw new Error("Python package retained reads unavailable");
+    verify?.(artifact.key);
+    if (publish) {
+      const key = artifact.key, path = publish(key);
+      await artifact.close();
+      artifact = void 0;
+      let destination = null;
+      try {
+        destination = await fs.lstat(path, settings);
+      } catch (error) {
+        if (!(error instanceof FsError3) || error.code !== "ENOENT") throw error;
+      }
+      await fs.publishStagedFile({ ...owner, file: { ...owner.file, stat } }, path, { parent, destination, signal });
+      artifact = await openPythonPackageFile(context, path, maxBytes);
+      if (!artifact || artifact.key !== key) throw new Error("Published Python package integrity mismatch");
+    }
+    return { ...artifact, close };
+  } catch (error) {
+    try {
+      await close();
+    } catch (cleanup) {
+      throw new AggregateError([error, cleanup], error instanceof Error ? error.message : "Python package download failed");
+    }
+    throw error;
+  }
+}
+
+// packages/safe-bash-command-python/src/build-wheel.ts
+async function publishPythonBuildWheel(source, directory, maxBytes, context) {
+  const { fs, signal } = context, settings = { signal };
+  let artifact = typeof source === "string" ? void 0 : source.artifact;
+  let reading;
+  try {
+    signal.throwIfAborted();
+    if (maxBytes !== Infinity && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) throw new RangeError("Invalid Python wheel size limit");
+    const filename = typeof source === "string" ? basename(source) : source.filename;
+    if (basename(filename) !== filename || !filename.endsWith(".whl") || filename.includes("\\") || filename.includes("\0")) throw new TypeError("Invalid Python build wheel filename");
+    const root = await fs.realpath(resolvePath4(context.cwd, directory), settings);
+    const caps = await fs.capabilitiesFor?.(root, settings) ?? fs.capabilities;
+    if (!fs.confineExtraction || !fs.prepareDirectory || !caps.retainedStagingWrite || !caps.retainedStagingCleanup || !caps.retainedRead || !caps.atomicFileStaging) throw new Error("Python wheel publication requires confined retained atomic staging");
+    if (typeof source === "string") artifact = await openPythonPackageFile(context, resolvePath4(context.cwd, source), maxBytes);
+    if (!artifact) throw new Error("Python wheel publication requires retained source reads");
+    if (artifact.size > maxBytes) throw new Error("Canonical package exceeds maxDownloadBytes");
+    const retained = artifact;
+    const confined = await fs.confineExtraction([root], settings);
+    const destination = new Proxy(confined, { get(target, key) {
+      const owner = key === "openReadFile" ? fs : target, value = Reflect.get(owner, key);
+      return typeof value === "function" ? value.bind(owner) : value;
+    } });
+    const parent = await destination.stat(root, settings), path = resolvePath4(root, artifact.key);
+    try {
+      await destination.prepareDirectory(path, { parent, expected: null, mode: 448, signal });
+    } catch (error) {
+      if (!(error instanceof FsError4) || !["EEXIST", "EAGAIN"].includes(error.code)) throw error;
+    }
+    if ((await destination.lstat(path, settings)).type !== "directory") throw new Error("Python wheel publication directory changed");
+    const output = resolvePath4(path, filename);
+    const body = async function* () {
+      for (let offset = 0; offset < retained.size; ) {
+        const bytes = await (reading = Promise.resolve(retained.read(offset, Math.min(65536, retained.size - offset))));
+        if (!bytes.length || bytes.length > Math.min(65536, retained.size - offset)) throw new Error("Invalid Python wheel read");
+        offset += bytes.length;
+        yield bytes;
+      }
+    };
+    const published = await stagePythonPackage({ ...context, fs: destination }, path, body(), maxBytes, void 0, (key) => {
+      if (key !== retained.key) throw new Error("Built Python wheel integrity mismatch");
+    }, () => output);
+    if (!published) throw new Error("Python wheel publication requires retained atomic staging");
+    try {
+      return { url: "file://" + output.split("/").map(encodeURIComponent).join("/"), digest: published.key, size: published.size };
+    } finally {
+      await published.close();
+    }
+  } finally {
+    try {
+      await reading?.catch(() => {
+      });
+    } finally {
+      await artifact?.close?.();
+    }
+  }
+}
+
+// packages/safe-bash-command-python/src/provisioning.ts
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+import { resolvePath as resolve, dirname as dirname2, basename as basename2 } from "../../safe-bash-contracts/path.js";
+import { inheritYieldCheckpoint } from "../../safe-bash-contracts/yield.js";
+
+// packages/safe-bash-command-python/src/cache.ts
+var pythonPackageRuntimeKey = "pyodide-314.0.6-cp314-emscripten-wasm32-v1";
+function createPythonPackageCache(options = {}) {
+  const maxBytes = options.maxBytes ?? Infinity;
+  if (options.maxBytes !== void 0 && (!Number.isSafeInteger(maxBytes) || maxBytes < 1)) throw new RangeError("Python cache maxBytes must be a positive integer");
+  const values = /* @__PURE__ */ new Map();
+  const manifestKey = pythonPackageRuntimeKey + "-environment";
+  let retainedBytes = 0;
+  let disposed = false;
+  return {
+    async get(key) {
+      if (disposed) throw new Error("Python package cache is disposed");
+      return values.get(key)?.slice();
+    },
+    async set(key, bytes) {
+      if (disposed) throw new Error("Python package cache is disposed");
+      if (key === manifestKey && bytes.length > maxBytes) throw new RangeError("Python package manifest exceeds maxCacheBytes");
+      const previous = values.get(key);
+      if (previous) {
+        retainedBytes -= previous.length;
+        values.delete(key);
+      }
+      if (bytes.length > maxBytes) return;
+      while (values.size && retainedBytes + bytes.length > maxBytes) {
+        const oldest = [...values.keys()].find((entry) => entry !== manifestKey);
+        if (oldest === void 0) return;
+        retainedBytes -= values.get(oldest).length;
+        values.delete(oldest);
+      }
+      values.set(key, Uint8Array.from(bytes));
+      retainedBytes += bytes.length;
+    },
+    dispose() {
+      disposed = true;
+      values.clear();
+      retainedBytes = 0;
+    }
+  };
+}
+
+// packages/safe-bash-command-python/src/provisioning.ts
+var pythonDocumentPackages = Object.freeze([
+  "lxml==6.0.2",
+  "pillow==12.2.0",
+  "python-docx==1.2.0",
+  "openpyxl==3.1.5",
+  "XlsxWriter==3.2.9",
+  "pypdf==6.18.1",
+  "fpdf2==2.8.8",
+  "fonttools==4.65.0",
+  "defusedxml==0.7.1",
+  "et-xmlfile==2.0.0",
+  "typing-extensions==4.16.0"
+]);
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function digest(value) {
+  return bytesToHex3(sha2563(value));
+}
+function validDigest(value) {
+  if (typeof value !== "string" || value.length !== 64) return false;
+  for (const char of value) if (!"0123456789abcdef".includes(char)) return false;
+  return true;
+}
+function failure(message, cause) {
+  return Object.assign(new Error(message, { cause }), { code: "EPACKAGE" });
+}
+function missing(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function* requirementLines(source) {
+  let start = 0, pending = "";
+  for (let end = 0; end <= source.length; end++) {
+    if (end < source.length && !"\n\r\v\f\x85\u2028\u2029".includes(source[end])) continue;
+    let line = source.slice(start, end);
+    if (source[end] === "\r" && source[end + 1] === "\n") end++;
+    start = end + 1;
+    if (line.trimStart()[0] === "#") line = " " + line;
+    else if (line.endsWith("\\")) {
+      let first = 0, last = line.length;
+      while (line[first] === "\\") first++;
+      while (line[last - 1] === "\\") last--;
+      pending += line.slice(first, last);
+      continue;
+    }
+    yield pending + line;
+    pending = "";
+  }
+  yield pending;
+}
+function expandRequirement(source, env = {}) {
+  let text = source;
+  for (let start = source.indexOf("${"); start >= 0; start = source.indexOf("${", start + 2)) {
+    let end = start + 2;
+    while (end < source.length && "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_".includes(source[end])) end++;
+    if (end === start + 2 || source[end] !== "}") continue;
+    const name = source.slice(start + 2, end), value = Object.hasOwn(env, name) && env[name];
+    if (value) text = text.replaceAll(source.slice(start, end + 1), () => value);
+  }
+  return text;
+}
+function requirementOptions(line) {
+  const tokens = line.split(" "), start = tokens.findIndex((token) => token.startsWith("-"));
+  if (start < 0) return;
+  const requirement = tokens.slice(0, start).join(" ");
+  line = tokens.slice(start).join(" ");
+  if (!["-r", "-c", "-i", "--requirem", "--const", "--index-url", "--extra-index-url", "--no-index", "--pre"].some((prefix) => line.startsWith(prefix))) return;
+  const words = [];
+  let word = "", quote = "", active = false;
+  for (let index = 0; index < line.length; index++) {
+    const char = line[index];
+    if (char === "\\" && quote !== "'") {
+      const next = line[++index];
+      if (next === void 0) throw failure("No escaped character");
+      if (quote && next !== quote && next !== "\\") word += "\\";
+      word += next;
+      active = true;
+    } else if (quote) {
+      if (char === quote) quote = "";
+      else word += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      active = true;
+    } else if (" 	\r\n".includes(char)) {
+      if (active) {
+        words.push(word);
+        word = "";
+        active = false;
+      }
+    } else {
+      word += char;
+      active = true;
+    }
+  }
+  if (quote) throw failure("No closing quotation");
+  if (active) words.push(word);
+  let included, constrained;
+  const options = { extraIndexUrls: [], ...requirement ? { requirement } : {} };
+  for (let index = 0; index < words.length; index++) {
+    const word2 = words[index], option = word2.split("=", 1)[0];
+    if (word2 === "--pre") {
+      options.pre = true;
+      continue;
+    }
+    if (word2 === "--no-index") {
+      options.noIndex = true;
+      continue;
+    }
+    const indexKind = word2.startsWith("-i") || option === "--index-url" ? "indexUrl" : option === "--extra-index-url" ? "extraIndexUrls" : void 0;
+    const kind = indexKind ?? ["requirement", "constraint"].find((name) => word2.startsWith("-" + name[0]) || option.startsWith("--" + name.slice(0, name === "requirement" ? 8 : 5)) && ("--" + name).startsWith(option));
+    if (!kind) {
+      if (word2.startsWith("-")) throw failure(`Unsupported requirement option: ${word2}`);
+      continue;
+    }
+    const path = word2.startsWith("--") ? word2.length === option.length ? words[++index] : word2.slice(option.length + 1) : word2.length === 2 ? words[++index] : word2.slice(2);
+    if (path === void 0) throw failure(`Requirement option needs a file: ${word2}`);
+    if (kind === "requirement") included ??= path;
+    else if (kind === "constraint") constrained ??= path;
+    else if (kind === "indexUrl") options.indexUrl = path;
+    else options.extraIndexUrls.push(path);
+  }
+  return included !== void 0 ? { ...options, include: [included, false] } : constrained !== void 0 ? { ...options, include: [constrained, true] } : options;
+}
+function normalizeRequirement(value, cwd) {
+  const requirement = value.trim();
+  if (!requirement || requirement.startsWith("-")) throw failure(`Unsupported requirement: ${value}`);
+  if (requirement.endsWith(".whl") && !requirement.includes("://")) return "file://" + resolve(cwd, requirement).split("/").map(encodeURIComponent).join("/");
+  return requirement;
+}
+function artifactKey(digest2) {
+  return pythonPackageRuntimeKey + "-sha256-" + digest2;
+}
+function createPythonPackageEnvironment(options = {}) {
+  const { manifestStore } = options;
+  let ownedManifest;
+  if (options.cache && options.cacheDirectory) throw new TypeError("Choose package cache or cacheDirectory, not both");
+  if (manifestStore && (typeof options.scope !== "string" || !options.scope.trim())) throw new TypeError("Shared Python manifests require an explicit nonempty scope");
+  if (options.scope !== void 0 && !manifestStore) throw new TypeError("Python scope requires a manifestStore");
+  const manifestKey = pythonPackageRuntimeKey + "-environment" + (manifestStore ? "-" + digest(encoder.encode(JSON.stringify(options.scope))) : "");
+  if (options.profile !== void 0 && options.profile !== "documents") throw new TypeError("Unknown Python package profile");
+  const maxBytes = options.maxDownloadBytes ?? Infinity;
+  const maxManifestBytes = options.maxManifestBytes ?? Infinity;
+  const maxMetadataBytes = options.maxMetadataBytes ?? Infinity;
+  for (const name of ["maxDownloadBytes", "maxManifestBytes", "maxMetadataBytes", "maxRequirementBytes", "maxCacheBytes"]) {
+    const value = options[name];
+    if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) throw new RangeError(`${name} must be a positive integer`);
+  }
+  const checkManifest = (bytes) => {
+    if (bytes && bytes.length > maxManifestBytes) throw failure("Python package manifest exceeds maxManifestBytes");
+  };
+  const checkMetadata = (bytes) => {
+    if (bytes.length > maxMetadataBytes) throw failure("Python package cache metadata exceeds maxMetadataBytes");
+    return bytes;
+  };
+  const cacheRecord = (key, headers, url) => checkMetadata(encoder.encode(JSON.stringify({ digest: key, headers, url })));
+  const defaultCache = createPythonPackageCache({ maxBytes: options.maxCacheBytes });
+  const sessions = /* @__PURE__ */ new Map();
+  const controller = new AbortController();
+  const pending = /* @__PURE__ */ new Set();
+  let cleanupFailure;
+  const track = (work, cleanup = false) => {
+    pending.add(work);
+    void work.then(() => pending.delete(work), (error) => {
+      if (cleanup) cleanupFailure ??= { error };
+      pending.delete(work);
+    });
+    return work;
+  };
+  function release(session, all = false) {
+    const artifacts = all ? [...session.retained.values()] : [];
+    if (all) {
+      artifacts.push(...Object.values(session.indexes));
+      session.indexes = {};
+    }
+    if (all) {
+      if (session.snapshot) artifacts.push(session.snapshot);
+      session.snapshot = void 0;
+      session.retained.clear();
+      session.records = void 0;
+      if (session.recordReader) artifacts.push(session.recordReader);
+      session.recordReader = void 0;
+    }
+    if (session.closed && session.installationRoot) {
+      artifacts.push(session.installationRoot);
+      session.installationRoot = void 0;
+    }
+    if (session.opened) {
+      artifacts.push(session.opened);
+      session.opened = void 0;
+    }
+    if (!artifacts.length) return session.retiring ?? Promise.resolve();
+    return track(session.retiring = Promise.allSettled([session.retiring, ...artifacts.map((artifact) => Promise.resolve().then(() => artifact.close?.()))]).then((results) => {
+      for (const result of results) if (result.status === "rejected") throw result.reason;
+    }), true);
+  }
+  let disposed = false;
+  let disposing;
+  const admit = (operation) => (...args) => track(Promise.resolve().then(() => {
+    if (disposed) throw failure("Python package environment is disposed");
+    return operation(...args);
+  }));
+  let counter = 0;
+  let committing = Promise.resolve();
+  async function prepare(input) {
+    const invocation = new AbortController();
+    const signal = AbortSignal.any([input.signal, controller.signal, invocation.signal]);
+    inheritYieldCheckpoint(input.signal, signal);
+    const context = { ...input, signal };
+    signal.throwIfAborted();
+    const directory = options.cacheDirectory === void 0 ? void 0 : resolve(context.cwd, options.cacheDirectory, pythonPackageRuntimeKey);
+    const noCache = context.noCache ?? options.noCache ?? false;
+    const artifactDirectory = directory ?? (!options.cache && options.maxCacheBytes === void 0 && !noCache ? resolve(context.cwd, ".python-packages", "cache", pythonPackageRuntimeKey) : void 0);
+    const cache = options.cache ?? (!artifactDirectory ? defaultCache : {
+      async get(key) {
+        try {
+          return await context.fs.readFile(resolve(artifactDirectory, key), { signal });
+        } catch (error) {
+          if (missing(error)) return void 0;
+          throw error;
+        }
+      },
+      async set(key, bytes) {
+        await context.fs.mkdir(artifactDirectory, { recursive: true, signal });
+        await context.fs.writeFile(resolve(artifactDirectory, key), bytes, { signal });
+      }
+    });
+    const store = manifestStore ?? (directory ? await createConfiguredPythonManifestStore(context, directory, manifestKey, maxManifestBytes, options.maxCacheBytes) : (ownedManifest ??= createDefaultPythonManifestStore(options.maxCacheBytes)).forContext(context));
+    const open = input.recordTransport === "host" ? store.openSnapshot : void 0;
+    let backed, adopted = false;
+    try {
+      const structured = open ? void 0 : store.getSnapshot;
+      let snapshot;
+      try {
+        if (open) backed = await open.call(store, manifestKey, { signal, maxBytes: maxManifestBytes });
+        else snapshot = await (structured ? structured.call(store, manifestKey, { signal, maxBytes: maxManifestBytes }) : store.get(manifestKey, context));
+      } catch (error) {
+        signal.throwIfAborted();
+        throw failure("Cannot read Python package environment manifest", error);
+      }
+      signal.throwIfAborted();
+      if (snapshot !== void 0 && (typeof snapshot !== "object" || !snapshot || typeof snapshot.revision !== "string" || !snapshot.revision || snapshot.revision.length > 1024 || !structured && !(snapshot.bytes instanceof Uint8Array))) throw failure("Invalid Python package manifest snapshot");
+      if (backed && (!backed.revision || typeof backed.revision !== "string" || backed.revision.length > 1024 || ![0, 1, 2, 3].includes(backed.version) || !readPackageManifest(backed.installed) || !Number.isSafeInteger(backed.recordCount) || backed.recordCount < -1 || typeof backed.readRecord !== "function" || typeof backed.close !== "function")) throw failure("Invalid Python package manifest snapshot");
+      const manifestRevision = backed?.revision ?? snapshot?.revision;
+      const stored = snapshot?.bytes;
+      signal.throwIfAborted();
+      checkManifest(stored);
+      let previous;
+      try {
+        previous = open ? backed?.installed ?? [] : structured ? snapshot ? snapshot.value : [] : stored === void 0 ? [] : JSON.parse(decoder.decode(stored));
+      } catch {
+      }
+      const saved = readPackageManifest(previous);
+      if (!saved) throw failure("Invalid Python package environment manifest");
+      const legacy = backed ? backed.version === 0 : Array.isArray(previous);
+      const restore = saved.map((value) => normalizeRequirement(value, context.cwd));
+      const requirements = [...options.profile ? pythonDocumentPackages : [], ...options.requirements ?? [], ...context.requirements ?? []].map((value) => normalizeRequirement(value, context.cwd));
+      const constraints = [...options.constraints ?? [], ...context.constraints ?? []];
+      const controls = {};
+      for (const key of ["pre", "upgrade", "forceReinstall", "noDeps"]) if (context[key] ?? options[key]) controls[key] = true;
+      let indexUrls = context.noIndex ?? options.noIndex ? [] : [context.indexUrl ?? options.indexUrl ?? "https://pypi.org/simple", ...context.extraIndexUrls ?? options.extraIndexUrls ?? []];
+      const activeFiles = /* @__PURE__ */ new Set();
+      let requirementBytes = 0;
+      const readRequirements = async (path, constraint = false) => {
+        signal.throwIfAborted();
+        let source, identity;
+        try {
+          identity = await context.fs.realpath(path, { signal });
+          if (activeFiles.has(identity)) throw failure(`Recursive Python requirements: ${path}`);
+          activeFiles.add(identity);
+          const bytes = await context.fs.readFile(path, { signal, ...options.maxRequirementBytes !== void 0 ? { maxBytes: options.maxRequirementBytes - requirementBytes } : {} });
+          requirementBytes += bytes.length;
+          if (requirementBytes > (options.maxRequirementBytes ?? Infinity)) throw failure("Python requirements byte limit exceeded");
+          source = decoder.decode(bytes);
+        } catch (error) {
+          signal.throwIfAborted();
+          throw failure(`Cannot read Python requirements ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        for (const line of requirementLines(source)) {
+          let comment = line.indexOf("#");
+          while (comment > 0 && line[comment - 1].trim()) comment = line.indexOf("#", comment + 1);
+          const text = (comment < 0 ? line : line.slice(0, comment)).trim();
+          if (!text) continue;
+          const expanded = expandRequirement(text, context.env);
+          const parsed = requirementOptions(expanded);
+          if (parsed?.requirement) (constraint ? constraints : requirements).push(normalizeRequirement(parsed.requirement, dirname2(path)));
+          else if (parsed?.include) await readRequirements(resolve(dirname2(path), parsed.include[0]), parsed.include[1]);
+          else if (parsed) {
+            if (parsed.indexUrl) indexUrls = [parsed.indexUrl];
+            if (parsed.noIndex) indexUrls = [];
+            indexUrls.push(...parsed.extraIndexUrls);
+            if (parsed.pre) controls.pre = true;
+          } else (constraint ? constraints : requirements).push(expanded[0] === "-" && options.prepareRequirements ? expanded : normalizeRequirement(expanded, dirname2(path)));
+        }
+        activeFiles.delete(identity);
+      };
+      for (const file of [...options.constraintFiles ?? [], ...context.constraintFiles ?? []]) await readRequirements(resolve(context.cwd, file), true);
+      for (const file of [...options.requirementFiles ?? [], ...context.requirementFiles ?? []]) await readRequirements(resolve(context.cwd, file));
+      if ((options.editable?.length || context.editable?.length) && !options.prepareRequirements) throw failure("Editable packages require a source package environment");
+      const requested = [...new Set(await options.prepareRequirements?.(requirements, { ...context, ...controls, noIndex: indexUrls.length === 0, ...indexUrls.length ? { indexUrl: indexUrls[0], extraIndexUrls: indexUrls.slice(1) } : {} }) ?? requirements)];
+      signal.throwIfAborted();
+      const session = String(++counter);
+      const unique = [.../* @__PURE__ */ new Set([...restore, ...requested])];
+      const aborted = () => {
+        const current = sessions.get(session);
+        if (current) {
+          current.closed = true;
+          void release(current, true);
+        }
+      };
+      const offline = context.offline ?? options.offline ?? false;
+      const records = previous.records;
+      const hostRecords = input.recordTransport === "host";
+      sessions.set(session, { ...context, snapshot: backed, records: hostRecords ? records : void 0, indexes: {}, cacheDirectory: directory, artifactDirectory, noCache, cache, manifestStore: store, manifestRevision, controller: invocation, offline, requirements: unique, opening: false, retained: /* @__PURE__ */ new Map(), closed: false, aborted });
+      signal.addEventListener("abort", aborted, { once: true });
+      adopted = true;
+      return { session, indexUrls, requirements: unique, restore, requested, ...store.compareAndSetSource ? { streamManifest: true } : {}, ...constraints.length ? { constraints: [...new Set(constraints)] } : {}, legacy, ...hostRecords ? { recordCount: backed?.recordCount ?? records?.length ?? -1 } : { records }, ...controls, ...input.uninstall ? { uninstall: input.uninstall } : {}, offline };
+    } finally {
+      if (!adopted) await backed?.close();
+    }
+  }
+  async function dispatch(op, args, _context) {
+    _context.signal.throwIfAborted();
+    const session = sessions.get(String(args[0]));
+    function check() {
+      session?.signal.throwIfAborted();
+      if (!session || session.closed) throw failure("Python package session is closed");
+    }
+    check();
+    const { fs, signal, cwd, cacheDirectory: configuredCache } = session;
+    const settings = { signal };
+    if (op === "package-record-read") {
+      const ordinal = args[1], offset = args[2], field = args[3];
+      if (field !== void 0 && (!Number.isInteger(field) || field < 0 || field > 5) || !Number.isSafeInteger(ordinal) || ordinal < 0 || ordinal >= (session.snapshot?.recordCount ?? session.records?.length ?? 0) || !Number.isSafeInteger(offset) || offset < 0) throw failure("Invalid package record request");
+      if (session.snapshot) {
+        const result2 = await (field === void 0 ? session.snapshot.readRecord(ordinal, offset) : session.snapshot.readField?.(ordinal, field, offset) ?? false);
+        check();
+        return result2;
+      }
+      session.recordReader ??= createPythonRecordReader((key) => {
+        const row = session.records[Math.floor(key / 7)], field2 = key % 7 - 1;
+        return serializeLlmJsonValue2(field2 < 0 ? row.length === 5 ? [...row, null] : row : row[field2] ?? null, signal);
+      });
+      const result = await session.recordReader.read(ordinal * 7 + (field === void 0 ? 0 : field + 1), offset);
+      check();
+      return result;
+    }
+    if (op === "package-commit" || op === "package-commit-file") {
+      await release(session, true);
+      check();
+      const { manifestStore: manifestStore2 } = session;
+      let publish;
+      if (op === "package-commit-file") {
+        const streamed = manifestStore2.compareAndSetSource;
+        if (!streamed || !session.installationRoot) throw failure("Python file publication is unavailable");
+        const cwd2 = await session.installationRoot.path();
+        publish = () => withPythonManifestPublication({ ...session, cwd: cwd2 }, maxManifestBytes, (source) => streamed.call(manifestStore2, manifestKey, session.manifestRevision, source, { signal, maxBytes: maxManifestBytes }));
+      } else {
+        const pinned = args[1], saved = readPackageManifest(pinned);
+        if (!saved) throw failure("Invalid installed package manifest");
+        const state = Array.isArray(pinned) ? [.../* @__PURE__ */ new Set([...session.requirements, ...saved])] : { ...pinned, installed: [...new Set(saved)] };
+        const streamed = manifestStore2.compareAndSetSnapshot, manifestBytes = streamed ? void 0 : encoder.encode(JSON.stringify(state));
+        checkManifest(manifestBytes);
+        publish = () => streamed ? streamed.call(manifestStore2, manifestKey, session.manifestRevision, state, { signal, maxBytes: maxManifestBytes }) : manifestStore2.compareAndSet(manifestKey, session.manifestRevision, manifestBytes, settings);
+      }
+      const commit = committing.then(async () => {
+        check();
+        const committed = await publish();
+        check();
+        if (typeof committed !== "boolean") throw failure("Invalid Python package manifest publication result");
+        if (!committed) throw new PythonPackageConflictError();
+        check();
+      });
+      committing = commit.catch(() => {
+      });
+      await commit;
+      options.onProgress?.({ phase: "installed" });
+      return null;
+    }
+    const root = op === "package-root", prefix = typeof args[1] === "string" ? args[1].split("-", 1)[0] : void 0;
+    const kind = prefix === "names" || prefix === "records" ? prefix : "wheel";
+    const operation = kind === "wheel" ? args[1] : args[1].slice(prefix.length + 1);
+    if (root || op === "package-index" && operation === "start") {
+      if (root && session.installationRoot) return session.installationRoot.path();
+      let directory = configuredCache ? dirname2(configuredCache) : cwd;
+      if (configuredCache) {
+        const caps = await fs.capabilitiesFor?.(directory, { signal, create: true }) ?? fs.capabilities;
+        if (root ? !caps.atomicTreeRemoval : !caps.retainedRead || !caps.retainedStagingWrite || !caps.retainedStagingCleanup) directory = cwd;
+      }
+      check();
+      const storage = { fs, signal, cwd: directory };
+      if (root) return (session.installationRoot ??= new PythonInstallationRoot(storage)).path();
+      if (session.indexes[kind]) throw failure("Python package index already open");
+      session.indexes[kind] = new PythonPackageIndex(storage, kind);
+      return null;
+    }
+    if (op === "package-index") {
+      if (operation === "close") {
+        const index2 = session.indexes[kind];
+        delete session.indexes[kind];
+        await index2?.close();
+        return null;
+      }
+      const index = session.indexes[kind];
+      if (!index) throw failure("Python package index is closed");
+      return index.execute(operation, args.slice(2));
+    }
+    if (op === "package-read" || op === "package-read-retained") {
+      const artifact = op === "package-read" ? session.opened : session.retained.get(String(args[1])), offset = args[2], length = args[3];
+      if (!artifact || op === "package-read" && artifact.key !== String(args[1]) || !Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 1 || length > 65536) throw failure("Invalid package chunk request");
+      const bytes = await artifact.read(offset, length);
+      check();
+      return Array.from(bytes);
+    }
+    if (op === "package-retain") {
+      let artifact = session.opened;
+      if (!artifact || artifact.key !== String(args[1])) throw failure("Invalid package retention request");
+      if (artifact.url && artifact.close) {
+        const source = artifact;
+        const retaining = (async () => {
+          const path = decodeURIComponent(new URL(source.url).pathname);
+          if (!fs.confineExtraction || !fs.prepareDirectory) return;
+          const fallback = resolve(cwd, ".python-packages", "installed");
+          let directory = configuredCache ? resolve(configuredCache, "installed") : fallback, probe = directory;
+          const required = ["retainedStagingWrite", "retainedStagingCleanup", "retainedRead", "atomicFileStaging"];
+          for (; ; ) {
+            try {
+              const capabilities = await fs.capabilitiesFor?.(probe, settings) ?? fs.capabilities;
+              if (required.every((key) => capabilities[key])) break;
+              if (directory === fallback) return;
+              probe = directory = fallback;
+            } catch (error) {
+              check();
+              if (!missing(error) || dirname2(probe) === probe) throw error;
+              probe = dirname2(probe);
+            }
+          }
+          await fs.mkdir(directory, { recursive: true, signal });
+          const target = resolve(directory, source.key, basename2(path));
+          if (path !== target || probe !== directory) {
+            check();
+            session.opened = void 0;
+            const published = await publishPythonBuildWheel({ filename: basename2(path), artifact: source }, directory, maxBytes, session);
+            artifact = await openPythonPackageFile(session, decodeURIComponent(new URL(published.url).pathname), maxBytes);
+            if (!artifact) throw failure("Installed Python wheels require retained reads");
+            if (artifact.key !== published.digest) {
+              await artifact.close?.();
+              throw failure("Installed Python wheel changed");
+            }
+            session.opened = artifact;
+            artifact.url = published.url;
+            try {
+              check();
+            } catch (error) {
+              await release(session);
+              throw error;
+            }
+          }
+          const durable = new URL(artifact.url);
+          durable.hash = "sha256=" + artifact.key;
+          artifact.url = durable.href;
+        })();
+        session.retaining = retaining;
+        try {
+          await retaining;
+        } finally {
+          session.retaining = void 0;
+        }
+      }
+      check();
+      if (!artifact) throw failure("Installed Python wheel unavailable");
+      const token = String(++counter);
+      session.retained.set(token, artifact);
+      session.opened = void 0;
+      return { token, key: artifact.key, size: artifact.size, ...artifact.url ? { url: artifact.url } : {} };
+    }
+    if (op === "package-close") {
+      if (session.opened?.key === String(args[1])) await release(session);
+      return null;
+    }
+    if (op !== "package-open" || typeof args[1] !== "string") throw failure("Invalid package operation");
+    if (session.opening || session.retaining) throw failure("Package download already in progress");
+    session.opening = true;
+    try {
+      await release(session);
+      check();
+      const url = args[1], { artifactDirectory: cacheDirectory, noCache } = session;
+      const expected = args[2];
+      let responseUrl = url;
+      const verifyIntegrity = (key2) => {
+        if (expected && key2 !== expected) throw failure(`Package integrity mismatch: ${url}`);
+      };
+      if (expected !== void 0 && expected !== null && !validDigest(expected)) throw failure("Invalid SHA-256 package integrity value");
+      const address = pythonPackageRuntimeKey + "-url-" + digest(encoder.encode(url));
+      const canonicalWheel = url.startsWith("file:") || url.startsWith("emfs:");
+      const metadata = canonicalWheel || noCache || args[3] === "metadata" && !session.offline ? void 0 : await session.cache.get(address);
+      check();
+      let key = "", bytes;
+      let headers = [];
+      const adopt = async (artifact, ready) => {
+        session.opened = artifact;
+        if (canonicalWheel) artifact.url = url;
+        try {
+          check();
+          await ready();
+          check();
+          return { key: artifact.key, size: artifact.size, headers, url: responseUrl };
+        } catch (error) {
+          await release(session);
+          throw error;
+        }
+      };
+      const openArtifact = async (source) => {
+        const retained = await openPythonPackageFile(session, source, maxBytes);
+        if (retained) return retained;
+        const capabilities = await fs.capabilitiesFor?.(source, settings) ?? fs.capabilities;
+        if (capabilities.streamingRead && fs.readStream) {
+          for (const directory of configuredCache ? [configuredCache, cwd] : [cwd]) {
+            if (directory !== cwd) await fs.mkdir(directory, { recursive: true, signal });
+            const body = (async function* () {
+              yield* fs.readStream(source, settings);
+            })();
+            const staged = await stagePythonPackage(session, directory, body, maxBytes);
+            if (staged) return staged;
+          }
+        }
+      };
+      if (metadata) {
+        checkMetadata(metadata);
+        let record;
+        try {
+          record = JSON.parse(decoder.decode(metadata));
+        } catch {
+        }
+        if (typeof record !== "object" || record === null || !validDigest(record.digest) || record.url !== void 0 && typeof record.url !== "string" || !Array.isArray(record.headers) || record.headers.some((pair) => !Array.isArray(pair) || pair.length !== 2 || pair.some((value2) => typeof value2 !== "string"))) throw failure(`Invalid package cache metadata: ${url}`);
+        headers = record.headers;
+        responseUrl = record.url ?? url;
+        let absent = false;
+        if (cacheDirectory) {
+          let artifact;
+          try {
+            artifact = await openArtifact(resolve(cacheDirectory, artifactKey(record.digest)));
+          } catch (error) {
+            if (!missing(error)) throw error;
+            absent = true;
+          }
+          if (artifact) {
+            return await adopt(artifact, () => {
+              if (artifact.key !== record.digest) throw failure(`Package cache integrity mismatch: ${url}`);
+              verifyIntegrity(artifact.key);
+              options.onProgress?.({ phase: "cached", url, bytes: artifact.size });
+            });
+          }
+        }
+        bytes = absent ? void 0 : await session.cache.get(artifactKey(record.digest));
+        check();
+        if (bytes && bytes.length > maxBytes) throw failure("Cached package exceeds maxDownloadBytes");
+        if (bytes) bytes = Uint8Array.from(bytes);
+        if (bytes && (key = digest(bytes)) !== record.digest) throw failure(`Package cache integrity mismatch: ${url}`);
+        if (bytes) options.onProgress?.({ phase: "cached", url, bytes: bytes.length });
+      }
+      if (!bytes) {
+        if (canonicalWheel) {
+          const path = new URL(url);
+          if (path.host && path.host !== "localhost") throw failure("Local wheels must use the canonical filesystem");
+          try {
+            const source = decodeURIComponent(path.pathname);
+            const artifact = await openArtifact(source);
+            if (artifact) {
+              return await adopt(artifact, () => verifyIntegrity(artifact.key));
+            }
+            bytes = Uint8Array.from(await fs.readFile(source, { signal, ...Number.isFinite(maxBytes) ? { maxBytes } : {} }));
+          } catch (error) {
+            check();
+            throw failure(`Cannot read canonical Python wheel ${path.pathname}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        } else {
+          if (session.offline) throw failure(`Offline package cache miss: ${url}`);
+          if (!options.transport || !options.authorize) throw failure("Python package download requires configured transport and authorization");
+          let current = new URL(url);
+          let redirectFrom;
+          for (let redirect = 0; ; redirect++) {
+            if (current.protocol !== "https:" && current.protocol !== "http:") throw failure(`Unsupported package transport protocol: ${current.protocol}`);
+            if (current.username || current.password) throw failure("Package URLs with credentials are unsupported");
+            let denyPrivate = false;
+            const allowed = await options.authorize({ url: current.href, method: "GET", attempt: 0, signal, ...redirectFrom === void 0 ? {} : { redirectFrom }, requirePrivateNetworkDeny() {
+              denyPrivate = true;
+            } });
+            check();
+            if (!allowed) throw failure(`Python package download authorization denied: ${current.href}`);
+            if (denyPrivate && !options.transport.supportsPrivateNetworkDeny) throw failure("Package transport cannot enforce private network denial");
+            check();
+            const response = await options.transport({ url: current.href, method: "GET", headers: [["accept", "application/vnd.pypi.simple.v1+json, application/json;q=0.9, */*;q=0.1"]], signal, ...denyPrivate ? { denyPrivateNetworks: true } : {} });
+            try {
+              check();
+              if ([301, 302, 303, 307, 308].includes(response.status)) {
+                if (redirect >= 5) throw failure("Too many package redirects");
+                const location = header(response.headers, "location");
+                if (!location) throw failure("Package redirect has no location");
+                redirectFrom = current.href;
+                current = new URL(location, current);
+                continue;
+              }
+              if (response.status < 200 || response.status >= 300) throw failure(`Package download failed: HTTP ${response.status} ${current.href}`);
+              headers = response.headers;
+              responseUrl = current.href;
+              const encoding = header(headers, "content-encoding")?.trim().toLowerCase();
+              const length = header(headers, "content-length");
+              const total = length === void 0 || encoding !== void 0 && encoding !== "identity" ? void 0 : Number(length);
+              if (Number.isFinite(total) && total > maxBytes) throw failure("Package download exceeds maxDownloadBytes");
+              const progress = (count2) => options.onProgress?.({ phase: "download", url, bytes: count2, ...Number.isSafeInteger(total) ? { totalBytes: total } : {} });
+              if (cacheDirectory || noCache) {
+                const directory = cacheDirectory ?? cwd;
+                if (cacheDirectory) await fs.mkdir(directory, { recursive: true, signal });
+                let metadataBytes;
+                const verify = (key2) => {
+                  verifyIntegrity(key2);
+                  if (!noCache) metadataBytes = cacheRecord(key2, headers, responseUrl);
+                };
+                const destination = (key2) => resolve(directory, artifactKey(key2));
+                let artifact = await stagePythonPackage(session, directory, response.body, maxBytes, progress, verify, noCache ? void 0 : destination);
+                let streamed = false;
+                if (!artifact && directory !== cwd && (noCache || fs.writeStream && (await fs.capabilitiesFor?.(directory, settings) ?? fs.capabilities).streamingWrite)) {
+                  artifact = await stagePythonPackage(session, cwd, response.body, maxBytes, progress, verify);
+                  streamed = true;
+                }
+                if (artifact) {
+                  const retained = artifact;
+                  return await adopt(retained, async () => {
+                    if (!noCache) {
+                      if (streamed) await fs.writeStream(destination(retained.key), (async function* () {
+                        for (let offset2 = 0; offset2 < retained.size; ) {
+                          const chunk = await retained.read(offset2, 65536);
+                          offset2 += chunk.length;
+                          yield chunk;
+                        }
+                      })(), settings);
+                      check();
+                      await session.cache.set(address, metadataBytes);
+                    }
+                  });
+                }
+              }
+              const chunks = [];
+              let count = 0;
+              for await (const chunk of response.body) {
+                check();
+                if (chunk.length === 0) continue;
+                count += chunk.length;
+                if (count > maxBytes) throw failure("Package download exceeds maxDownloadBytes");
+                chunks.push(Uint8Array.from(chunk));
+                progress(count);
+              }
+              bytes = new Uint8Array(count);
+              let offset = 0;
+              for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.length;
+              }
+              break;
+            } finally {
+              await response.dispose();
+            }
+          }
+        }
+        check();
+        verifyIntegrity(key = digest(bytes));
+        if (!noCache) {
+          const metadataBytes = cacheRecord(key, headers, responseUrl);
+          await session.cache.set(artifactKey(key), Uint8Array.from(bytes));
+          check();
+          if (!canonicalWheel) await session.cache.set(address, metadataBytes);
+        }
+      }
+      check();
+      verifyIntegrity(key);
+      const value = bytes;
+      session.opened = { key, size: bytes.length, ...canonicalWheel ? { url } : {}, read: (offset, length) => value.subarray(offset, offset + length) };
+      return { key, size: bytes.length, headers, url: responseUrl };
+    } finally {
+      session.opening = false;
+    }
+  }
+  return {
+    prepare: admit(prepare),
+    dispatch: admit(dispatch),
+    finish(start) {
+      const session = sessions.get(start.session);
+      if (session) {
+        session.closed = true;
+        session.signal.removeEventListener("abort", session.aborted);
+        session.controller.abort(failure("Python package session is closed"));
+        sessions.delete(start.session);
+        const retired = release(session, true);
+        return Promise.allSettled([session.retaining, retired]).then(async () => {
+          try {
+            await retired;
+          } finally {
+            await release(session, true);
+          }
+        });
+      }
+    },
+    dispose() {
+      if (!disposing) {
+        disposed = true;
+        controller.abort(failure("Python package environment is disposed"));
+        disposing = Promise.allSettled([...pending]).then(async () => {
+          sessions.clear();
+          defaultCache.dispose();
+          try {
+            await ownedManifest?.close();
+          } catch (error) {
+            cleanupFailure ??= { error };
+          }
+          if (cleanupFailure) throw cleanupFailure.error;
+        });
+      }
+      return disposing;
+    }
+  };
+}
+
+export {
+  createPythonPackageStreamingManifestStore,
+  PythonPackageConflictError,
+  createPythonPackageManifestStore,
+  createPythonPackageFileManifestStore,
+  publishPythonBuildWheel,
+  createPythonPackageCache,
+  pythonDocumentPackages,
+  createPythonPackageEnvironment
+};