disk 0.8.17 → 0.8.19

package/dist/index.cjs

@@ -1,1257 +1,1441 @@
-"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  Archil: () => Archil,
-  ArchilApiError: () => ArchilApiError,
-  ArchilError: () => ArchilError,
-  ArchilS3Error: () => ArchilS3Error,
-  Disk: () => Disk,
-  DiskMultipart: () => DiskMultipart,
-  Disks: () => Disks,
-  Tokens: () => Tokens,
-  USER_AGENT: () => USER_AGENT,
-  VERSION: () => VERSION,
-  configure: () => configure,
-  createApiKey: () => createApiKey,
-  createDisk: () => createDisk,
-  deleteApiKey: () => deleteApiKey,
-  effectiveUploadPartSize: () => effectiveUploadPartSize,
-  exec: () => exec,
-  getDisk: () => getDisk,
-  listApiKeys: () => listApiKeys,
-  listDisks: () => listDisks
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/client.ts
-var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
-
-// src/s3xml.ts
-var import_fast_xml_parser = require("fast-xml-parser");
-var parser = new import_fast_xml_parser.XMLParser({
-  isArray: (name) => name === "Contents" || name === "CommonPrefixes",
-  parseTagValue: false,
-  trimValues: true,
-  ignoreAttributes: true
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_paths = require("./paths-1c4QqbOB.cjs");
+let openapi_fetch = require("openapi-fetch");
+openapi_fetch = __toESM(openapi_fetch, 1);
+//#region src/s3xml.ts
+const parser = new (require("fast-xml-parser")).XMLParser({
+	isArray: (name) => name === "Contents" || name === "CommonPrefixes",
+	parseTagValue: false,
+	trimValues: true,
+	ignoreAttributes: true
 });
+/** Parse an XML document into a plain object. Returns {} for empty/blank input. */
 function parseXml(xml) {
-  if (!xml.trim()) return {};
-  return parser.parse(xml);
+	if (!xml.trim()) return {};
+	return parser.parse(xml);
 }
-
-// src/errors.ts
+//#endregion
+//#region src/errors.ts
+/**
+* Base class for every error the SDK throws. Catch with `instanceof ArchilError`
+* to handle control-plane and S3 failures uniformly; `status` is the HTTP status
+* code and `code` a machine-readable error code when the server provided one.
+*/
 var ArchilError = class extends Error {
-  /** HTTP status code associated with the failure. */
-  status;
-  /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
-  code;
-  constructor(message, status, code) {
-    super(message);
-    this.name = "ArchilError";
-    this.status = status;
-    this.code = code;
-  }
+	/** HTTP status code associated with the failure. */
+	status;
+	/** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
+	code;
+	constructor(message, status, code) {
+		super(message);
+		this.name = "ArchilError";
+		this.status = status;
+		this.code = code;
+	}
 };
+/** Error from the control-plane REST API. */
 var ArchilApiError = class extends ArchilError {
-  constructor(message, status, code) {
-    super(message, status, code);
-    this.name = "ArchilApiError";
-  }
+	constructor(message, status, code) {
+		super(message, status, code);
+		this.name = "ArchilApiError";
+	}
 };
+/**
+* Error from the S3-compatible object API (getObject/putObject/deleteObject/
+* headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
+* this surfaces its parts as structured fields (`status`, `code`, `requestId`)
+* rather than a raw blob, while keeping the full body on `raw` for debugging.
+*/
 var ArchilS3Error = class extends ArchilError {
-  /** S3 request id, if the gateway returned one. */
-  requestId;
-  /** Raw response body (the XML document), for debugging. */
-  raw;
-  constructor(opts) {
-    const detail = opts.message ?? opts.statusText ?? "";
-    const codePart = opts.code ? ` ${opts.code}` : "";
-    super(
-      `S3 ${opts.operation} failed: ${opts.statusCode}${codePart}${detail ? ` \u2014 ${detail}` : ""}`,
-      opts.statusCode,
-      opts.code
-    );
-    this.name = "ArchilS3Error";
-    this.requestId = opts.requestId;
-    this.raw = opts.raw;
-  }
+	/** S3 request id, if the gateway returned one. */
+	requestId;
+	/** Raw response body (the XML document), for debugging. */
+	raw;
+	constructor(opts) {
+		const detail = opts.message ?? opts.statusText ?? "";
+		const codePart = opts.code ? ` ${opts.code}` : "";
+		super(`S3 ${opts.operation} failed: ${opts.statusCode}${codePart}${detail ? ` — ${detail}` : ""}`, opts.statusCode, opts.code);
+		this.name = "ArchilS3Error";
+		this.requestId = opts.requestId;
+		this.raw = opts.raw;
+	}
 };
 function tagString(obj, tag) {
-  const value = obj[tag];
-  return value === void 0 || value === null ? void 0 : String(value);
+	const value = obj[tag];
+	return value === void 0 || value === null ? void 0 : String(value);
 }
+/** Build an ArchilS3Error from a failed S3 response, parsing the XML body. */
 function parseS3Error(operation, statusCode, statusText, body) {
-  let err = {};
-  try {
-    err = parseXml(body).Error ?? {};
-  } catch {
-    err = {};
-  }
-  return new ArchilS3Error({
-    operation,
-    statusCode,
-    statusText,
-    code: tagString(err, "Code"),
-    message: tagString(err, "Message"),
-    requestId: tagString(err, "RequestId"),
-    raw: body
-  });
+	let err = {};
+	try {
+		err = parseXml(body).Error ?? {};
+	} catch {
+		err = {};
+	}
+	return new ArchilS3Error({
+		operation,
+		statusCode,
+		statusText,
+		code: tagString(err, "Code"),
+		message: tagString(err, "Message"),
+		requestId: tagString(err, "RequestId"),
+		raw: body
+	});
 }
-
-// src/regions.ts
-var REGION_URLS = {
-  "aws-us-east-1": "https://control.green.us-east-1.aws.prod.archil.com",
-  "aws-us-west-2": "https://control.green.us-west-2.aws.prod.archil.com",
-  "aws-eu-west-1": "https://control.green.eu-west-1.aws.prod.archil.com",
-  "gcp-us-central1": "https://control.blue.us-central1.gcp.prod.archil.com"
+//#endregion
+//#region src/regions.ts
+const REGION_URLS = {
+	"aws-us-east-1": "https://control.green.us-east-1.aws.prod.archil.com",
+	"aws-us-west-2": "https://control.green.us-west-2.aws.prod.archil.com",
+	"aws-eu-west-1": "https://control.green.eu-west-1.aws.prod.archil.com",
+	"gcp-us-central1": "https://control.blue.us-central1.gcp.prod.archil.com"
 };
 function resolveBaseUrl(region) {
-  const url = REGION_URLS[region];
-  if (!url) {
-    throw new Error(
-      `Unknown region "${region}". Valid regions: ${Object.keys(REGION_URLS).join(", ")}`
-    );
-  }
-  return url;
+	const url = REGION_URLS[region];
+	if (!url) throw new Error(`Unknown region "${region}". Valid regions: ${Object.keys(REGION_URLS).join(", ")}`);
+	return url;
 }
+/**
+* Derive the S3-compatible endpoint from a control-plane base URL by swapping a
+* leading `control.` hostname segment for `s3.` (e.g.
+* `control.green.us-east-1.…` → `s3.green.us-east-1.…`). Returns undefined if the
+* URL can't be parsed. A host without a `control.` prefix is returned unchanged.
+*/
 function deriveS3BaseUrl(controlBaseUrl) {
-  try {
-    const u = new URL(controlBaseUrl);
-    u.hostname = u.hostname.replace(/^control\./, "s3.");
-    return u.toString().replace(/\/$/, "");
-  } catch {
-    return void 0;
-  }
+	try {
+		const u = new URL(controlBaseUrl);
+		u.hostname = u.hostname.replace(/^control\./, "s3.");
+		return u.toString().replace(/\/$/, "");
+	} catch {
+		return;
+	}
 }
-
-// src/version.ts
-var VERSION = true ? "0.8.17" : "0.0.0-dev";
-var USER_AGENT = `archil-js/${VERSION}`;
-
-// src/client.ts
-var createClient = typeof import_openapi_fetch.default === "function" ? import_openapi_fetch.default : import_openapi_fetch.default.default;
+//#endregion
+//#region src/version.ts
+const VERSION = "0.8.19";
+const USER_AGENT = `archil-js/${VERSION}`;
+//#endregion
+//#region src/client.ts
+const createClient = typeof openapi_fetch.default === "function" ? openapi_fetch.default : openapi_fetch.default.default;
 function createApiClient(opts) {
-  const baseUrl = opts.baseUrl ?? resolveBaseUrl(opts.region);
-  return createClient({
-    baseUrl,
-    headers: {
-      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`,
-      // Identifies the JS SDK (and its version) to the control plane. Honored
-      // by Node's fetch; browsers treat User-Agent as a forbidden header and
-      // drop it, which is fine — the SDK's primary use is server-side.
-      "User-Agent": USER_AGENT
-    }
-  });
+	const baseUrl = opts.baseUrl ?? resolveBaseUrl(opts.region);
+	return createClient({
+		baseUrl,
+		headers: {
+			Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`,
+			"User-Agent": USER_AGENT
+		}
+	});
 }
+/**
+* Unwrap the API envelope: return data on success, throw ArchilApiError on failure.
+*/
 async function unwrap(promise) {
-  const { data: body, error, response } = await promise;
-  if (error || !body) {
-    const errBody = error;
-    throw new ArchilApiError(
-      errBody?.error ?? `API request failed with status ${response.status}`,
-      response.status
-    );
-  }
-  if (!body.success) {
-    throw new ArchilApiError(
-      body.error ?? "Unknown API error",
-      response.status
-    );
-  }
-  return body.data;
+	const { data: body, error, response } = await promise;
+	if (error || !body) throw new ArchilApiError(error?.error ?? `API request failed with status ${response.status}`, response.status);
+	if (!body.success) throw new ArchilApiError(body.error ?? "Unknown API error", response.status);
+	return body.data;
 }
+/**
+* Unwrap an API response that has no data payload (e.g., delete operations).
+*/
 async function unwrapEmpty(promise) {
-  const { data: body, error, response } = await promise;
-  if (error || !body) {
-    const errBody = error;
-    throw new ArchilApiError(
-      errBody?.error ?? `API request failed with status ${response.status}`,
-      response.status
-    );
-  }
-  if (!body.success) {
-    throw new ArchilApiError(
-      body.error ?? "Unknown API error",
-      response.status
-    );
-  }
+	const { data: body, error, response } = await promise;
+	if (error || !body) throw new ArchilApiError(error?.error ?? `API request failed with status ${response.status}`, response.status);
+	if (!body.success) throw new ArchilApiError(body.error ?? "Unknown API error", response.status);
 }
-
-// src/disk.ts
+//#endregion
+//#region src/disk.ts
 var Disk = class {
-  id;
-  name;
-  organization;
-  status;
-  provider;
-  region;
-  createdAt;
-  fsHandlerStatus;
-  lastAccessed;
-  dataSize;
-  monthlyUsage;
-  mounts;
-  metrics;
-  connectedClients;
-  authorizedUsers;
-  allowedIps;
-  /** @internal */
-  _client;
-  /** @internal */
-  _archilRegion;
-  /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
-  _s3BaseUrl;
-  /** Lazily-constructed multipart namespace (see {@link multipart}). @internal */
-  _multipart;
-  /** @internal */
-  constructor(data, client, archilRegion, s3BaseUrl) {
-    this.id = data.id;
-    this.name = data.name;
-    this.organization = data.organization;
-    this.status = data.status;
-    this.provider = data.provider;
-    this.region = data.region;
-    this.createdAt = data.createdAt;
-    this.fsHandlerStatus = data.fsHandlerStatus;
-    this.lastAccessed = data.lastAccessed;
-    this.dataSize = data.dataSize;
-    this.monthlyUsage = data.monthlyUsage;
-    this.mounts = data.mounts;
-    this.metrics = data.metrics;
-    this.connectedClients = data.connectedClients;
-    this.authorizedUsers = data.authorizedUsers;
-    this.allowedIps = data.allowedIps;
-    this._client = client;
-    this._archilRegion = archilRegion;
-    this._s3BaseUrl = s3BaseUrl ?? "";
-  }
-  toJSON() {
-    return {
-      id: this.id,
-      name: this.name,
-      organization: this.organization,
-      status: this.status,
-      provider: this.provider,
-      region: this.region,
-      createdAt: this.createdAt,
-      fsHandlerStatus: this.fsHandlerStatus,
-      lastAccessed: this.lastAccessed,
-      dataSize: this.dataSize,
-      monthlyUsage: this.monthlyUsage,
-      mounts: this.mounts,
-      metrics: this.metrics,
-      connectedClients: this.connectedClients,
-      authorizedUsers: this.authorizedUsers,
-      allowedIps: this.allowedIps
-    };
-  }
-  async addUser(user) {
-    return unwrap(
-      this._client.POST("/api/disks/{id}/users", {
-        params: { path: { id: this.id } },
-        body: user
-      })
-    );
-  }
-  async removeUser(userType, identifier) {
-    await unwrapEmpty(
-      this._client.DELETE("/api/disks/{id}/users/{userType}", {
-        params: {
-          path: { id: this.id, userType },
-          query: { identifier }
-        }
-      })
-    );
-  }
-  async createToken(nickname) {
-    const user = await unwrap(
-      this._client.POST("/api/disks/{id}/users", {
-        params: { path: { id: this.id } },
-        body: { type: "token", nickname }
-      })
-    );
-    if (!user.token || !user.identifier) {
-      throw new Error("Server did not return a generated token");
-    }
-    return user;
-  }
-  async removeTokenUser(identifier) {
-    await this.removeUser("token", identifier);
-  }
-  async getAllowedIPs() {
-    const data = await unwrap(
-      this._client.GET("/api/disks/{id}/allowed-ips", {
-        params: { path: { id: this.id } }
-      })
-    );
-    return data.allowedIps;
-  }
-  async setAllowedIPs(allowedIps) {
-    const data = await unwrap(
-      this._client.PUT("/api/disks/{id}/allowed-ips", {
-        params: { path: { id: this.id } },
-        body: { allowedIps }
-      })
-    );
-    return data.allowedIps;
-  }
-  async addAllowedIP(ip) {
-    const current = await this.getAllowedIPs();
-    if (current.includes(ip)) return current;
-    return this.setAllowedIPs([...current, ip]);
-  }
-  async removeAllowedIP(ip) {
-    const current = await this.getAllowedIPs();
-    return this.setAllowedIPs(current.filter((i) => i !== ip));
-  }
-  async delete() {
-    await unwrapEmpty(
-      this._client.DELETE("/api/disks/{id}", {
-        params: { path: { id: this.id } }
-      })
-    );
-  }
-  /**
-   * Execute a command in a container with this disk mounted.
-   * Blocks until the command completes and returns stdout, stderr, and exit code.
-   */
-  async exec(command) {
-    return unwrap(
-      this._client.POST("/api/disks/{id}/exec", {
-        params: { path: { id: this.id } },
-        body: { command }
-      })
-    );
-  }
-  /**
-   * Constant-time parallel grep across files on this disk. Listing and
-   * matching are fanned out across ephemeral exec containers; the request
-   * finishes within the supplied time budget regardless of dataset size.
-   *
-   * The returned `stoppedReason` says whether the search ran to completion
-   * or short-circuited on `maxResults` / `maxDurationSeconds`. When
-   * stopping early, the matches returned are a sample (whichever workers
-   * reported first), not the lexicographically first N.
-   */
-  async grep(opts) {
-    return unwrap(
-      this._client.POST("/api/disks/{id}/grep", {
-        params: { path: { id: this.id } },
-        body: {
-          directory: opts.directory,
-          pattern: opts.pattern,
-          recursive: opts.recursive ?? false,
-          maxDurationSeconds: opts.maxDurationSeconds ?? 30,
-          concurrency: opts.concurrency ?? 50,
-          maxResults: opts.maxResults ?? 1e3
-        }
-      })
-    );
-  }
-  /**
-   * Create a signed, time-limited URL that lets anyone download a single file
-   * from this disk without authentication. The returned URL embeds a
-   * cryptographically signed token carrying the disk, the file's key, and an
-   * expiry — share it directly; no API key is needed to redeem it.
-   *
-   * @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
-   * @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
-   *              integer, max 604800 = 7 days). Defaults to 24h.
-   */
-  async share(key, opts = {}) {
-    const body = { key };
-    if (opts.expiresIn !== void 0) body.expiresIn = opts.expiresIn;
-    const call = this._client.POST;
-    return unwrap(call(`/api/disks/${this.id}/share`, { body }));
-  }
-  /**
-   * Read an object from the disk via the S3-compatible GetObject API and return
-   * its full contents as bytes. Throws `ArchilS3Error` if the object does not
-   * exist (status 404, code "NoSuchKey") or the request is rejected; use
-   * `headObject`/`objectExists` to check existence without throwing.
-   *
-   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
-   */
-  async getObject(key) {
-    const resp = await this._s3Request("GET", key);
-    if (!resp.ok) {
-      throw parseS3Error("GetObject", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return resp.body;
-  }
-  /**
-   * Fetch an object's metadata (size, etag, content type, last-modified) without
-   * downloading its contents, via the S3-compatible HeadObject API. Returns
-   * `null` if the object does not exist.
-   *
-   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
-   */
-  async headObject(key) {
-    const resp = await this._s3Request("HEAD", key);
-    if (resp.status === 404) return null;
-    if (!resp.ok) {
-      throw parseS3Error("HeadObject", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    const lastModified = resp.headers.get("last-modified");
-    return {
-      size: Number(resp.headers.get("content-length") ?? 0),
-      etag: resp.headers.get("etag") ?? void 0,
-      contentType: resp.headers.get("content-type") ?? void 0,
-      lastModified: lastModified ? new Date(lastModified) : void 0
-    };
-  }
-  /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
-  async objectExists(key) {
-    return await this.headObject(key) !== null;
-  }
-  /**
-   * Write an object to the disk via the S3-compatible API. Handles any size:
-   * bodies at or below `multipartThreshold` (defaults to `partSize`, i.e.
-   * 16 MiB) go through a single PutObject request; larger bodies are uploaded as
-   * a multipart upload — split into `partSize` parts, uploaded with bounded
-   * `concurrency` (default 4), and assembled. A failed part aborts the upload so
-   * nothing is left half-staged. For manual control over the multipart
-   * lifecycle, use the {@link multipart} namespace.
-   *
-   * Faster than exec for large files — no container overhead, no command-length
-   * limits. Returns the entity tag the server assigned (a multipart upload's tag
-   * is S3's `md5(concat(partMd5s))-N` form rather than a plain MD5).
-   *
-   * @param key      Path on the disk (e.g. "reports/2026-01/data.json")
-   * @param body     Contents as a string, Uint8Array/Buffer, or ArrayBuffer
-   * @param options  Either a content-type string, or {@link PutObjectOptions}
-   *                 (`contentType`, `multipartThreshold`, `partSize`,
-   *                 `concurrency`). Content type defaults to
-   *                 "application/octet-stream".
-   */
-  async putObject(key, body, options) {
-    const opts = typeof options === "string" ? { contentType: options } : options ?? {};
-    const contentType = opts.contentType ?? "application/octet-stream";
-    const partSize = Math.max(opts.partSize ?? DEFAULT_PART_SIZE, MIN_PART_SIZE);
-    const threshold = opts.multipartThreshold ?? partSize;
-    const bytes = toBytes(body);
-    if (bytes.length <= threshold) {
-      const resp = await this._s3Request("PUT", key, { body, contentType });
-      if (!resp.ok) {
-        throw parseS3Error("PutObject", resp.status, resp.statusText, decodeText(resp.body));
-      }
-      return { etag: resp.headers.get("etag") ?? void 0 };
-    }
-    return this._putMultipart(
-      key,
-      bytes,
-      contentType,
-      partSize,
-      Math.max(1, opts.concurrency ?? DEFAULT_UPLOAD_CONCURRENCY)
-    );
-  }
-  /**
-   * Upload a large body through the multipart lifecycle: split into `partSize`
-   * parts, upload them with bounded concurrency, then complete — aborting the
-   * upload if any part fails so nothing is left half-staged. @internal
-   */
-  async _putMultipart(key, bytes, contentType, partSize, concurrency) {
-    const effectivePartSize = effectiveUploadPartSize(bytes.length, partSize);
-    const mp = this.multipart;
-    const upload = await mp.create(key, contentType);
-    try {
-      const partCount = Math.ceil(bytes.length / effectivePartSize);
-      const parts = new Array(partCount);
-      let next = 0;
-      const worker = async () => {
-        for (; ; ) {
-          const index = next++;
-          if (index >= partCount) return;
-          const start = index * effectivePartSize;
-          const slice = bytes.subarray(start, Math.min(start + effectivePartSize, bytes.length));
-          parts[index] = await mp.uploadPart(key, upload.uploadId, index + 1, slice);
-        }
-      };
-      await Promise.all(Array.from({ length: Math.min(concurrency, partCount) }, worker));
-      const done = await mp.complete(key, upload.uploadId, parts);
-      return { etag: done.etag };
-    } catch (err) {
-      await mp.abort(key, upload.uploadId).catch(() => {
-      });
-      throw err;
-    }
-  }
-  /**
-   * Append bytes to an object via the S3-compatible PutObject append extension
-   * (`?append=true`). If the object already exists the bytes are appended to it;
-   * if it doesn't, it is created. Returns the entity tag of the full object
-   * after the append.
-   *
-   * Each call may append at most 1 MiB — the server rejects a larger body with
-   * `EntityTooLarge`. To grow an object past that, append in chunks (or use
-   * {@link putObject} for a one-shot large write).
-   *
-   * Unlike most operations this is NOT auto-retried on a transient error:
-   * append isn't idempotent, so retrying a succeeded-but-unacknowledged append
-   * would duplicate the bytes. On a transient failure, re-append yourself only
-   * after confirming the object's size.
-   *
-   * @param key          Path on the disk (e.g. "logs/app.log")
-   * @param body         Bytes to append (string, Uint8Array/Buffer, or ArrayBuffer)
-   * @param contentType  MIME type, applied only when the object is newly created.
-   */
-  async appendObject(key, body, contentType = "application/octet-stream") {
-    const resp = await this._s3Request("PUT", key, {
-      body,
-      contentType,
-      query: { append: "true" },
-      retry: false
-    });
-    if (!resp.ok) {
-      throw parseS3Error("AppendObject", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return { etag: resp.headers.get("etag") ?? void 0 };
-  }
-  /**
-   * Delete an object from the disk via the S3-compatible DeleteObject API.
-   * Idempotent: deleting a key that doesn't exist resolves successfully, per
-   * S3 semantics.
-   *
-   * @param key  Path on the disk (e.g. "project/dist/server.cjs")
-   */
-  async deleteObject(key) {
-    const resp = await this._s3Request("DELETE", key);
-    if (!resp.ok && resp.status !== 404) {
-      throw parseS3Error("DeleteObject", resp.status, resp.statusText, decodeText(resp.body));
-    }
-  }
-  /**
-   * List objects on the disk via the S3-compatible ListObjectsV2 API. By
-   * default this follows continuation tokens until the listing is exhausted and
-   * returns every matching key. Use `limit` to cap the total, `singlePage` for a
-   * single request, or {@link listObjectsPages} to stream pages without loading
-   * everything into memory.
-   *
-   * @param prefix  Only return keys beginning with this prefix (omit for all).
-   * @param opts    Listing and pagination options.
-   */
-  async listObjects(prefix, opts = {}) {
-    if (opts.singlePage) {
-      return this._listObjectsPage(prefix, opts);
-    }
-    const objects = [];
-    const commonPrefixes = [];
-    const seenPrefixes = /* @__PURE__ */ new Set();
-    let echoedPrefix;
-    let truncated = false;
-    outer: for await (const page of this.listObjectsPages(prefix, opts)) {
-      echoedPrefix = page.prefix;
-      for (const cp of page.commonPrefixes) {
-        if (!seenPrefixes.has(cp)) {
-          seenPrefixes.add(cp);
-          commonPrefixes.push(cp);
-        }
-      }
-      for (const obj of page.objects) {
-        if (opts.limit !== void 0 && objects.length >= opts.limit) {
-          truncated = true;
-          break outer;
-        }
-        objects.push(obj);
-      }
-    }
-    return { objects, commonPrefixes, isTruncated: truncated, keyCount: objects.length, prefix: echoedPrefix };
-  }
-  /**
-   * Yield ListObjectsV2 pages lazily, following continuation tokens. A
-   * memory-friendly way to process a large listing without materializing it:
-   *
-   * ```ts
-   * for await (const page of disk.listObjectsPages("logs/")) {
-   *   for (const obj of page.objects) process(obj);
-   * }
-   * ```
-   *
-   * @param prefix  Only return keys beginning with this prefix (omit for all).
-   * @param opts    Listing options (`limit` / `singlePage` are ignored here —
-   *                control your own loop).
-   */
-  async *listObjectsPages(prefix, opts = {}) {
-    const seenTokens = /* @__PURE__ */ new Set();
-    let continuationToken = opts.continuationToken;
-    for (; ; ) {
-      const page = await this._listObjectsPage(prefix, { ...opts, continuationToken });
-      yield page;
-      const next = page.isTruncated ? page.nextContinuationToken : void 0;
-      if (!next || seenTokens.has(next)) break;
-      seenTokens.add(next);
-      continuationToken = next;
-    }
-  }
-  /** Fetch a single ListObjectsV2 page. @internal */
-  async _listObjectsPage(prefix, opts) {
-    const query = { "list-type": 2 };
-    if (prefix !== void 0) query.prefix = prefix;
-    if (!opts.recursive) query.delimiter = "/";
-    if (opts.continuationToken !== void 0) query["continuation-token"] = opts.continuationToken;
-    if (opts.startAfter !== void 0) query["start-after"] = opts.startAfter;
-    const resp = await this._s3Request("GET", "", { query });
-    if (!resp.ok) {
-      throw parseS3Error("ListObjectsV2", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return parseListObjectsResult(decodeText(resp.body));
-  }
-  /**
-   * Delete up to many objects in a single S3-compatible DeleteObjects request.
-   * Unlike {@link deleteObject}, failures are reported per key rather than
-   * thrown: the result's `deleted` lists the keys that were removed and
-   * `errors` lists the ones that weren't (with the server's code/message). A
-   * key that didn't exist still counts as deleted, per S3 semantics.
-   *
-   * The server caps a single request at 1000 keys; this method transparently
-   * splits larger inputs into 1000-key batches and merges the results.
-   *
-   * @param keys  Object keys to delete.
-   * @param opts  `quiet` suppresses the per-key success list server-side.
-   */
-  async deleteObjects(keys, opts = {}) {
-    const deleted = [];
-    const errors = [];
-    for (let i = 0; i < keys.length; i += MAX_DELETE_OBJECTS_PER_REQUEST) {
-      const batch = keys.slice(i, i + MAX_DELETE_OBJECTS_PER_REQUEST);
-      const xml = buildDeleteObjectsXml(batch, opts.quiet ?? false);
-      const resp = await this._s3Request("POST", "", {
-        query: { delete: "" },
-        body: xml,
-        contentType: "application/xml"
-      });
-      if (!resp.ok) {
-        throw parseS3Error("DeleteObjects", resp.status, resp.statusText, decodeText(resp.body));
-      }
-      const parsed = parseDeleteObjectsResult(decodeText(resp.body));
-      deleted.push(...parsed.deleted);
-      errors.push(...parsed.errors);
-    }
-    return { deleted, errors };
-  }
-  /**
-   * The advanced, opt-in multipart-upload API. Drive the raw lifecycle
-   * yourself — `create` → `uploadPart` → `complete` (or `abort`), plus
-   * `listParts` / `listUploads`. Most callers don't need this: {@link putObject}
-   * runs the whole lifecycle automatically for large bodies. Reach for it only
-   * when you need manual control (e.g. uploading parts from separate processes),
-   * and note you then own part-size, memory, and concurrency management.
-   */
-  get multipart() {
-    return this._multipart ??= new DiskMultipart(this.id, this._s3Request.bind(this));
-  }
-  /**
-   * Send a single request to the disk's S3-compatible endpoint. This reuses the
-   * control-plane client purely for its credential and transport — the same
-   * `Authorization` header is sent and verified by the same code server-side —
-   * pointed at the S3 host. Returns the response status and fully-buffered body
-   * so callers can inspect both regardless of the verb used.
-   *
-   * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
-   * are not part of the typed control-plane API, so the path and per-request
-   * options are passed untyped. An empty `key` targets the bucket itself (used
-   * by listObjects).
-   *
-   * @internal
-   */
-  async _s3Request(method, key, opts = {}) {
-    if (!this._s3BaseUrl) {
-      throw new Error(
-        "S3 base URL not configured. Pass s3BaseUrl to new Archil({...}) or set ARCHIL_S3_BASE_URL."
-      );
-    }
-    const call = this._client[method];
-    const trimmedKey = key.replace(/^\//, "");
-    const encodedKey = trimmedKey.split("/").map(encodeURIComponent).join("/");
-    const path = encodedKey ? `/${this.id}/${encodedKey}` : `/${this.id}`;
-    const init = {
-      baseUrl: this._s3BaseUrl,
-      parseAs: "stream",
-      ...opts.query ? { params: { query: opts.query } } : {},
-      // fetch accepts string / Uint8Array / ArrayBuffer bodies directly; pass it
-      // through unchanged (no Node Buffer in the data path). Bodies are fully
-      // buffered (never streams), so re-sending one on a retry is safe.
-      ...opts.body !== void 0 ? { body: opts.body, bodySerializer: (b) => b } : {},
-      ...opts.contentType ? { headers: { "Content-Type": opts.contentType } } : {}
-    };
-    const hasBody = method === "GET" || method === "POST";
-    const maxRetries = opts.retry === false ? 0 : MAX_S3_RETRIES;
-    for (let attempt = 0; ; attempt++) {
-      let error;
-      let response;
-      try {
-        ({ error, response } = await call(path, init));
-      } catch (transportError) {
-        if (attempt < maxRetries) {
-          await sleep(s3RetryDelayMs(attempt));
-          continue;
-        }
-        throw transportError;
-      }
-      if (!response.ok) {
-        if (isTransientS3Status(response.status) && attempt < maxRetries) {
-          await response.body?.cancel().catch(() => {
-          });
-          await sleep(s3RetryDelayMs(attempt));
-          continue;
-        }
-        const message = typeof error === "string" ? error : error ? JSON.stringify(error) : "";
-        return {
-          ok: false,
-          status: response.status,
-          statusText: response.statusText,
-          headers: response.headers,
-          body: new TextEncoder().encode(message)
-        };
-      }
-      const bytes = hasBody ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array(0);
-      return {
-        ok: true,
-        status: response.status,
-        statusText: response.statusText,
-        headers: response.headers,
-        body: bytes
-      };
-    }
-  }
-  /**
-   * Connect to this disk's data plane via the native ArchilClient.
-   *
-   * Requires the native module to be available (platform-specific .node binary).
-   */
-  async mount(opts) {
-    let ArchilClient;
-    try {
-      const nativeSpecifier = "@archildata/native";
-      const native = await import(nativeSpecifier);
-      ArchilClient = native.ArchilClient ?? native.default?.ArchilClient;
-      if (!ArchilClient) {
-        throw new Error("@archildata/native did not export ArchilClient");
-      }
-    } catch {
-      throw new Error(
-        "Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly. mount() is not supported in browsers."
-      );
-    }
-    return ArchilClient.connect({
-      region: this._archilRegion,
-      diskName: `${this.organization}/${this.name}`,
-      authToken: opts?.authToken,
-      logLevel: opts?.logLevel,
-      serverAddress: opts?.serverAddress,
-      insecure: opts?.insecure
-    });
-  }
+	id;
+	name;
+	organization;
+	status;
+	provider;
+	region;
+	createdAt;
+	fsHandlerStatus;
+	lastAccessed;
+	dataSize;
+	monthlyUsage;
+	mounts;
+	metrics;
+	connectedClients;
+	authorizedUsers;
+	allowedIps;
+	/** @internal */
+	_client;
+	/** @internal */
+	_archilRegion;
+	/** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
+	_s3BaseUrl;
+	/** Lazily-constructed multipart namespace (see {@link multipart}). @internal */
+	_multipart;
+	/** @internal */
+	constructor(data, client, archilRegion, s3BaseUrl) {
+		this.id = data.id;
+		this.name = data.name;
+		this.organization = data.organization;
+		this.status = data.status;
+		this.provider = data.provider;
+		this.region = data.region;
+		this.createdAt = data.createdAt;
+		this.fsHandlerStatus = data.fsHandlerStatus;
+		this.lastAccessed = data.lastAccessed;
+		this.dataSize = data.dataSize;
+		this.monthlyUsage = data.monthlyUsage;
+		this.mounts = data.mounts;
+		this.metrics = data.metrics;
+		this.connectedClients = data.connectedClients;
+		this.authorizedUsers = data.authorizedUsers;
+		this.allowedIps = data.allowedIps;
+		this._client = client;
+		this._archilRegion = archilRegion;
+		this._s3BaseUrl = s3BaseUrl ?? "";
+	}
+	toJSON() {
+		return {
+			id: this.id,
+			name: this.name,
+			organization: this.organization,
+			status: this.status,
+			provider: this.provider,
+			region: this.region,
+			createdAt: this.createdAt,
+			fsHandlerStatus: this.fsHandlerStatus,
+			lastAccessed: this.lastAccessed,
+			dataSize: this.dataSize,
+			monthlyUsage: this.monthlyUsage,
+			mounts: this.mounts,
+			metrics: this.metrics,
+			connectedClients: this.connectedClients,
+			authorizedUsers: this.authorizedUsers,
+			allowedIps: this.allowedIps
+		};
+	}
+	async addUser(user) {
+		return unwrap(this._client.POST("/api/disks/{id}/users", {
+			params: { path: { id: this.id } },
+			body: user
+		}));
+	}
+	async removeUser(userType, identifier) {
+		await unwrapEmpty(this._client.DELETE("/api/disks/{id}/users/{userType}", { params: {
+			path: {
+				id: this.id,
+				userType
+			},
+			query: { identifier }
+		} }));
+	}
+	async createToken(nickname) {
+		const user = await unwrap(this._client.POST("/api/disks/{id}/users", {
+			params: { path: { id: this.id } },
+			body: {
+				type: "token",
+				nickname
+			}
+		}));
+		if (!user.token || !user.identifier) throw new Error("Server did not return a generated token");
+		return user;
+	}
+	async removeTokenUser(identifier) {
+		await this.removeUser("token", identifier);
+	}
+	async getAllowedIPs() {
+		return (await unwrap(this._client.GET("/api/disks/{id}/allowed-ips", { params: { path: { id: this.id } } }))).allowedIps;
+	}
+	async setAllowedIPs(allowedIps) {
+		return (await unwrap(this._client.PUT("/api/disks/{id}/allowed-ips", {
+			params: { path: { id: this.id } },
+			body: { allowedIps }
+		}))).allowedIps;
+	}
+	async addAllowedIP(ip) {
+		const current = await this.getAllowedIPs();
+		if (current.includes(ip)) return current;
+		return this.setAllowedIPs([...current, ip]);
+	}
+	async removeAllowedIP(ip) {
+		const current = await this.getAllowedIPs();
+		return this.setAllowedIPs(current.filter((i) => i !== ip));
+	}
+	async delete() {
+		await unwrapEmpty(this._client.DELETE("/api/disks/{id}", { params: { path: { id: this.id } } }));
+	}
+	/**
+	* Execute a command in a container with this disk mounted.
+	* Blocks until the command completes and returns stdout, stderr, and exit code.
+	*/
+	async exec(command) {
+		return unwrap(this._client.POST("/api/disks/{id}/exec", {
+			params: { path: { id: this.id } },
+			body: { command }
+		}));
+	}
+	/**
+	* Constant-time parallel grep across files on this disk. Listing and
+	* matching are fanned out across ephemeral exec containers; the request
+	* finishes within the supplied time budget regardless of dataset size.
+	*
+	* The returned `stoppedReason` says whether the search ran to completion
+	* or short-circuited on `maxResults` / `maxDurationSeconds`. When
+	* stopping early, the matches returned are a sample (whichever workers
+	* reported first), not the lexicographically first N.
+	*/
+	async grep(opts) {
+		return unwrap(this._client.POST("/api/disks/{id}/grep", {
+			params: { path: { id: this.id } },
+			body: {
+				directory: opts.directory,
+				pattern: opts.pattern,
+				recursive: opts.recursive ?? false,
+				maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+				concurrency: opts.concurrency ?? 50,
+				maxResults: opts.maxResults ?? 1e3
+			}
+		}));
+	}
+	/**
+	* Create a signed, time-limited URL that lets anyone download a single file
+	* from this disk without authentication. The returned URL embeds a
+	* cryptographically signed token carrying the disk, the file's key, and an
+	* expiry — share it directly; no API key is needed to redeem it.
+	*
+	* @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
+	* @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
+	*              integer, max 604800 = 7 days). Defaults to 24h.
+	*/
+	async share(key, opts = {}) {
+		const body = { key };
+		if (opts.expiresIn !== void 0) body.expiresIn = opts.expiresIn;
+		const call = this._client.POST;
+		return unwrap(call(`/api/disks/${this.id}/share`, { body }));
+	}
+	/**
+	* Read an object from the disk via the S3-compatible GetObject API and return
+	* its full contents as bytes. Throws `ArchilS3Error` if the object does not
+	* exist (status 404, code "NoSuchKey") or the request is rejected; use
+	* `headObject`/`objectExists` to check existence without throwing.
+	*
+	* @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+	*/
+	async getObject(key) {
+		const resp = await this._s3Request("GET", key);
+		if (!resp.ok) throw parseS3Error("GetObject", resp.status, resp.statusText, decodeText(resp.body));
+		return resp.body;
+	}
+	/**
+	* Fetch an object's metadata (size, etag, content type, last-modified) without
+	* downloading its contents, via the S3-compatible HeadObject API. Returns
+	* `null` if the object does not exist.
+	*
+	* @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+	*/
+	async headObject(key) {
+		const resp = await this._s3Request("HEAD", key);
+		if (resp.status === 404) return null;
+		if (!resp.ok) throw parseS3Error("HeadObject", resp.status, resp.statusText, decodeText(resp.body));
+		const lastModified = resp.headers.get("last-modified");
+		return {
+			size: Number(resp.headers.get("content-length") ?? 0),
+			etag: resp.headers.get("etag") ?? void 0,
+			contentType: resp.headers.get("content-type") ?? void 0,
+			lastModified: lastModified ? new Date(lastModified) : void 0
+		};
+	}
+	/** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
+	async objectExists(key) {
+		return await this.headObject(key) !== null;
+	}
+	/**
+	* Write an object to the disk via the S3-compatible API. Handles any size:
+	* bodies at or below `multipartThreshold` (defaults to `partSize`, i.e.
+	* 16 MiB) go through a single PutObject request; larger bodies are uploaded as
+	* a multipart upload — split into `partSize` parts, uploaded with bounded
+	* `concurrency` (default 4), and assembled. A failed part aborts the upload so
+	* nothing is left half-staged. For manual control over the multipart
+	* lifecycle, use the {@link multipart} namespace.
+	*
+	* Faster than exec for large files — no container overhead, no command-length
+	* limits. Returns the entity tag the server assigned (a multipart upload's tag
+	* is S3's `md5(concat(partMd5s))-N` form rather than a plain MD5).
+	*
+	* @param key      Path on the disk (e.g. "reports/2026-01/data.json")
+	* @param body     Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+	* @param options  Either a content-type string, or {@link PutObjectOptions}
+	*                 (`contentType`, `multipartThreshold`, `partSize`,
+	*                 `concurrency`). Content type defaults to
+	*                 "application/octet-stream".
+	*/
+	async putObject(key, body, options) {
+		const opts = typeof options === "string" ? { contentType: options } : options ?? {};
+		const contentType = opts.contentType ?? "application/octet-stream";
+		const partSize = Math.max(opts.partSize ?? DEFAULT_PART_SIZE, MIN_PART_SIZE);
+		const threshold = opts.multipartThreshold ?? partSize;
+		const bytes = toBytes(body);
+		if (bytes.length <= threshold) {
+			const resp = await this._s3Request("PUT", key, {
+				body,
+				contentType
+			});
+			if (!resp.ok) throw parseS3Error("PutObject", resp.status, resp.statusText, decodeText(resp.body));
+			return { etag: resp.headers.get("etag") ?? void 0 };
+		}
+		return this._putMultipart(key, bytes, contentType, partSize, Math.max(1, opts.concurrency ?? DEFAULT_UPLOAD_CONCURRENCY));
+	}
+	/**
+	* Upload a large body through the multipart lifecycle: split into `partSize`
+	* parts, upload them with bounded concurrency, then complete — aborting the
+	* upload if any part fails so nothing is left half-staged. @internal
+	*/
+	async _putMultipart(key, bytes, contentType, partSize, concurrency) {
+		const effectivePartSize = effectiveUploadPartSize(bytes.length, partSize);
+		const mp = this.multipart;
+		const upload = await mp.create(key, contentType);
+		try {
+			const partCount = Math.ceil(bytes.length / effectivePartSize);
+			const parts = new Array(partCount);
+			let next = 0;
+			const worker = async () => {
+				for (;;) {
+					const index = next++;
+					if (index >= partCount) return;
+					const start = index * effectivePartSize;
+					const slice = bytes.subarray(start, Math.min(start + effectivePartSize, bytes.length));
+					parts[index] = await mp.uploadPart(key, upload.uploadId, index + 1, slice);
+				}
+			};
+			await Promise.all(Array.from({ length: Math.min(concurrency, partCount) }, worker));
+			return { etag: (await mp.complete(key, upload.uploadId, parts)).etag };
+		} catch (err) {
+			await mp.abort(key, upload.uploadId).catch(() => {});
+			throw err;
+		}
+	}
+	/**
+	* Append bytes to an object via the S3-compatible PutObject append extension
+	* (`?append=true`). If the object already exists the bytes are appended to it;
+	* if it doesn't, it is created. Returns the entity tag of the full object
+	* after the append.
+	*
+	* Each call may append at most 1 MiB — the server rejects a larger body with
+	* `EntityTooLarge`. To grow an object past that, append in chunks (or use
+	* {@link putObject} for a one-shot large write).
+	*
+	* Unlike most operations this is NOT auto-retried on a transient error:
+	* append isn't idempotent, so retrying a succeeded-but-unacknowledged append
+	* would duplicate the bytes. On a transient failure, re-append yourself only
+	* after confirming the object's size.
+	*
+	* @param key          Path on the disk (e.g. "logs/app.log")
+	* @param body         Bytes to append (string, Uint8Array/Buffer, or ArrayBuffer)
+	* @param contentType  MIME type, applied only when the object is newly created.
+	*/
+	async appendObject(key, body, contentType = "application/octet-stream") {
+		const resp = await this._s3Request("PUT", key, {
+			body,
+			contentType,
+			query: { append: "true" },
+			retry: false
+		});
+		if (!resp.ok) throw parseS3Error("AppendObject", resp.status, resp.statusText, decodeText(resp.body));
+		return { etag: resp.headers.get("etag") ?? void 0 };
+	}
+	/**
+	* Delete an object from the disk via the S3-compatible DeleteObject API.
+	* Idempotent: deleting a key that doesn't exist resolves successfully, per
+	* S3 semantics.
+	*
+	* @param key  Path on the disk (e.g. "project/dist/server.cjs")
+	*/
+	async deleteObject(key) {
+		const resp = await this._s3Request("DELETE", key);
+		if (!resp.ok && resp.status !== 404) throw parseS3Error("DeleteObject", resp.status, resp.statusText, decodeText(resp.body));
+	}
+	/**
+	* List objects on the disk via the S3-compatible ListObjectsV2 API. By
+	* default this follows continuation tokens until the listing is exhausted and
+	* returns every matching key. Use `limit` to cap the total, `singlePage` for a
+	* single request, or {@link listObjectsPages} to stream pages without loading
+	* everything into memory.
+	*
+	* @param prefix  Only return keys beginning with this prefix (omit for all).
+	* @param opts    Listing and pagination options.
+	*/
+	async listObjects(prefix, opts = {}) {
+		if (opts.singlePage) return this._listObjectsPage(prefix, opts);
+		const objects = [];
+		const commonPrefixes = [];
+		const seenPrefixes = /* @__PURE__ */ new Set();
+		let echoedPrefix;
+		let truncated = false;
+		outer: for await (const page of this.listObjectsPages(prefix, opts)) {
+			echoedPrefix = page.prefix;
+			for (const cp of page.commonPrefixes) if (!seenPrefixes.has(cp)) {
+				seenPrefixes.add(cp);
+				commonPrefixes.push(cp);
+			}
+			for (const obj of page.objects) {
+				if (opts.limit !== void 0 && objects.length >= opts.limit) {
+					truncated = true;
+					break outer;
+				}
+				objects.push(obj);
+			}
+		}
+		return {
+			objects,
+			commonPrefixes,
+			isTruncated: truncated,
+			keyCount: objects.length,
+			prefix: echoedPrefix
+		};
+	}
+	/**
+	* Yield ListObjectsV2 pages lazily, following continuation tokens. A
+	* memory-friendly way to process a large listing without materializing it:
+	*
+	* ```ts
+	* for await (const page of disk.listObjectsPages("logs/")) {
+	*   for (const obj of page.objects) process(obj);
+	* }
+	* ```
+	*
+	* @param prefix  Only return keys beginning with this prefix (omit for all).
+	* @param opts    Listing options (`limit` / `singlePage` are ignored here —
+	*                control your own loop).
+	*/
+	async *listObjectsPages(prefix, opts = {}) {
+		const seenTokens = /* @__PURE__ */ new Set();
+		let continuationToken = opts.continuationToken;
+		for (;;) {
+			const page = await this._listObjectsPage(prefix, {
+				...opts,
+				continuationToken
+			});
+			yield page;
+			const next = page.isTruncated ? page.nextContinuationToken : void 0;
+			if (!next || seenTokens.has(next)) break;
+			seenTokens.add(next);
+			continuationToken = next;
+		}
+	}
+	/** Fetch a single ListObjectsV2 page. @internal */
+	async _listObjectsPage(prefix, opts) {
+		const query = { "list-type": 2 };
+		if (prefix !== void 0) query.prefix = prefix;
+		if (!opts.recursive) query.delimiter = "/";
+		if (opts.continuationToken !== void 0) query["continuation-token"] = opts.continuationToken;
+		if (opts.startAfter !== void 0) query["start-after"] = opts.startAfter;
+		const resp = await this._s3Request("GET", "", { query });
+		if (!resp.ok) throw parseS3Error("ListObjectsV2", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListObjectsResult(decodeText(resp.body));
+	}
+	/**
+	* Delete up to many objects in a single S3-compatible DeleteObjects request.
+	* Unlike {@link deleteObject}, failures are reported per key rather than
+	* thrown: the result's `deleted` lists the keys that were removed and
+	* `errors` lists the ones that weren't (with the server's code/message). A
+	* key that didn't exist still counts as deleted, per S3 semantics.
+	*
+	* The server caps a single request at 1000 keys; this method transparently
+	* splits larger inputs into 1000-key batches and merges the results.
+	*
+	* @param keys  Object keys to delete.
+	* @param opts  `quiet` suppresses the per-key success list server-side.
+	*/
+	async deleteObjects(keys, opts = {}) {
+		const deleted = [];
+		const errors = [];
+		for (let i = 0; i < keys.length; i += MAX_DELETE_OBJECTS_PER_REQUEST) {
+			const xml = buildDeleteObjectsXml(keys.slice(i, i + MAX_DELETE_OBJECTS_PER_REQUEST), opts.quiet ?? false);
+			const resp = await this._s3Request("POST", "", {
+				query: { delete: "" },
+				body: xml,
+				contentType: "application/xml"
+			});
+			if (!resp.ok) throw parseS3Error("DeleteObjects", resp.status, resp.statusText, decodeText(resp.body));
+			const parsed = parseDeleteObjectsResult(decodeText(resp.body));
+			deleted.push(...parsed.deleted);
+			errors.push(...parsed.errors);
+		}
+		return {
+			deleted,
+			errors
+		};
+	}
+	/**
+	* The advanced, opt-in multipart-upload API. Drive the raw lifecycle
+	* yourself — `create` → `uploadPart` → `complete` (or `abort`), plus
+	* `listParts` / `listUploads`. Most callers don't need this: {@link putObject}
+	* runs the whole lifecycle automatically for large bodies. Reach for it only
+	* when you need manual control (e.g. uploading parts from separate processes),
+	* and note you then own part-size, memory, and concurrency management.
+	*/
+	get multipart() {
+		return this._multipart ??= new DiskMultipart(this.id, this._s3Request.bind(this));
+	}
+	/**
+	* Send a single request to the disk's S3-compatible endpoint. This reuses the
+	* control-plane client purely for its credential and transport — the same
+	* `Authorization` header is sent and verified by the same code server-side —
+	* pointed at the S3 host. Returns the response status and fully-buffered body
+	* so callers can inspect both regardless of the verb used.
+	*
+	* The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
+	* are not part of the typed control-plane API, so the path and per-request
+	* options are passed untyped. An empty `key` targets the bucket itself (used
+	* by listObjects).
+	*
+	* @internal
+	*/
+	async _s3Request(method, key, opts = {}) {
+		if (!this._s3BaseUrl) throw new Error("S3 base URL not configured. Pass s3BaseUrl to new Archil({...}) or set ARCHIL_S3_BASE_URL.");
+		const call = this._client[method];
+		const encodedKey = key.replace(/^\//, "").split("/").map(encodeURIComponent).join("/");
+		const path = encodedKey ? `/${this.id}/${encodedKey}` : `/${this.id}`;
+		const init = {
+			baseUrl: this._s3BaseUrl,
+			parseAs: "stream",
+			...opts.query ? { params: { query: opts.query } } : {},
+			...opts.body !== void 0 ? {
+				body: opts.body,
+				bodySerializer: (b) => b
+			} : {},
+			...opts.contentType ? { headers: { "Content-Type": opts.contentType } } : {}
+		};
+		const hasBody = method === "GET" || method === "POST";
+		const maxRetries = opts.retry === false ? 0 : MAX_S3_RETRIES;
+		for (let attempt = 0;; attempt++) {
+			let error;
+			let response;
+			try {
+				({error, response} = await call(path, init));
+			} catch (transportError) {
+				if (attempt < maxRetries) {
+					await sleep(s3RetryDelayMs(attempt));
+					continue;
+				}
+				throw transportError;
+			}
+			if (!response.ok) {
+				if (isTransientS3Status(response.status) && attempt < maxRetries) {
+					await response.body?.cancel().catch(() => {});
+					await sleep(s3RetryDelayMs(attempt));
+					continue;
+				}
+				const message = typeof error === "string" ? error : error ? JSON.stringify(error) : "";
+				return {
+					ok: false,
+					status: response.status,
+					statusText: response.statusText,
+					headers: response.headers,
+					body: new TextEncoder().encode(message)
+				};
+			}
+			const bytes = hasBody ? new Uint8Array(await response.arrayBuffer()) : /* @__PURE__ */ new Uint8Array(0);
+			return {
+				ok: true,
+				status: response.status,
+				statusText: response.statusText,
+				headers: response.headers,
+				body: bytes
+			};
+		}
+	}
+	/**
+	* Connect to this disk's data plane via the native ArchilClient.
+	*
+	* Requires the native module to be available (platform-specific .node binary).
+	*/
+	async mount(opts) {
+		let ArchilClient;
+		try {
+			const native = await import("@archildata/native");
+			ArchilClient = native.ArchilClient ?? native.default?.ArchilClient;
+			if (!ArchilClient) throw new Error("@archildata/native did not export ArchilClient");
+		} catch {
+			throw new Error("Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly. mount() is not supported in browsers.");
+		}
+		return ArchilClient.connect({
+			region: this._archilRegion,
+			diskName: `${this.organization}/${this.name}`,
+			authToken: opts?.authToken,
+			logLevel: opts?.logLevel,
+			serverAddress: opts?.serverAddress,
+			insecure: opts?.insecure
+		});
+	}
 };
+/**
+* The advanced, opt-in multipart-upload namespace, reached via {@link Disk.multipart}.
+* Drives the raw S3 multipart lifecycle — `create` → `uploadPart` → `complete`
+* (or `abort`), plus `listParts` / `listUploads`. Prefer {@link Disk.putObject},
+* which runs this lifecycle automatically for large bodies; use this only when
+* you need manual control, in which case you own part-size, memory, and
+* concurrency management.
+*/
 var DiskMultipart = class {
-  /** @internal */
-  constructor(diskId, s3Request) {
-    this.diskId = diskId;
-    this.s3Request = s3Request;
-  }
-  diskId;
-  s3Request;
-  /**
-   * Start a multipart upload (CreateMultipartUpload) and return its `uploadId`.
-   *
-   * @param key          Path on the disk the finished object will live at.
-   * @param contentType  MIME type to store the object with.
-   */
-  async create(key, contentType) {
-    const resp = await this.s3Request("POST", key, { query: { uploads: "" }, contentType });
-    if (!resp.ok) {
-      throw parseS3Error("CreateMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    const root = parseXml(decodeText(resp.body)).InitiateMultipartUploadResult ?? {};
-    const uploadId = optionalString(root.UploadId);
-    if (!uploadId) {
-      throw new ArchilS3Error({
-        operation: "CreateMultipartUpload",
-        statusCode: resp.status,
-        message: "response did not contain an UploadId",
-        raw: decodeText(resp.body)
-      });
-    }
-    return {
-      uploadId,
-      key: optionalString(root.Key) ?? key,
-      bucket: optionalString(root.Bucket) ?? this.diskId
-    };
-  }
-  /**
-   * Upload one part (UploadPart) and return its entity tag, which you must
-   * collect (with its part number) and pass to {@link complete}. Every part
-   * except the last must be at least 5 MiB.
-   *
-   * @param key         The upload's object key.
-   * @param uploadId    The id from {@link create}.
-   * @param partNumber  1-based part number (1..=10000).
-   * @param body        Part contents as a string, Uint8Array/Buffer, or ArrayBuffer.
-   */
-  async uploadPart(key, uploadId, partNumber, body) {
-    const resp = await this.s3Request("PUT", key, { query: { uploadId, partNumber }, body });
-    if (!resp.ok) {
-      throw parseS3Error("UploadPart", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return { partNumber, etag: resp.headers.get("etag") ?? "" };
-  }
-  /**
-   * Finish a multipart upload (CompleteMultipartUpload), assembling the listed
-   * parts into one object. Parts are sorted by part number before submission
-   * (the server requires strictly-increasing order).
-   *
-   * Unlike the other operations this is NOT auto-retried on a transient error:
-   * the gateway isn't idempotent for completion, so a retry after a
-   * successful-but-unacknowledged complete would return a spurious NoSuchUpload.
-   * On a transient failure, re-drive completion yourself only after confirming
-   * the object isn't already present.
-   *
-   * @param key       The upload's object key.
-   * @param uploadId  The id from {@link create}.
-   * @param parts     The `{ partNumber, etag }` pairs from {@link uploadPart}.
-   */
-  async complete(key, uploadId, parts) {
-    const sorted = [...parts].sort((a, b) => a.partNumber - b.partNumber);
-    const xml = buildCompleteMultipartUploadXml(sorted);
-    const resp = await this.s3Request("POST", key, {
-      query: { uploadId },
-      body: xml,
-      contentType: "application/xml",
-      retry: false
-    });
-    if (!resp.ok) {
-      throw parseS3Error("CompleteMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    const root = parseXml(decodeText(resp.body)).CompleteMultipartUploadResult ?? {};
-    return {
-      etag: optionalString(root.ETag),
-      location: optionalString(root.Location),
-      bucket: optionalString(root.Bucket),
-      key: optionalString(root.Key)
-    };
-  }
-  /**
-   * Abort a multipart upload (AbortMultipartUpload), discarding every staged
-   * part. Idempotent against an upload that's already gone (404 / NoSuchUpload
-   * resolves successfully).
-   *
-   * @param key       The upload's object key.
-   * @param uploadId  The id from {@link create}.
-   */
-  async abort(key, uploadId) {
-    const resp = await this.s3Request("DELETE", key, { query: { uploadId } });
-    if (!resp.ok && resp.status !== 404) {
-      throw parseS3Error("AbortMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
-    }
-  }
-  /**
-   * List the parts already uploaded for an in-progress upload (ListParts).
-   * Returns a single page; follow `nextPartNumberMarker` (when `isTruncated`)
-   * to page through the rest.
-   *
-   * @param key       The upload's object key.
-   * @param uploadId  The id from {@link create}.
-   * @param opts      `maxParts` / `partNumberMarker` pagination controls.
-   */
-  async listParts(key, uploadId, opts = {}) {
-    const query = { uploadId };
-    if (opts.maxParts !== void 0) query["max-parts"] = opts.maxParts;
-    if (opts.partNumberMarker !== void 0) query["part-number-marker"] = opts.partNumberMarker;
-    const resp = await this.s3Request("GET", key, { query });
-    if (!resp.ok) {
-      throw parseS3Error("ListParts", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return parseListPartsResult(decodeText(resp.body));
-  }
-  /**
-   * List in-progress multipart uploads on the disk (ListMultipartUploads).
-   * Returns a single page; follow `nextKeyMarker` / `nextUploadIdMarker` (when
-   * `isTruncated`) for the rest.
-   *
-   * @param opts  Prefix/delimiter filter and pagination markers.
-   */
-  async listUploads(opts = {}) {
-    const query = { uploads: "" };
-    if (opts.prefix !== void 0) query.prefix = opts.prefix;
-    if (opts.delimiter !== void 0) query.delimiter = opts.delimiter;
-    if (opts.keyMarker !== void 0) query["key-marker"] = opts.keyMarker;
-    if (opts.uploadIdMarker !== void 0) query["upload-id-marker"] = opts.uploadIdMarker;
-    if (opts.maxUploads !== void 0) query["max-uploads"] = opts.maxUploads;
-    const resp = await this.s3Request("GET", "", { query });
-    if (!resp.ok) {
-      throw parseS3Error("ListMultipartUploads", resp.status, resp.statusText, decodeText(resp.body));
-    }
-    return parseListMultipartUploadsResult(decodeText(resp.body));
-  }
+	diskId;
+	s3Request;
+	/** @internal */
+	constructor(diskId, s3Request) {
+		this.diskId = diskId;
+		this.s3Request = s3Request;
+	}
+	/**
+	* Start a multipart upload (CreateMultipartUpload) and return its `uploadId`.
+	*
+	* @param key          Path on the disk the finished object will live at.
+	* @param contentType  MIME type to store the object with.
+	*/
+	async create(key, contentType) {
+		const resp = await this.s3Request("POST", key, {
+			query: { uploads: "" },
+			contentType
+		});
+		if (!resp.ok) throw parseS3Error("CreateMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+		const root = parseXml(decodeText(resp.body)).InitiateMultipartUploadResult ?? {};
+		const uploadId = optionalString(root.UploadId);
+		if (!uploadId) throw new ArchilS3Error({
+			operation: "CreateMultipartUpload",
+			statusCode: resp.status,
+			message: "response did not contain an UploadId",
+			raw: decodeText(resp.body)
+		});
+		return {
+			uploadId,
+			key: optionalString(root.Key) ?? key,
+			bucket: optionalString(root.Bucket) ?? this.diskId
+		};
+	}
+	/**
+	* Upload one part (UploadPart) and return its entity tag, which you must
+	* collect (with its part number) and pass to {@link complete}. Every part
+	* except the last must be at least 5 MiB.
+	*
+	* @param key         The upload's object key.
+	* @param uploadId    The id from {@link create}.
+	* @param partNumber  1-based part number (1..=10000).
+	* @param body        Part contents as a string, Uint8Array/Buffer, or ArrayBuffer.
+	*/
+	async uploadPart(key, uploadId, partNumber, body) {
+		const resp = await this.s3Request("PUT", key, {
+			query: {
+				uploadId,
+				partNumber
+			},
+			body
+		});
+		if (!resp.ok) throw parseS3Error("UploadPart", resp.status, resp.statusText, decodeText(resp.body));
+		return {
+			partNumber,
+			etag: resp.headers.get("etag") ?? ""
+		};
+	}
+	/**
+	* Finish a multipart upload (CompleteMultipartUpload), assembling the listed
+	* parts into one object. Parts are sorted by part number before submission
+	* (the server requires strictly-increasing order).
+	*
+	* Unlike the other operations this is NOT auto-retried on a transient error:
+	* the gateway isn't idempotent for completion, so a retry after a
+	* successful-but-unacknowledged complete would return a spurious NoSuchUpload.
+	* On a transient failure, re-drive completion yourself only after confirming
+	* the object isn't already present.
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	* @param parts     The `{ partNumber, etag }` pairs from {@link uploadPart}.
+	*/
+	async complete(key, uploadId, parts) {
+		const xml = buildCompleteMultipartUploadXml([...parts].sort((a, b) => a.partNumber - b.partNumber));
+		const resp = await this.s3Request("POST", key, {
+			query: { uploadId },
+			body: xml,
+			contentType: "application/xml",
+			retry: false
+		});
+		if (!resp.ok) throw parseS3Error("CompleteMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+		const root = parseXml(decodeText(resp.body)).CompleteMultipartUploadResult ?? {};
+		return {
+			etag: optionalString(root.ETag),
+			location: optionalString(root.Location),
+			bucket: optionalString(root.Bucket),
+			key: optionalString(root.Key)
+		};
+	}
+	/**
+	* Abort a multipart upload (AbortMultipartUpload), discarding every staged
+	* part. Idempotent against an upload that's already gone (404 / NoSuchUpload
+	* resolves successfully).
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	*/
+	async abort(key, uploadId) {
+		const resp = await this.s3Request("DELETE", key, { query: { uploadId } });
+		if (!resp.ok && resp.status !== 404) throw parseS3Error("AbortMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+	}
+	/**
+	* List the parts already uploaded for an in-progress upload (ListParts).
+	* Returns a single page; follow `nextPartNumberMarker` (when `isTruncated`)
+	* to page through the rest.
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	* @param opts      `maxParts` / `partNumberMarker` pagination controls.
+	*/
+	async listParts(key, uploadId, opts = {}) {
+		const query = { uploadId };
+		if (opts.maxParts !== void 0) query["max-parts"] = opts.maxParts;
+		if (opts.partNumberMarker !== void 0) query["part-number-marker"] = opts.partNumberMarker;
+		const resp = await this.s3Request("GET", key, { query });
+		if (!resp.ok) throw parseS3Error("ListParts", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListPartsResult(decodeText(resp.body));
+	}
+	/**
+	* List in-progress multipart uploads on the disk (ListMultipartUploads).
+	* Returns a single page; follow `nextKeyMarker` / `nextUploadIdMarker` (when
+	* `isTruncated`) for the rest.
+	*
+	* @param opts  Prefix/delimiter filter and pagination markers.
+	*/
+	async listUploads(opts = {}) {
+		const query = { uploads: "" };
+		if (opts.prefix !== void 0) query.prefix = opts.prefix;
+		if (opts.delimiter !== void 0) query.delimiter = opts.delimiter;
+		if (opts.keyMarker !== void 0) query["key-marker"] = opts.keyMarker;
+		if (opts.uploadIdMarker !== void 0) query["upload-id-marker"] = opts.uploadIdMarker;
+		if (opts.maxUploads !== void 0) query["max-uploads"] = opts.maxUploads;
+		const resp = await this.s3Request("GET", "", { query });
+		if (!resp.ok) throw parseS3Error("ListMultipartUploads", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListMultipartUploadsResult(decodeText(resp.body));
+	}
 };
-var MAX_DELETE_OBJECTS_PER_REQUEST = 1e3;
-var MAX_S3_RETRIES = 3;
-var S3_RETRY_BASE_MS = 100;
-var S3_RETRY_CAP_MS = 2e3;
+/** S3's per-request cap on DeleteObjects keys; larger inputs are batched. */
+const MAX_DELETE_OBJECTS_PER_REQUEST = 1e3;
+/** Automatic retries for a transient S3 failure (5xx / 429 / network error). */
+const MAX_S3_RETRIES = 3;
+/** Base backoff for S3 retries (ms); grows exponentially, then full-jittered. */
+const S3_RETRY_BASE_MS = 100;
+/** Ceiling for a single retry backoff (ms). */
+const S3_RETRY_CAP_MS = 2e3;
+/**
+* Statuses worth retrying: throttling (429) and the gateway's transient 5xx
+* (e.g. a journal-commit timeout surfaced as 500). 4xx other than 429 are
+* caller errors and never retried.
+*/
 function isTransientS3Status(status) {
-  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+	return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
 }
+/** Full-jittered exponential backoff for retry `attempt` (0-based). */
 function s3RetryDelayMs(attempt) {
-  const ceiling = Math.min(S3_RETRY_CAP_MS, S3_RETRY_BASE_MS * 2 ** attempt);
-  return Math.random() * ceiling;
+	const ceiling = Math.min(S3_RETRY_CAP_MS, S3_RETRY_BASE_MS * 2 ** attempt);
+	return Math.random() * ceiling;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var MIN_PART_SIZE = 5 * 1024 * 1024;
-var DEFAULT_PART_SIZE = 16 * 1024 * 1024;
-var DEFAULT_UPLOAD_CONCURRENCY = 4;
-var MAX_PARTS_PER_UPLOAD = 1e4;
+/** S3's minimum size for every multipart part but the last (5 MiB). */
+const MIN_PART_SIZE = 5 * 1024 * 1024;
+/** Default part size {@link Disk.putObject} uses on the multipart path (16 MiB). */
+const DEFAULT_PART_SIZE = 16 * 1024 * 1024;
+/** Default number of parts {@link Disk.putObject} uploads in parallel. */
+const DEFAULT_UPLOAD_CONCURRENCY = 4;
+/** The server's cap on parts in a single multipart upload (MAX_PARTS_PER_UPLOAD). */
+const MAX_PARTS_PER_UPLOAD = 1e4;
+/**
+* Choose the part size for a `totalBytes` multipart upload. Returns
+* `requestedPartSize` unless splitting at that size would exceed the server's
+* 10,000-part cap, in which case it grows the part size (rounded up to a whole
+* MiB) so the body fits in ≤ 10,000 parts — mirroring boto3's chunk-size
+* adjustment. Parts only ever get larger, so they stay above the 5 MiB floor.
+*/
 function effectiveUploadPartSize(totalBytes, requestedPartSize) {
-  if (Math.ceil(totalBytes / requestedPartSize) <= MAX_PARTS_PER_UPLOAD) {
-    return requestedPartSize;
-  }
-  const MiB = 1024 * 1024;
-  const needed = Math.ceil(totalBytes / MAX_PARTS_PER_UPLOAD);
-  return Math.ceil(needed / MiB) * MiB;
+	if (Math.ceil(totalBytes / requestedPartSize) <= MAX_PARTS_PER_UPLOAD) return requestedPartSize;
+	const MiB = 1024 * 1024;
+	const needed = Math.ceil(totalBytes / MAX_PARTS_PER_UPLOAD);
+	return Math.ceil(needed / MiB) * MiB;
 }
+/** Normalize an upload body to bytes so it can be sized and sliced into parts. */
 function toBytes(body) {
-  if (typeof body === "string") return new TextEncoder().encode(body);
-  if (body instanceof Uint8Array) return body;
-  return new Uint8Array(body);
+	if (typeof body === "string") return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	return new Uint8Array(body);
 }
+/** Escape text for safe inclusion in XML element content. */
 function escapeXml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+/** Build a `<Delete>` request body for the DeleteObjects API. */
 function buildDeleteObjectsXml(keys, quiet) {
-  const objects = keys.map((k) => `<Object><Key>${escapeXml(k)}</Key></Object>`).join("");
-  const quietTag = quiet ? "<Quiet>true</Quiet>" : "";
-  return `<?xml version="1.0" encoding="UTF-8"?><Delete>${objects}${quietTag}</Delete>`;
+	return `<?xml version="1.0" encoding="UTF-8"?><Delete>${keys.map((k) => `<Object><Key>${escapeXml(k)}</Key></Object>`).join("")}${quiet ? "<Quiet>true</Quiet>" : ""}</Delete>`;
 }
+/** Build a `<CompleteMultipartUpload>` request body from the uploaded parts. */
 function buildCompleteMultipartUploadXml(parts) {
-  const body = parts.map(
-    (p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${escapeXml(p.etag)}</ETag></Part>`
-  ).join("");
-  return `<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload>${body}</CompleteMultipartUpload>`;
+	return `<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload>${parts.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${escapeXml(p.etag)}</ETag></Part>`).join("")}</CompleteMultipartUpload>`;
 }
+/** Coerce a parser value that may be a single object or an array into an array. */
 function asArray(value) {
-  if (value === void 0 || value === null) return [];
-  return Array.isArray(value) ? value : [value];
+	if (value === void 0 || value === null) return [];
+	return Array.isArray(value) ? value : [value];
 }
 function optionalNumber(value) {
-  return value === void 0 || value === null ? void 0 : Number(value);
+	return value === void 0 || value === null ? void 0 : Number(value);
 }
 function optionalString(value) {
-  return value === void 0 || value === null ? void 0 : String(value);
+	return value === void 0 || value === null ? void 0 : String(value);
 }
 function optionalDate(value) {
-  return value === void 0 || value === null ? void 0 : new Date(String(value));
+	return value === void 0 || value === null ? void 0 : new Date(String(value));
 }
+/** Decode response bytes to a UTF-8 string (used for XML error/result bodies). */
 function decodeText(bytes) {
-  return new TextDecoder().decode(bytes);
+	return new TextDecoder().decode(bytes);
 }
+/** Parse an S3 ListObjectsV2 `<ListBucketResult>` XML document. */
 function parseListObjectsResult(xml) {
-  const root = parseXml(xml).ListBucketResult ?? {};
-  const contents = root.Contents ?? [];
-  const objects = contents.map((c) => ({
-    key: String(c.Key ?? ""),
-    size: Number(c.Size ?? 0),
-    etag: optionalString(c.ETag),
-    lastModified: optionalDate(c.LastModified)
-  }));
-  const commonPrefixes = (root.CommonPrefixes ?? []).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
-  return {
-    objects,
-    commonPrefixes,
-    isTruncated: root.IsTruncated === "true" || root.IsTruncated === true,
-    nextContinuationToken: optionalString(root.NextContinuationToken),
-    keyCount: root.KeyCount !== void 0 ? Number(root.KeyCount) : objects.length,
-    prefix: optionalString(root.Prefix)
-  };
+	const root = parseXml(xml).ListBucketResult ?? {};
+	const objects = (root.Contents ?? []).map((c) => ({
+		key: String(c.Key ?? ""),
+		size: Number(c.Size ?? 0),
+		etag: optionalString(c.ETag),
+		lastModified: optionalDate(c.LastModified)
+	}));
+	return {
+		objects,
+		commonPrefixes: (root.CommonPrefixes ?? []).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0),
+		isTruncated: root.IsTruncated === "true" || root.IsTruncated === true,
+		nextContinuationToken: optionalString(root.NextContinuationToken),
+		keyCount: root.KeyCount !== void 0 ? Number(root.KeyCount) : objects.length,
+		prefix: optionalString(root.Prefix)
+	};
 }
 function xmlIsTruncated(value) {
-  return value === "true" || value === true;
+	return value === "true" || value === true;
 }
+/** Parse an S3 DeleteObjects `<DeleteResult>` XML document. */
 function parseDeleteObjectsResult(xml) {
-  const root = parseXml(xml).DeleteResult ?? {};
-  const deleted = asArray(root.Deleted).map((d) => optionalString(d.Key)).filter((k) => k !== void 0);
-  const errors = asArray(root.Error).map((e) => ({
-    key: String(e.Key ?? ""),
-    code: optionalString(e.Code),
-    message: optionalString(e.Message)
-  }));
-  return { deleted, errors };
+	const root = parseXml(xml).DeleteResult ?? {};
+	return {
+		deleted: asArray(root.Deleted).map((d) => optionalString(d.Key)).filter((k) => k !== void 0),
+		errors: asArray(root.Error).map((e) => ({
+			key: String(e.Key ?? ""),
+			code: optionalString(e.Code),
+			message: optionalString(e.Message)
+		}))
+	};
 }
+/** Parse an S3 `<ListPartsResult>` XML document. */
 function parseListPartsResult(xml) {
-  const root = parseXml(xml).ListPartsResult ?? {};
-  const parts = asArray(root.Part).map((p) => ({
-    partNumber: Number(p.PartNumber ?? 0),
-    etag: optionalString(p.ETag),
-    size: Number(p.Size ?? 0),
-    lastModified: optionalDate(p.LastModified)
-  }));
-  return {
-    bucket: optionalString(root.Bucket),
-    key: optionalString(root.Key),
-    uploadId: optionalString(root.UploadId),
-    parts,
-    isTruncated: xmlIsTruncated(root.IsTruncated),
-    partNumberMarker: Number(root.PartNumberMarker ?? 0),
-    nextPartNumberMarker: optionalNumber(root.NextPartNumberMarker),
-    maxParts: Number(root.MaxParts ?? parts.length)
-  };
+	const root = parseXml(xml).ListPartsResult ?? {};
+	const parts = asArray(root.Part).map((p) => ({
+		partNumber: Number(p.PartNumber ?? 0),
+		etag: optionalString(p.ETag),
+		size: Number(p.Size ?? 0),
+		lastModified: optionalDate(p.LastModified)
+	}));
+	return {
+		bucket: optionalString(root.Bucket),
+		key: optionalString(root.Key),
+		uploadId: optionalString(root.UploadId),
+		parts,
+		isTruncated: xmlIsTruncated(root.IsTruncated),
+		partNumberMarker: Number(root.PartNumberMarker ?? 0),
+		nextPartNumberMarker: optionalNumber(root.NextPartNumberMarker),
+		maxParts: Number(root.MaxParts ?? parts.length)
+	};
 }
+/** Parse an S3 `<ListMultipartUploadsResult>` XML document. */
 function parseListMultipartUploadsResult(xml) {
-  const root = parseXml(xml).ListMultipartUploadsResult ?? {};
-  const uploads = asArray(root.Upload).map((u) => ({
-    key: String(u.Key ?? ""),
-    uploadId: String(u.UploadId ?? ""),
-    initiated: optionalDate(u.Initiated)
-  }));
-  const commonPrefixes = asArray(root.CommonPrefixes).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
-  return {
-    bucket: optionalString(root.Bucket),
-    uploads,
-    commonPrefixes,
-    isTruncated: xmlIsTruncated(root.IsTruncated),
-    keyMarker: optionalString(root.KeyMarker),
-    uploadIdMarker: optionalString(root.UploadIdMarker),
-    nextKeyMarker: optionalString(root.NextKeyMarker),
-    nextUploadIdMarker: optionalString(root.NextUploadIdMarker),
-    prefix: optionalString(root.Prefix),
-    delimiter: optionalString(root.Delimiter),
-    maxUploads: optionalNumber(root.MaxUploads)
-  };
+	const root = parseXml(xml).ListMultipartUploadsResult ?? {};
+	const uploads = asArray(root.Upload).map((u) => ({
+		key: String(u.Key ?? ""),
+		uploadId: String(u.UploadId ?? ""),
+		initiated: optionalDate(u.Initiated)
+	}));
+	const commonPrefixes = asArray(root.CommonPrefixes).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
+	return {
+		bucket: optionalString(root.Bucket),
+		uploads,
+		commonPrefixes,
+		isTruncated: xmlIsTruncated(root.IsTruncated),
+		keyMarker: optionalString(root.KeyMarker),
+		uploadIdMarker: optionalString(root.UploadIdMarker),
+		nextKeyMarker: optionalString(root.NextKeyMarker),
+		nextUploadIdMarker: optionalString(root.NextUploadIdMarker),
+		prefix: optionalString(root.Prefix),
+		delimiter: optionalString(root.Delimiter),
+		maxUploads: optionalNumber(root.MaxUploads)
+	};
 }
-
-// src/disks.ts
+//#endregion
+//#region src/disks.ts
 var Disks = class {
-  /** @internal */
-  _client;
-  /** @internal */
-  _region;
-  /** @internal */
-  _s3BaseUrl;
-  /** @internal */
-  constructor(client, region, s3BaseUrl) {
-    this._client = client;
-    this._region = region;
-    this._s3BaseUrl = s3BaseUrl;
-  }
-  async list(opts) {
-    const data = await unwrap(
-      this._client.GET("/api/disks", {
-        params: { query: { limit: opts?.limit, cursor: opts?.cursor, name: opts?.name } }
-      })
-    );
-    return data.map(
-      (d) => new Disk(d, this._client, this._region, this._s3BaseUrl)
-    );
-  }
-  async get(id) {
-    const data = await unwrap(
-      this._client.GET("/api/disks/{id}", {
-        params: { path: { id } }
-      })
-    );
-    return new Disk(data, this._client, this._region, this._s3BaseUrl);
-  }
-  /**
-   * Create a new disk with an auto-generated mount token.
-   *
-   * Returns the Disk, the one-time token (save it — it cannot be retrieved
-   * again), and the token identifier for later management.
-   */
-  async create(req) {
-    const created = await unwrap(
-      this._client.POST("/api/disks", { body: req })
-    );
-    const resp = created;
-    if (!resp.diskId) {
-      throw new Error("API returned success but no diskId");
-    }
-    const authorizedUsers = resp.authorizedUsers ?? [];
-    const tokenUser = authorizedUsers.find((u) => u.token);
-    const disk = await this.get(resp.diskId);
-    return {
-      disk,
-      token: tokenUser?.token ?? null,
-      tokenIdentifier: tokenUser?.identifier ?? null,
-      authorizedUsers
-    };
-  }
+	/** @internal */
+	_client;
+	/** @internal */
+	_region;
+	/** @internal */
+	_s3BaseUrl;
+	/** @internal */
+	constructor(client, region, s3BaseUrl) {
+		this._client = client;
+		this._region = region;
+		this._s3BaseUrl = s3BaseUrl;
+	}
+	async list(opts) {
+		return (await unwrap(this._client.GET("/api/disks", { params: { query: {
+			limit: opts?.limit,
+			cursor: opts?.cursor,
+			name: opts?.name
+		} } }))).map((d) => new Disk(d, this._client, this._region, this._s3BaseUrl));
+	}
+	async get(id) {
+		return new Disk(await unwrap(this._client.GET("/api/disks/{id}", { params: { path: { id } } })), this._client, this._region, this._s3BaseUrl);
+	}
+	/**
+	* Create a new disk with an auto-generated mount token.
+	*
+	* Returns the Disk, the one-time token (save it — it cannot be retrieved
+	* again), and the token identifier for later management.
+	*/
+	async create(req) {
+		const resp = await unwrap(this._client.POST("/api/disks", { body: req }));
+		if (!resp.diskId) throw new Error("API returned success but no diskId");
+		const authorizedUsers = resp.authorizedUsers ?? [];
+		const tokenUser = authorizedUsers.find((u) => u.token);
+		return {
+			disk: await this.get(resp.diskId),
+			token: tokenUser?.token ?? null,
+			tokenIdentifier: tokenUser?.identifier ?? null,
+			authorizedUsers
+		};
+	}
 };
-
-// src/tokens.ts
+//#endregion
+//#region src/tokens.ts
 var Tokens = class {
-  /** @internal */
-  _client;
-  /** @internal */
-  constructor(client) {
-    this._client = client;
-  }
-  async list(opts) {
-    const data = await unwrap(
-      this._client.GET("/api/tokens", {
-        params: { query: { limit: opts?.limit, cursor: opts?.cursor } }
-      })
-    );
-    return data.tokens ?? [];
-  }
-  async create(req) {
-    const data = await unwrap(
-      this._client.POST("/api/tokens", { body: req })
-    );
-    return data;
-  }
-  async delete(id) {
-    await unwrapEmpty(
-      this._client.DELETE("/api/tokens/{id}", {
-        params: { path: { id } }
-      })
-    );
-  }
+	/** @internal */
+	_client;
+	/** @internal */
+	constructor(client) {
+		this._client = client;
+	}
+	async list(opts) {
+		return (await unwrap(this._client.GET("/api/tokens", { params: { query: {
+			limit: opts?.limit,
+			cursor: opts?.cursor
+		} } }))).tokens ?? [];
+	}
+	async create(req) {
+		return await unwrap(this._client.POST("/api/tokens", { body: req }));
+	}
+	async delete(id) {
+		await unwrapEmpty(this._client.DELETE("/api/tokens/{id}", { params: { path: { id } } }));
+	}
+};
+//#endregion
+//#region src/workspace.ts
+function isExecMountSpec$1(m) {
+	return typeof m === "object" && m !== null && "disk" in m;
+}
+/**
+* A key-routed filesystem spanning several Archil disks. Each disk is mounted
+* under a name and addressed as the first segment of a key (`<name>/...`);
+* `getObject`, `putObject`, `deleteObject`, `listObjects`, and `grep` route to
+* the right disk by that segment (and `listObjects` / `grep` fan out across all
+* of them when the key/prefix doesn't name one). Implements the same
+* {@link FileSystem} surface as a single {@link Disk}, so it works anywhere a
+* disk does. Mounts can be changed at runtime with {@link addDisk} /
+* {@link removeDisk}.
+*/
+var Workspace = class {
+	client;
+	mounts = /* @__PURE__ */ new Map();
+	/** @internal Use `archil.workspace({ ... })`. */
+	constructor(client, mounts) {
+		this.client = client;
+		for (const [name, value] of Object.entries(mounts)) this.addDisk(name, value);
+		if (this.mounts.size === 0) throw new Error("workspace() needs at least one disk");
+	}
+	/** Mount (or replace) a disk at `name`; its objects are addressed as
+	* `<name>/...`. Accepts a `Disk` or a mount spec (read-only / subdirectory /
+	* conditional / delegation checkouts); a bare disk-id string is rejected —
+	* fetch the disk first. */
+	addDisk(name, disk) {
+		const rel = name.replace(/^\/+|\/+$/g, "");
+		if (!rel) throw new Error("workspace mount name must be non-empty");
+		if (rel.includes("/")) throw new Error(`workspace mount name '${name}' must not contain '/'`);
+		if (rel === "." || rel === "..") throw new Error(`workspace mount name '${name}' is reserved ('.' and '..' are path navigation, not disk names)`);
+		let d;
+		let readOnly = false;
+		let subdirectory;
+		let conditional = false;
+		let queueMs;
+		let checkoutPaths;
+		if (isExecMountSpec$1(disk)) {
+			d = disk.disk;
+			readOnly = disk.readOnly ?? false;
+			subdirectory = disk.subdirectory;
+			conditional = disk.conditional ?? false;
+			queueMs = disk.queueMs;
+			checkoutPaths = disk.checkoutPaths;
+		} else d = disk;
+		if (typeof d === "string") throw new Error("workspace needs Disk objects, not disk-id strings; fetch with archil.getDisk(id) first");
+		this.mounts.set(rel, {
+			disk: d,
+			readOnly,
+			subdirectory,
+			conditional,
+			queueMs,
+			checkoutPaths
+		});
+		return this;
+	}
+	/** Unmount the disk at `name`. Returns whether a disk was removed. Refuses to
+	* remove the last disk — a workspace must always have at least one (the same
+	* invariant the constructor enforces), else fan-out/exec would have nothing to
+	* route to. */
+	removeDisk(name) {
+		const rel = name.replace(/^\/+|\/+$/g, "");
+		if (this.mounts.has(rel) && this.mounts.size === 1) throw new Error("cannot remove the last disk from a workspace; a workspace must keep at least one");
+		return this.mounts.delete(rel);
+	}
+	/** The names of the currently-mounted disks. */
+	diskNames() {
+		return [...this.mounts.keys()];
+	}
+	unknownDisk(name) {
+		return /* @__PURE__ */ new Error(`No disk named '${name}'. Address objects by disk: ${this.diskNames().map((n) => `${n}/…`).join(", ")}`);
+	}
+	/** Resolve a workspace key (`<name>/...`) to the disk and the disk-relative key. */
+	route(key) {
+		const segs = require_paths.toSegments(key);
+		if (segs.length === 0) throw new Error("that key is the workspace root, not an object; name a disk, e.g. data/file.txt");
+		const entry = this.mounts.get(segs[0]);
+		if (!entry) throw this.unknownDisk(segs[0]);
+		return {
+			entry,
+			diskKey: this.diskKey(entry, segs.slice(1).join("/"))
+		};
+	}
+	/** Mounts touched by a key prefix; an empty prefix fans out to all of them. */
+	covered(prefix) {
+		const segs = require_paths.toSegments(prefix);
+		if (segs.length === 0) return [...this.mounts.entries()].map(([name, entry]) => ({
+			name,
+			entry,
+			rel: this.diskKey(entry, "")
+		}));
+		const entry = this.mounts.get(segs[0]);
+		if (!entry) throw this.unknownDisk(segs[0]);
+		return [{
+			name: segs[0],
+			entry,
+			rel: this.diskKey(entry, segs.slice(1).join("/"))
+		}];
+	}
+	/** Map a workspace-relative key to the disk's key, applying the mount's subdirectory. */
+	diskKey(entry, rel) {
+		const trimmed = rel.replace(/^\/+/, "");
+		const sub = (entry.subdirectory ?? "").replace(/^\/+|\/+$/g, "");
+		if (!sub) return trimmed;
+		return trimmed ? `${sub}/${trimmed}` : sub;
+	}
+	/** Map a disk key back to its workspace key (`<name>/...`), stripping the mount subdirectory. */
+	abs(name, entry, diskKey) {
+		const sub = (entry.subdirectory ?? "").replace(/^\/+|\/+$/g, "");
+		let rel = diskKey;
+		if (sub && diskKey.startsWith(sub + "/")) rel = diskKey.slice(sub.length + 1);
+		else if (sub && diskKey === sub) rel = "";
+		rel = rel.replace(/^\/+|\/+$/g, "");
+		return rel ? `${name}/${rel}` : name;
+	}
+	async getObject(key) {
+		const { entry, diskKey } = this.route(key);
+		return entry.disk.getObject(diskKey);
+	}
+	async putObject(key, body, contentType) {
+		const { entry, diskKey } = this.route(key);
+		if (entry.readOnly) throw new Error(`${key} is on a read-only disk and cannot be written.`);
+		return entry.disk.putObject(diskKey, body, contentType);
+	}
+	async deleteObject(key) {
+		const { entry, diskKey } = this.route(key);
+		if (entry.readOnly) throw new Error(`${key} is on a read-only disk and cannot be deleted.`);
+		await entry.disk.deleteObject(diskKey);
+	}
+	async listObjects(prefix, opts = {}) {
+		if (require_paths.toSegments(prefix ?? "").length === 0 && !opts.recursive) return {
+			objects: [],
+			commonPrefixes: this.diskNames().map((n) => `${n}/`).sort(),
+			isTruncated: false,
+			keyCount: 0
+		};
+		const covered = this.covered(prefix ?? "");
+		const listings = await Promise.allSettled(covered.map(({ entry, rel }) => {
+			const p = rel ? rel.endsWith("/") ? rel : `${rel}/` : void 0;
+			return entry.disk.listObjects(p, { recursive: opts.recursive });
+		}));
+		const objects = [];
+		const commonPrefixes = [];
+		let isTruncated = false;
+		let keyCount = 0;
+		covered.forEach(({ name, entry }, i) => {
+			const settled = listings[i];
+			if (settled.status === "rejected") {
+				isTruncated = true;
+				return;
+			}
+			const listing = settled.value;
+			for (const cp of listing.commonPrefixes) commonPrefixes.push(`${this.abs(name, entry, cp.replace(/\/+$/, ""))}/`);
+			for (const obj of listing.objects) objects.push({
+				...obj,
+				key: this.abs(name, entry, obj.key)
+			});
+			isTruncated = isTruncated || listing.isTruncated;
+			keyCount += listing.keyCount;
+		});
+		objects.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+		commonPrefixes.sort();
+		return {
+			objects,
+			commonPrefixes,
+			isTruncated,
+			keyCount
+		};
+	}
+	async grep(opts) {
+		const covered = this.covered(opts.directory ?? "");
+		const results = await Promise.allSettled(covered.map(({ entry, rel }) => entry.disk.grep({
+			...opts,
+			directory: rel
+		})));
+		const matches = [];
+		let filesScanned = 0;
+		let containersDispatched = 0;
+		let computeSecondsUsed = 0;
+		let durationMs = 0;
+		let listingMs = 0;
+		let grepMs = 0;
+		const reasons = /* @__PURE__ */ new Set();
+		covered.forEach(({ name, entry }, i) => {
+			const settled = results[i];
+			if (settled.status === "rejected") {
+				reasons.add("list_failed");
+				return;
+			}
+			const r = settled.value;
+			filesScanned += r.filesScanned;
+			containersDispatched += r.containersDispatched ?? 0;
+			computeSecondsUsed += r.computeSecondsUsed ?? 0;
+			durationMs = Math.max(durationMs, r.durationMs ?? 0);
+			listingMs = Math.max(listingMs, r.listingMs ?? 0);
+			grepMs = Math.max(grepMs, r.grepMs ?? 0);
+			reasons.add(r.stoppedReason);
+			for (const m of r.matches) matches.push({
+				file: this.abs(name, entry, m.file),
+				line: m.line,
+				text: m.text
+			});
+		});
+		const cap = opts.maxResults ?? 1e3;
+		if (matches.length > cap) reasons.add("max_results");
+		const priority = [
+			"list_failed",
+			"incomplete",
+			"deadline",
+			"max_results"
+		];
+		const stoppedReason = [...reasons].every((x) => x === "completed") ? "completed" : priority.find((x) => reasons.has(x)) ?? "completed";
+		return {
+			matches: matches.slice(0, cap),
+			stoppedReason,
+			filesScanned,
+			containersDispatched,
+			computeSecondsUsed,
+			durationMs,
+			listingMs,
+			grepMs
+		};
+	}
+	exec(command) {
+		const disks = {};
+		for (const [name, entry] of this.mounts) disks[name] = entry.readOnly || entry.subdirectory || entry.conditional || entry.queueMs !== void 0 || entry.checkoutPaths !== void 0 ? {
+			disk: entry.disk,
+			subdirectory: entry.subdirectory,
+			readOnly: entry.readOnly,
+			conditional: entry.conditional,
+			queueMs: entry.queueMs,
+			checkoutPaths: entry.checkoutPaths
+		} : entry.disk;
+		return this.client.exec({
+			disks,
+			command
+		});
+	}
 };
-
-// src/archil.ts
+//#endregion
+//#region src/archil.ts
+/**
+* Read an environment variable in a way that is safe in browsers, where the
+* `process` global does not exist. Returns undefined when there is no process
+* environment, so the SDK can be bundled and run client-side as long as
+* credentials are passed explicitly to `new Archil({ ... })`.
+*/
 function envVar(name) {
-  return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
+	return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
 }
 function isExecMountSpec(m) {
-  return typeof m === "object" && m !== null && "disk" in m;
+	return typeof m === "object" && m !== null && "disk" in m;
 }
 function diskIdFromMount(m) {
-  return typeof m === "string" ? m : m.id;
+	return typeof m === "string" ? m : m.id;
 }
 var Archil = class {
-  disks;
-  tokens;
-  /** @internal */
-  _client;
-  constructor(opts = {}) {
-    const apiKey = opts.apiKey ?? envVar("ARCHIL_API_KEY");
-    const region = opts.region ?? envVar("ARCHIL_REGION");
-    if (!apiKey) {
-      throw new Error("Missing API key: pass apiKey in options or set ARCHIL_API_KEY environment variable");
-    }
-    if (!region) {
-      throw new Error("Missing region: pass region in options or set ARCHIL_REGION environment variable");
-    }
-    const controlBaseUrl = opts.baseUrl ?? resolveBaseUrl(region);
-    const client = createApiClient({
-      apiKey,
-      region,
-      baseUrl: controlBaseUrl
-    });
-    const s3BaseUrl = opts.s3BaseUrl ?? envVar("ARCHIL_S3_BASE_URL") ?? deriveS3BaseUrl(controlBaseUrl);
-    this._client = client;
-    this.disks = new Disks(client, region, s3BaseUrl);
-    this.tokens = new Tokens(client);
-  }
-  /**
-   * Run a command in a container with multiple disks mounted simultaneously,
-   * each at its own relative path under `/mnt/archil`. Blocks until the
-   * command completes and returns its stdout, stderr, exit code, and timing.
-   */
-  async exec(opts) {
-    const disks = {};
-    for (const [relPath, mount] of Object.entries(opts.disks)) {
-      if (isExecMountSpec(mount)) {
-        const entry = {
-          disk: diskIdFromMount(mount.disk),
-          readOnly: mount.readOnly ?? false
-        };
-        if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
-        disks[relPath] = entry;
-      } else {
-        disks[relPath] = diskIdFromMount(mount);
-      }
-    }
-    return unwrap(
-      this._client.POST("/api/exec", {
-        body: { disks, command: opts.command }
-      })
-    );
-  }
+	disks;
+	tokens;
+	/** @internal */
+	_client;
+	constructor(opts = {}) {
+		const apiKey = opts.apiKey ?? envVar("ARCHIL_API_KEY");
+		const region = opts.region ?? envVar("ARCHIL_REGION");
+		if (!apiKey) throw new Error("Missing API key: pass apiKey in options or set ARCHIL_API_KEY environment variable");
+		if (!region) throw new Error("Missing region: pass region in options or set ARCHIL_REGION environment variable");
+		const controlBaseUrl = opts.baseUrl ?? resolveBaseUrl(region);
+		const client = createApiClient({
+			apiKey,
+			region,
+			baseUrl: controlBaseUrl
+		});
+		const s3BaseUrl = opts.s3BaseUrl ?? envVar("ARCHIL_S3_BASE_URL") ?? deriveS3BaseUrl(controlBaseUrl);
+		this._client = client;
+		this.disks = new Disks(client, region, s3BaseUrl);
+		this.tokens = new Tokens(client);
+	}
+	/**
+	* Run a command in a container with multiple disks mounted simultaneously,
+	* each at its own relative path under `/mnt/archil`. Blocks until the
+	* command completes and returns its stdout, stderr, exit code, and timing.
+	*/
+	async exec(opts) {
+		const disks = {};
+		for (const [relPath, mount] of Object.entries(opts.disks)) if (isExecMountSpec(mount)) {
+			const entry = {
+				disk: diskIdFromMount(mount.disk),
+				readOnly: mount.readOnly ?? false,
+				conditional: mount.conditional ?? false
+			};
+			if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
+			if (mount.queueMs !== void 0) entry.queueMs = mount.queueMs;
+			if (mount.checkoutPaths !== void 0) entry.checkoutPaths = mount.checkoutPaths;
+			disks[relPath] = entry;
+		} else disks[relPath] = diskIdFromMount(mount);
+		return unwrap(this._client.POST("/api/exec", { body: {
+			disks,
+			command: opts.command
+		} }));
+	}
+	/**
+	* Build an agent filesystem toolset spanning several disks at once. `mounts`
+	* maps a relative path to a disk (or `ExecMountSpec`), exactly like
+	* {@link exec}; each disk appears under `/mnt/archil/<path>`. Hand the result
+	* to a framework adapter (`createDiskTools(workspace)`) to get tools that route
+	* file operations by path and fan `grep`/`list_files` out across the disks.
+	*/
+	workspace(mounts) {
+		return new Workspace(this, mounts);
+	}
 };
-
-// src/index.ts
-var _options;
-var _instance;
+//#endregion
+//#region src/index.ts
+let _options;
+let _instance;
 function configure(options) {
-  _options = options;
-  _instance = void 0;
+	_options = options;
+	_instance = void 0;
 }
 function archil() {
-  if (!_instance) {
-    _instance = new Archil(_options);
-  }
-  return _instance;
+	if (!_instance) _instance = new Archil(_options);
+	return _instance;
 }
 function createDisk(req) {
-  return archil().disks.create(req);
+	return archil().disks.create(req);
 }
 function listDisks(opts) {
-  return archil().disks.list(opts);
+	return archil().disks.list(opts);
 }
 function getDisk(id) {
-  return archil().disks.get(id);
+	return archil().disks.get(id);
 }
 function listApiKeys(opts) {
-  return archil().tokens.list(opts);
+	return archil().tokens.list(opts);
 }
 function createApiKey(req) {
-  return archil().tokens.create(req);
+	return archil().tokens.create(req);
 }
 function deleteApiKey(id) {
-  return archil().tokens.delete(id);
+	return archil().tokens.delete(id);
 }
+/**
+* Run a command in a container with multiple disks mounted simultaneously,
+* each at its own relative path under `/mnt/archil`. Blocks until the
+* command completes and returns its stdout, stderr, exit code, and timing.
+*/
 function exec(opts) {
-  return archil().exec(opts);
+	return archil().exec(opts);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Archil,
-  ArchilApiError,
-  ArchilError,
-  ArchilS3Error,
-  Disk,
-  DiskMultipart,
-  Disks,
-  Tokens,
-  USER_AGENT,
-  VERSION,
-  configure,
-  createApiKey,
-  createDisk,
-  deleteApiKey,
-  effectiveUploadPartSize,
-  exec,
-  getDisk,
-  listApiKeys,
-  listDisks
-});
+/**
+* Build an agent filesystem toolset spanning several disks, using the
+* module-level client. See {@link Archil.workspace}.
+*/
+function workspace(mounts) {
+	return archil().workspace(mounts);
+}
+//#endregion
+exports.Archil = Archil;
+exports.ArchilApiError = ArchilApiError;
+exports.ArchilError = ArchilError;
+exports.ArchilS3Error = ArchilS3Error;
+exports.Disk = Disk;
+exports.DiskMultipart = DiskMultipart;
+exports.Disks = Disks;
+exports.Tokens = Tokens;
+exports.USER_AGENT = USER_AGENT;
+exports.VERSION = VERSION;
+exports.Workspace = Workspace;
+exports.configure = configure;
+exports.createApiKey = createApiKey;
+exports.createDisk = createDisk;
+exports.deleteApiKey = deleteApiKey;
+exports.effectiveUploadPartSize = effectiveUploadPartSize;
+exports.exec = exec;
+exports.getDisk = getDisk;
+exports.listApiKeys = listApiKeys;
+exports.listDisks = listDisks;
+exports.workspace = workspace;