@compforge/harness-toolbox 0.4.0 → 0.4.2

package/README.md

@@ -18,45 +18,49 @@ not load database or Kubernetes drivers.
 
 ## File sources
 
-Use `LocalFileDataSource` for a local file or `PodFileDataSource` for a file in an explicit
-namespace/Pod/container. Both extend Common's `FileDataSource`, so a Service can store them directly
-as DataSources and consumers can recognize files with `instanceof FileDataSource`. No additional
-`id` or `kind` wrapper is required; consumer-owned selection names remain separate from client identity.
+A FileDataSource is a caller-declared acquisition group. Use `LocalFileDataSource` for local paths
+or `PodFileDataSource` for paths in one explicit namespace/Pod/container. Both extend Common's
+`FileDataSource`; no additional id/kind wrapper is required.
 
 ```ts
-import { ClientManager, FileDataSource } from "@compforge/harness-common";
+import { ClientManager } from "@compforge/harness-common";
 import { LocalFileDataSource, PodFileDataSource } from "@compforge/harness-toolbox/file";
 
-const source = new LocalFileDataSource("./config.yaml", { concurrency: 2 });
+const source = new LocalFileDataSource(["./config.yaml", "./secret/config.yaml"], { concurrency: 2 });
 const clients = new ClientManager();
 try {
-  if (source instanceof FileDataSource) {
-    const file = await clients.get(source);
-    const bytes = await file.read({ maxBytes: 1024 * 1024, timeoutMs: 15_000 });
-    console.log(source.path, new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  const file = await clients.get(source);
+  const results = await file.read({ maxBytes: 1024 * 1024, maxTotalBytes: 2 * 1024 * 1024, timeoutMs: 15_000 });
+  for (const result of results) {
+    if (result.status === "error") console.error(result.path, result.error.message);
+    else console.log(result.path, new TextDecoder("utf-8", { fatal: true }).decode(result.bytes));
   }
-} finally {
-  await clients.dispose();
-}
+} finally { await clients.dispose(); }
 
-// `environment` is a KubernetesEnvironment (or an equivalent ClientProvider).
-// Resolve Workloads first and create one source per chosen Pod/container.
+// Resolve Workloads first. This entire group is fetched through one exec session.
 const podSource = new PodFileDataSource(environment,
   { namespace: "app", pod: "worker-abc", container: "worker" },
-  "/etc/app/config.yaml", { concurrency: 2 });
+  ["/etc/app/config.yaml", "/etc/app/secret/config.yaml"], { concurrency: 2 });
 ```
 
-Each read reopens the file; the manager shares clients, not previous file contents. The byte limit
-rejects oversized reads, including a zero-byte limit on a nonempty file. Timeouts include queue time;
-caller cancellation and disposal cancel active reads. Keep the source path and Pod target with any
-persisted evidence. A successful read describes bytes at that location, not the application's parsed
-or effective configuration and not an atomic filesystem snapshot.
-
-Local files may be symlinks to regular files. Pod reads require `pods/exec` access and `head -c` in the
-selected container; paths are passed as argv without a shell. A Pod name is an access location, not
-a UID fence; callers needing incarnation guarantees must verify discovery around collection. Pod
-sources borrow Kubernetes access from the root manager and never close it themselves. Unsupported
-commands, missing paths and denied reads fail explicitly; they are not empty file results.
+Every read reopens all declared paths and returns one ordered result per path. Empty files succeed;
+missing, denied, nonregular and oversized files return individual errors with no partial bytes.
+An error in one file does not discard sibling results. Per-file limits reset for each path; the total
+budget bounds retained decoded bytes, including incomplete files. Queueing and the whole group
+share one deadline. Cancellation, total-budget exhaustion, deadline and transport/protocol failure
+reject the operation. Sources share clients, never previous file contents.
+
+Pod groups use one exec and require `sh`, `head -c`, `base64` and `tr`. Paths remain positional
+arguments even when they contain shell syntax or newlines. Indexed base64 records carry raw binary
+bytes plus each file's exit status; truncated or malformed records reject without replay. No remote
+temporary files are written. Local reads allow symlinks to regular files and reject nonregular files.
+Keep the path and Pod target on evidence; grouping guarantees neither an atomic filesystem snapshot
+nor application configuration precedence. A Pod name is not a UID fence; callers needing incarnation
+guarantees must check discovery around collection. File clients borrow root Kubernetes access and
+never close it themselves.
+
+Version 0.4.2 requires Common 0.5.4. Replace single path arguments with arrays, supply `maxTotalBytes`,
+and handle per-file results. Publish Common before Toolbox; this change has no single-file legacy adapter.
 
 ## Kubernetes resources
 
@@ -103,7 +107,23 @@ selectorless Services and failed access raise KubernetesError.
 
 The resource path uses client-node kubeconfig authentication/TLS and bounded native JSON reads,
 not kubectl error text. Configure request timeout, concurrency and response bytes with the
-client's ResourceLimits constructor argument. Existing exec/port-forward operations remain unchanged.
+client's ResourceLimits constructor argument. Native exec uses the same root capacity/byte policy
+with a separate slot pool; its per-call timeout defaults to that policy and covers queueing,
+authentication, upgrade and execution. Explicit per-call timeouts support longer commands.
+
+Exec requires `get pods/exec` permission for the WebSocket upgrade (kubectl/SPDY paths may use
+`create pods/exec`). It connects directly to the Pod exec WebSocket endpoint without a preliminary Pod GET or
+kubectl subprocess. Each command owns a stream session; failures are never retried or replayed.
+Kubeconfig controls authentication, TLS and proxy access. stdout/stderr and remote exit status
+remain separate; retained output and individual messages are bounded. Streaming callers may
+set `collectStdout: false` and enforce their own total byte budget. Root disposal cancels active
+and queued sessions. Protocol v4 is accepted for output-only commands; stdin requires v5 to
+close input without losing remaining output/status. Bun does not expose HTTP upgrade rejection
+status, so those failures retain an unknown connection error. Native exec with a kubeconfig
+proxy requires Node: Bun cannot reliably release proxy sockets or preserve TLS name overrides.
+It fails before opening a session on Bun; use Node or explicitly provide an Executor adapter.
+The transport never bypasses the proxy or TLS checks.
+Port-forward still uses kubectl.
 See [the shared Workload model](../../../docs/workload.md).
 
 ```ts

package/dist/{chunk-y529s0mz.js → chunk-8kts470p.js}

@@ -7,6 +7,9 @@ import {
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
+import {
+  KubernetesExecTransport
+} from "./chunk-shsabpc1.js";
 import {
   KubernetesError
 } from "./chunk-20kv4wc3.js";
@@ -24,11 +27,14 @@ class KubernetesClient {
   #forwarders = new Map;
   #operations = new Set;
   #disposal;
+  #exec;
+  #injectedExecutor;
   #resources;
   #transport;
   constructor(kube, signal, executor, resourceLimits = { timeoutMs: 30000, concurrency: 4, maxBytes: 8 * 1024 * 1024 }, resources) {
     this.kube = kube;
     this.resourceLimits = resourceLimits;
+    this.#injectedExecutor = executor;
     this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
     if (executor)
       this.#executors.set(kube.namespace, executor);
@@ -86,7 +92,7 @@ class KubernetesClient {
     };
   }
   exec(namespace, target, command, options) {
-    return this.#track(() => this.#executor(namespace).exec(target, command, this.#options(options)));
+    return this.#track(() => this.#injectedExecutor && namespace === this.kube.namespace ? this.#injectedExecutor.exec(target, command, this.#options(options)) : (this.#exec ??= new KubernetesExecTransport(this.kube, this.signal, this.resourceLimits)).exec(namespace, target, command, this.#options(options)));
   }
   forward(namespace, target) {
     return this.#track(async () => {

package/dist/chunk-grpygk6f.js

@@ -0,0 +1,157 @@
+import {
+  BoundedFileClient,
+  fileClientOptions,
+  filePaths
+} from "./chunk-kkts16w9.js";
+import {
+  FileError
+} from "./chunk-20kv4wc3.js";
+
+// src/file/pod.ts
+import { posix } from "node:path";
+import { clientKey, FileDataSource } from "@compforge/harness-common";
+var READ_FILES = String.raw`limit=$1
+shift
+index=0
+for path do
+  printf '%s ' "$index"
+  { if [ -f "$path" ]; then head -c "$limit" "$path" 2>/dev/null; status=$?; else status=1; fi
+    printf '\000%03d' "$status"
+  } | base64 | tr -d '\r\n'
+  printf '\n'
+  index=$((index + 1))
+done`;
+function fileRecords(paths, maxBytes, target, sink) {
+  let index = 0, header = "", started = false, carry = "", encodedSize = 0, padded = false;
+  let trailer = Buffer.alloc(0);
+  const maximumEncoded = Math.ceil((maxBytes + 5) / 3) * 4;
+  const invalid = () => new FileError("Invalid Pod file group response", { kind: "invalid_response" });
+  const body = (part) => {
+    if (padded && part)
+      throw invalid();
+    encodedSize += part.length;
+    if (encodedSize > maximumEncoded)
+      throw invalid();
+    const text = carry + part, end = text.length - text.length % 4;
+    carry = text.slice(end);
+    if (!end)
+      return;
+    const encoded = text.slice(0, end), decoded = Buffer.from(encoded, "base64");
+    if (decoded.toString("base64") !== encoded)
+      throw invalid();
+    padded = encoded.endsWith("=");
+    if (padded && carry)
+      throw invalid();
+    const bytes = Buffer.concat([trailer, decoded]);
+    if (bytes.length > 4)
+      sink.receive(index, bytes.subarray(0, -4));
+    trailer = Buffer.from(bytes.subarray(Math.max(0, bytes.length - 4)));
+  };
+  return {
+    receive(bytes) {
+      if (bytes.some((byte) => byte > 127))
+        throw invalid();
+      const text = Buffer.from(bytes).toString("ascii");
+      for (let offset = 0;offset < text.length; ) {
+        if (!started) {
+          const char = text[offset++];
+          if (char !== " ") {
+            if (!/\d/.test(char) || header.length >= String(paths.length).length)
+              throw invalid();
+            header += char;
+            continue;
+          }
+          if (index >= paths.length || header !== String(index))
+            throw invalid();
+          started = true;
+        }
+        const newline = text.indexOf(`
+`, offset);
+        body(text.slice(offset, newline < 0 ? text.length : newline));
+        if (newline < 0)
+          return;
+        if (carry || trailer.length !== 4 || trailer[0] !== 0)
+          throw invalid();
+        const status = trailer.subarray(1).toString("ascii");
+        if (!/^\d{3}$/.test(status) || Number(status) > 255)
+          throw invalid();
+        sink.complete(index, Number(status) === 0 ? undefined : new FileError(`Cannot read Pod file: ${target.namespace}/${target.pod}/${target.container} ${paths[index]}`, { kind: "operation_failed", code: Number(status) }));
+        index++;
+        header = "";
+        started = false;
+        encodedSize = 0;
+        padded = false;
+        trailer = Buffer.alloc(0);
+        offset = newline + 1;
+      }
+    },
+    finish() {
+      if (started || header || index !== paths.length)
+        throw invalid();
+    }
+  };
+}
+
+class PodFileClient extends BoundedFileClient {
+  target;
+  acquire;
+  #kubernetes;
+  constructor(paths, target, options, signal, acquire) {
+    super(paths, options, signal);
+    this.target = target;
+    this.acquire = acquire;
+  }
+  async initializeAccess() {
+    this.#kubernetes = await this.acquire();
+  }
+  async capture(signal, limits, sink) {
+    const abort = new AbortController;
+    const combined = AbortSignal.any([signal, abort.signal]);
+    const records = fileRecords(this.paths, limits.maxBytes, this.target, sink);
+    const result = await this.#kubernetes.exec(this.target.namespace, this.target, ["sh", "-c", READ_FILES, "file-source", String(limits.maxBytes + 1), ...this.paths], {
+      signal: combined,
+      timeoutMs: limits.timeoutMs,
+      collectStdout: false,
+      onStdoutBytes: (bytes) => {
+        if (combined.aborted)
+          return;
+        try {
+          records.receive(bytes);
+          combined.throwIfAborted();
+        } catch (error) {
+          abort.abort(error);
+        }
+      }
+    });
+    combined.throwIfAborted();
+    if (!result.ok)
+      throw new FileError(`Cannot acquire Pod file group: ${this.target.namespace}/${this.target.pod}/${this.target.container}`, { kind: result.timedOut ? "timeout" : "operation_failed", code: result.exitCode ?? undefined });
+    records.finish();
+  }
+}
+
+class PodFileDataSource extends FileDataSource {
+  kubernetes;
+  paths;
+  target;
+  clientKey;
+  #options;
+  constructor(kubernetes, target, paths, options) {
+    super();
+    this.kubernetes = kubernetes;
+    this.paths = filePaths(paths);
+    if (this.paths.some((path) => !posix.isAbsolute(path)))
+      throw new FileError("Pod file paths must be absolute", { kind: "invalid_argument" });
+    if ([target.namespace, target.pod, target.container].some((value) => !value.trim())) {
+      throw new FileError("Pod file namespace, Pod and Container are required", { kind: "invalid_argument" });
+    }
+    this.target = Object.freeze({ namespace: target.namespace, pod: target.pod, container: target.container });
+    this.#options = fileClientOptions(options);
+    this.clientKey = clientKey("pod-file", { access: kubernetes.clientKey, target: this.target, paths: this.paths, options: this.#options });
+  }
+  createClient(clients, signal) {
+    return new PodFileClient(this.paths, this.target, this.#options, signal, () => clients.get(this.kubernetes));
+  }
+}
+
+export { PodFileClient, PodFileDataSource };

package/dist/chunk-kkts16w9.js

@@ -0,0 +1,131 @@
+import {
+  FileError,
+  ToolboxError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/file/client.ts
+function fileClientOptions(options) {
+  if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1) {
+    throw new FileError("File concurrency must be a positive integer", { kind: "invalid_argument" });
+  }
+  return Object.freeze({ concurrency: options.concurrency });
+}
+function filePaths(paths) {
+  if (!paths.length || paths.some((path) => typeof path !== "string" || !path || path.includes("\x00")) || new Set(paths).size !== paths.length) {
+    throw new FileError("File paths must be nonempty, distinct and contain no NUL", { kind: "invalid_argument" });
+  }
+  return Object.freeze([...paths]);
+}
+
+class BoundedFileClient {
+  paths;
+  #controller = new AbortController;
+  #signal;
+  #pool;
+  #operations = new Set;
+  #ready = false;
+  #disposal;
+  constructor(paths, options, signal) {
+    this.paths = filePaths(paths);
+    this.#pool = new ConcurrencyPool(fileClientOptions(options).concurrency);
+    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+  }
+  async initialize() {
+    this.#signal.throwIfAborted();
+    await this.initializeAccess();
+    this.#signal.throwIfAborted();
+    this.#ready = true;
+  }
+  async initializeAccess() {}
+  async read(options) {
+    this.#signal.throwIfAborted();
+    if (!this.#ready)
+      throw new FileError("File client is not initialized", { kind: "operation_failed" });
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0 || options.maxBytes >= Number.MAX_SAFE_INTEGER - 5 || !Number.isSafeInteger(options.maxTotalBytes) || options.maxTotalBytes < 0 || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2147483647) {
+      throw new FileError("Invalid file group read limits", { kind: "invalid_argument" });
+    }
+    const controller = new AbortController;
+    const signal = AbortSignal.any([this.#signal, controller.signal, ...options.signal ? [options.signal] : []]);
+    const timer = setTimeout(() => controller.abort(new FileError("File group read timed out", { kind: "timeout" })), options.timeoutMs);
+    const operation = this.#pool.run(async () => {
+      const files = this.paths.map((path) => ({ path, chunks: [], size: 0, done: false, error: undefined }));
+      let retained = 0;
+      const discard = (file, error) => {
+        retained -= file.size;
+        file.size = 0;
+        file.chunks = [];
+        file.error ??= error;
+      };
+      const entry = (index) => {
+        const file = files[index];
+        if (!file || file.done)
+          throw new FileError("Invalid file group response", { kind: "invalid_response" });
+        return file;
+      };
+      const sink = {
+        receive: (index, bytes) => {
+          if (signal.aborted)
+            return;
+          const file = entry(index);
+          if (file.error)
+            return;
+          if (bytes.byteLength > options.maxBytes - file.size) {
+            discard(file, new FileError(`File exceeds ${options.maxBytes} bytes: ${file.path}`, { kind: "limit_exceeded" }));
+          } else if (bytes.byteLength > options.maxTotalBytes - retained) {
+            controller.abort(new FileError(`File group exceeds ${options.maxTotalBytes} bytes`, { kind: "limit_exceeded" }));
+          } else {
+            file.chunks.push(Uint8Array.from(bytes));
+            file.size += bytes.byteLength;
+            retained += bytes.byteLength;
+          }
+        },
+        complete: (index, error) => {
+          if (signal.aborted)
+            return;
+          const file = entry(index);
+          if (error)
+            discard(file, error);
+          file.done = true;
+        }
+      };
+      await this.capture(signal, options, sink);
+      signal.throwIfAborted();
+      if (files.some((file) => !file.done))
+        throw new FileError("Incomplete file group response", { kind: "invalid_response" });
+      return files.map((file) => {
+        if (file.error)
+          return { path: file.path, status: "error", error: file.error };
+        const bytes = new Uint8Array(file.size);
+        let offset = 0;
+        for (const chunk of file.chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        return { path: file.path, status: "ok", bytes };
+      });
+    }, signal);
+    this.#operations.add(operation);
+    try {
+      return await operation;
+    } catch (cause) {
+      signal.throwIfAborted();
+      if (cause instanceof ToolboxError)
+        throw cause;
+      throw new FileError("Cannot acquire file group", { kind: "operation_failed", cause });
+    } finally {
+      clearTimeout(timer);
+      this.#operations.delete(operation);
+    }
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("File client disposed"));
+      await Promise.allSettled(this.#operations);
+    })();
+  }
+}
+
+export { fileClientOptions, filePaths, BoundedFileClient };

package/dist/chunk-shsabpc1.js

@@ -0,0 +1,267 @@
+import {
+  KubernetesError,
+  kubernetesHttpError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/kubernetes/exec-transport.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import WebSocket from "ws";
+class KubernetesExecTransport {
+  signal;
+  limits;
+  #config = new KubeConfig;
+  #capacity;
+  #server;
+  constructor(options, signal, limits) {
+    this.signal = signal;
+    this.limits = limits;
+    if (!Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new KubernetesError("Exec limits must be positive integers", { kind: "invalid_argument" });
+    }
+    if (options.kubeconfig)
+      this.#config.loadFromFile(options.kubeconfig);
+    else
+      this.#config.loadFromDefault();
+    if (options.context)
+      this.#config.setCurrentContext(options.context);
+    const cluster = this.#config.getCurrentCluster();
+    if (!cluster)
+      throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+    if (process.versions.bun && cluster.proxyUrl) {
+      throw new KubernetesError("Native exec through a kubeconfig proxy requires a Node host", { kind: "unsupported_operation" });
+    }
+    this.#server = cluster.server.replace(/\/$/, "");
+    if (new URL(cluster.server).protocol === "http:")
+      this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+    this.#capacity = new ConcurrencyPool(limits.concurrency);
+  }
+  async exec(namespace, target, command, options = {}) {
+    const started = performance.now();
+    const timeoutMs = options.timeoutMs ?? this.limits.timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || !namespace || !target.pod || !command.length) {
+      throw new KubernetesError("Exec requires a namespace, Pod, command and positive timeout", { kind: "invalid_argument" });
+    }
+    const caller = options.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal;
+    const deadline = new AbortController;
+    const signal = AbortSignal.any([caller, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    try {
+      return await this.#capacity.run(() => this.#session(namespace, target, command, options, signal, started, deadline.signal), signal);
+    } catch (error) {
+      if (caller.aborted)
+        throw caller.reason;
+      if (deadline.signal.aborted)
+        return this.#result(namespace, target, command, started, null, "", "Exec deadline exceeded", true);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #result(namespace, target, command, started, exitCode, stdout, stderr, timedOut = false) {
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      durationMs: performance.now() - started,
+      command: [
+        "kubernetes-api",
+        "exec",
+        "-n",
+        namespace,
+        target.pod,
+        ...target.container ? ["-c", target.container] : [],
+        "--",
+        ...command
+      ]
+    };
+  }
+  #session(namespace, target, command, options, signal, started, deadline) {
+    return new Promise((resolve, reject) => {
+      let socket;
+      let agent;
+      let input;
+      let settled = false;
+      let stdout = "", stderr = "", retained = 0;
+      const outDecoder = new TextDecoder, errDecoder = new TextDecoder;
+      const finish = (exitCode, error) => {
+        if (settled)
+          return;
+        settled = true;
+        signal.removeEventListener("abort", abort);
+        socket?.terminate();
+        agent?.destroy();
+        input?.cancel().catch(() => {});
+        const tail = outDecoder.decode(), errTail = errDecoder.decode();
+        if (options.collectStdout !== false)
+          stdout += tail;
+        stderr += errTail;
+        try {
+          if (tail)
+            options.onStdout?.(tail);
+          if (errTail)
+            options.onStderr?.(errTail);
+        } catch (cause) {
+          error ??= cause instanceof Error ? cause : new Error("Exec output callback failed");
+        }
+        if (error)
+          reject(error);
+        else
+          resolve(this.#result(namespace, target, command, started, exitCode, stdout, stderr, deadline.aborted));
+      };
+      const abort = () => {
+        if (deadline.aborted) {
+          stderr += `
+Exec deadline exceeded`;
+          finish(null);
+        } else
+          finish(null, signal.reason instanceof Error ? signal.reason : new Error("Exec aborted"));
+      };
+      const fail = (kind, cause) => finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} failed`, { kind, cause }));
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
+      const request = { headers: {} };
+      this.#config.applyToHTTPSOptions(request).then(() => {
+        agent = request.agent;
+        if (settled || signal.aborted) {
+          agent?.destroy();
+          return;
+        }
+        const url = new URL(`${this.#server}/api/v1/namespaces/${encodeURIComponent(namespace)}/pods/${encodeURIComponent(target.pod)}/exec`);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        for (const arg of command)
+          url.searchParams.append("command", arg);
+        url.searchParams.set("stdout", "true");
+        url.searchParams.set("stderr", "true");
+        url.searchParams.set("stdin", String(options.stdin !== undefined));
+        url.searchParams.set("tty", "false");
+        if (target.container)
+          url.searchParams.set("container", target.container);
+        socket = new WebSocket(url, options.stdin === undefined ? ["v5.channel.k8s.io", "v4.channel.k8s.io"] : ["v5.channel.k8s.io"], { ...request, ...process.versions.bun ? { tls: {
+          ca: request.ca,
+          cert: request.cert,
+          key: request.key,
+          pfx: request.pfx,
+          passphrase: request.passphrase,
+          rejectUnauthorized: request.rejectUnauthorized,
+          serverName: request.servername
+        } } : {}, maxPayload: this.limits.maxBytes, handshakeTimeout: this.limits.timeoutMs });
+        if (!process.versions.bun)
+          socket.on("unexpected-response", (request2, response) => {
+            const status = response.statusCode ?? 500;
+            response.destroy();
+            request2.destroy();
+            const failure = kubernetesHttpError(status);
+            finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} HTTP ${status}`, {
+              kind: failure.kind,
+              code: status
+            }));
+          });
+        socket.on("error", (error) => fail("connection_failed", error));
+        socket.on("close", () => {
+          if (!settled)
+            fail("connection_lost");
+        });
+        socket.on("message", (data, binary) => {
+          if (settled)
+            return;
+          try {
+            if (!binary)
+              throw new Error("Exec frame must be binary");
+            const frame = Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+            if (!frame.length)
+              throw new Error("Empty exec frame");
+            if (frame.length > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            const channel = frame[0], payload = frame.subarray(1);
+            if (channel === 255) {
+              if (payload.length !== 1 || ![0, 1, 2].includes(payload[0]))
+                throw new Error("Invalid channel close");
+              return;
+            }
+            if (channel === 3) {
+              const status = JSON.parse(payload.toString("utf8"));
+              if (status.status === "Success") {
+                finish(0);
+                return;
+              }
+              const code = status.details?.causes?.find((cause) => cause.reason === "ExitCode")?.message;
+              if (status.status !== "Failure" || !/^\d+$/.test(code ?? ""))
+                throw new Error("Exec status lacks exit code");
+              if (!Number.isSafeInteger(Number(code)))
+                throw new Error("Invalid exit code");
+              finish(Number(code));
+              return;
+            }
+            if (channel !== 1 && channel !== 2)
+              throw new Error("Invalid exec channel");
+            if (channel === 2 || options.collectStdout !== false)
+              retained += payload.length;
+            if (retained > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            if (channel === 1) {
+              options.onStdoutBytes?.(payload);
+              const text = outDecoder.decode(payload, { stream: true });
+              if (options.collectStdout !== false)
+                stdout += text;
+              options.onStdout?.(text);
+            } else {
+              const text = errDecoder.decode(payload, { stream: true });
+              stderr += text;
+              options.onStderr?.(text);
+            }
+          } catch (error) {
+            fail("invalid_response", error);
+          }
+        });
+        socket.on("open", () => {
+          if (options.stdin === undefined || settled)
+            return;
+          const send = (bytes) => new Promise((done, failed) => {
+            if (settled) {
+              failed(new Error("Exec closed"));
+              return;
+            }
+            socket.send(Buffer.concat([Buffer.from([0]), bytes]), (error) => error ? failed(error) : done());
+          });
+          (async () => {
+            const stdin = options.stdin;
+            if (typeof stdin === "string" || stdin instanceof Uint8Array)
+              await send(typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin);
+            else {
+              const reader = stdin.getReader();
+              input = reader;
+              while (!settled) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                  break;
+                await send(chunk.value);
+              }
+            }
+            if (!settled)
+              socket.send(Buffer.from([255, 0]));
+          })().catch((error) => {
+            if (!settled)
+              fail("connection_failed", error);
+          });
+        });
+      }).catch((error) => {
+        if (!settled)
+          fail("connection_failed", error);
+      });
+    });
+  }
+}
+
+export { KubernetesExecTransport };

package/dist/chunk-sqbew04a.js

@@ -0,0 +1,65 @@
+import {
+  BoundedFileClient,
+  fileClientOptions,
+  filePaths
+} from "./chunk-kkts16w9.js";
+import {
+  FileError
+} from "./chunk-20kv4wc3.js";
+
+// src/file/local.ts
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { clientKey, FileDataSource } from "@compforge/harness-common";
+class LocalFileClient extends BoundedFileClient {
+  async capture(signal, limits, sink) {
+    for (const [index, path] of this.paths.entries()) {
+      try {
+        signal.throwIfAborted();
+        const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        try {
+          signal.throwIfAborted();
+          if (!(await file.stat()).isFile())
+            throw new FileError(`Not a regular file: ${path}`, { kind: "unsupported_operation" });
+          const stream = file.createReadStream({
+            autoClose: false,
+            signal,
+            end: limits.maxBytes,
+            highWaterMark: Math.min(limits.maxBytes + 1, 64 * 1024)
+          });
+          for await (const bytes of stream)
+            sink.receive(index, bytes);
+        } finally {
+          await file.close();
+        }
+        sink.complete(index);
+      } catch (cause) {
+        signal.throwIfAborted();
+        const code = cause?.code;
+        sink.complete(index, cause instanceof FileError ? cause : new FileError(`Cannot read local file: ${path}`, {
+          kind: code === "ENOENT" || code === "ENOTDIR" ? "resource_not_found" : code === "EACCES" || code === "EPERM" ? "permission_denied" : "operation_failed",
+          code,
+          cause
+        }));
+      }
+    }
+  }
+}
+
+class LocalFileDataSource extends FileDataSource {
+  paths;
+  clientKey;
+  #options;
+  constructor(paths, options) {
+    super();
+    this.paths = filePaths(filePaths(paths).map((path) => resolve(path)));
+    this.#options = fileClientOptions(options);
+    this.clientKey = clientKey("local-file", { paths: this.paths, options: this.#options });
+  }
+  createClient(_clients, signal) {
+    return new LocalFileClient(this.paths, this.#options, signal);
+  }
+}
+
+export { LocalFileClient, LocalFileDataSource };

package/dist/file/client.d.ts

@@ -1,17 +1,22 @@
-import type { FileClient, FileReadOptions } from "@compforge/harness-common";
+import type { FileClient, FileReadOptions, FileReadResult } from "@compforge/harness-common";
 export interface FileClientOptions {
     concurrency: number;
 }
+export interface FileCaptureSink {
+    receive(index: number, bytes: Uint8Array): void;
+    complete(index: number, error?: Error): void;
+}
 export declare function fileClientOptions(options: FileClientOptions): Readonly<FileClientOptions>;
-/** Shared limits and lifecycle; transports stream bytes and own per-read resource cleanup. */
+export declare function filePaths(paths: readonly string[]): readonly string[];
+/** Group lifecycle and budgets; a per-file failure releases its partial bytes and preserves sibling results. */
 export declare abstract class BoundedFileClient implements FileClient {
     #private;
-    readonly path: string;
-    constructor(path: string, options: FileClientOptions, signal: AbortSignal);
+    readonly paths: readonly string[];
+    constructor(paths: readonly string[], options: FileClientOptions, signal: AbortSignal);
     initialize(): Promise<void>;
     protected initializeAccess(): Promise<void>;
-    protected abstract capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
-    /** @spec Limits apply while streaming; a failed read never publishes partial bytes. */
-    read(options: FileReadOptions): Promise<Uint8Array>;
+    protected abstract capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
+    /** @spec Enforce budgets while streaming; file failures discard only that file, never publish partial bytes. */
+    read(options: FileReadOptions): Promise<readonly FileReadResult[]>;
     dispose(): Promise<void>;
 }

package/dist/file/client.js

@@ -1,10 +1,12 @@
 import {
   BoundedFileClient,
-  fileClientOptions
-} from "../chunk-mzdz6wwc.js";
+  fileClientOptions,
+  filePaths
+} from "../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {
+  filePaths,
   fileClientOptions,
   BoundedFileClient
 };

package/dist/file/index.d.ts

@@ -1,4 +1,4 @@
-export { FileDataSource, type FileClient, type FileReadOptions } from "@compforge/harness-common";
+export { FileDataSource, type FileClient, type FileReadOptions, type FileReadResult } from "@compforge/harness-common";
 export { FileError } from "../errors";
 export type { FileClientOptions } from "./client";
 export { LocalFileDataSource, LocalFileClient } from "./local";

package/dist/file/index.js

@@ -1,12 +1,12 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
+} from "../chunk-grpygk6f.js";
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import {
   FileError
 } from "../chunk-20kv4wc3.js";

package/dist/file/local.d.ts

@@ -1,13 +1,13 @@
 import { FileDataSource, type ClientManager, type FileReadOptions } from "@compforge/harness-common";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export declare class LocalFileClient extends BoundedFileClient {
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
-/** @spec Resolve relative paths once at declaration; reads reopen the path to observe replaced mounted files. */
+/** @spec Resolve paths once at declaration; each group read reopens them to observe replaced mounted files. */
 export declare class LocalFileDataSource extends FileDataSource<LocalFileClient> {
     #private;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly clientKey: string;
-    constructor(path: string, options: FileClientOptions);
+    constructor(paths: readonly string[], options: FileClientOptions);
     createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): LocalFileClient;
 }

package/dist/file/local.js

@@ -1,8 +1,8 @@
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/file/pod.d.ts

@@ -1,6 +1,6 @@
 import { FileDataSource, type ClientManager, type ClientProvider, type FileReadOptions } from "@compforge/harness-common";
 import type { KubernetesClient } from "../kubernetes/client";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export interface PodFileTarget {
     namespace: string;
     pod: string;
@@ -11,21 +11,22 @@ export declare class PodFileClient extends BoundedFileClient {
     #private;
     readonly target: Readonly<PodFileTarget>;
     private readonly acquire;
-    constructor(path: string, target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
+    constructor(paths: readonly string[], target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
     protected initializeAccess(): Promise<void>;
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    /** @spec The whole declared group uses exactly one exec; file failures are records, never implicit retries. */
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
 /**
- * @spec One explicit Pod/container/path per source; workload discovery and replica traversal belong to callers.
+ * @spec One explicit Pod/container and one caller-declared acquisition group; discovery belongs to consumers.
  * @rule Borrow Kubernetes access from the root manager; file clients never dispose that shared dependency.
  * @see {@link component://../../../docs/toolbox.md}
  */
 export declare class PodFileDataSource extends FileDataSource<PodFileClient> {
     #private;
     private readonly kubernetes;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly target: Readonly<PodFileTarget>;
     readonly clientKey: string;
-    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, path: string, options: FileClientOptions);
+    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, paths: readonly string[], options: FileClientOptions);
     createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): PodFileClient;
 }

package/dist/file/pod.js

@@ -1,8 +1,8 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-grpygk6f.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/kubernetes/client.js

@@ -1,12 +1,13 @@
 import {
   KubernetesClient
-} from "../chunk-y529s0mz.js";
+} from "../chunk-8kts470p.js";
 import"../chunk-4ms037k2.js";
 import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
 import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";

package/dist/kubernetes/environment.js

@@ -1,12 +1,13 @@
 import {
   KubernetesClient
-} from "../chunk-y529s0mz.js";
+} from "../chunk-8kts470p.js";
 import"../chunk-4ms037k2.js";
 import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
 import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";

package/dist/kubernetes/exec-transport.d.ts

@@ -0,0 +1,19 @@
+import type { ExecTarget, ExecResult, RunOptions } from "./executor";
+import type { KubernetesConnectionOptions } from "./resource-transport";
+export interface KubernetesExecLimits {
+    timeoutMs: number;
+    concurrency: number;
+    maxBytes: number;
+}
+/**
+ * @spec Each exec owns one channel session; it is never retried or replayed.
+ * @rule The root owns configuration and capacity. Deadlines cover queueing, auth, upgrade and execution.
+ * @why A WebSocket upgrade cannot reuse an ordinary HTTP request connection as another exec session.
+ */
+export declare class KubernetesExecTransport {
+    #private;
+    private readonly signal;
+    private readonly limits;
+    constructor(options: KubernetesConnectionOptions, signal: AbortSignal, limits: KubernetesExecLimits);
+    exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<ExecResult>;
+}

package/dist/kubernetes/exec-transport.js

@@ -0,0 +1,8 @@
+import {
+  KubernetesExecTransport
+} from "../chunk-shsabpc1.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-v3hxvnrc.js";
+export {
+  KubernetesExecTransport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -99,23 +99,22 @@
     "README.md"
   ],
   "dependencies": {
-    "@compforge/harness-common": "0.5.3",
+    "@compforge/harness-common": "0.5.4",
     "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",
     "@smithy/node-http-handler": "4.12.1",
     "mysql2": "3.23.1",
-    "node-fetch": "2.7.0"
+    "node-fetch": "2.7.0",
+    "ws": "8.21.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.6.0",
     "@types/node-fetch": "2.6.13",
-    "@types/node": "^22"
-  },
-  "overrides": {
-    "@compforge/harness-common": "file:../common"
+    "@types/node": "^22",
+    "@types/ws": "^8.18.1"
   },
   "publishConfig": {
     "access": "public"

package/dist/chunk-ba883sdp.js

@@ -1,60 +0,0 @@
-import {
-  BoundedFileClient,
-  fileClientOptions
-} from "./chunk-mzdz6wwc.js";
-import {
-  FileError
-} from "./chunk-20kv4wc3.js";
-
-// src/file/local.ts
-import { constants } from "node:fs";
-import { open } from "node:fs/promises";
-import { resolve } from "node:path";
-import { clientKey, FileDataSource } from "@compforge/harness-common";
-class LocalFileClient extends BoundedFileClient {
-  async capture(signal, limits, receive) {
-    try {
-      const file = await open(this.path, constants.O_RDONLY | constants.O_NONBLOCK);
-      try {
-        signal.throwIfAborted();
-        if (!(await file.stat()).isFile()) {
-          throw new FileError(`Not a regular file: ${this.path}`, { kind: "unsupported_operation" });
-        }
-        const stream = file.createReadStream({ autoClose: false, signal, highWaterMark: Math.min(limits.maxBytes + 1, 64 * 1024) });
-        for await (const bytes of stream)
-          receive(bytes);
-      } finally {
-        await file.close();
-      }
-    } catch (cause) {
-      signal.throwIfAborted();
-      if (cause instanceof FileError)
-        throw cause;
-      const code = cause?.code;
-      throw new FileError(`Cannot read local file: ${this.path}`, {
-        kind: code === "ENOENT" || code === "ENOTDIR" ? "resource_not_found" : code === "EACCES" || code === "EPERM" ? "permission_denied" : "operation_failed",
-        code,
-        cause
-      });
-    }
-  }
-}
-
-class LocalFileDataSource extends FileDataSource {
-  path;
-  clientKey;
-  #options;
-  constructor(path, options) {
-    super();
-    if (!path || path.includes("\x00"))
-      throw new FileError("File path must be nonempty and contain no NUL", { kind: "invalid_argument" });
-    this.path = resolve(path);
-    this.#options = fileClientOptions(options);
-    this.clientKey = clientKey("local-file", { path: this.path, options: this.#options });
-  }
-  createClient(_clients, signal) {
-    return new LocalFileClient(this.path, this.#options, signal);
-  }
-}
-
-export { LocalFileClient, LocalFileDataSource };

package/dist/chunk-mxyvpy79.js

@@ -1,62 +0,0 @@
-import {
-  BoundedFileClient,
-  fileClientOptions
-} from "./chunk-mzdz6wwc.js";
-import {
-  FileError
-} from "./chunk-20kv4wc3.js";
-
-// src/file/pod.ts
-import { posix } from "node:path";
-import { clientKey, FileDataSource } from "@compforge/harness-common";
-class PodFileClient extends BoundedFileClient {
-  target;
-  acquire;
-  #kubernetes;
-  constructor(path, target, options, signal, acquire) {
-    super(path, options, signal);
-    this.target = target;
-    this.acquire = acquire;
-  }
-  async initializeAccess() {
-    this.#kubernetes = await this.acquire();
-  }
-  async capture(signal, limits, receive) {
-    const result = await this.#kubernetes.exec(this.target.namespace, this.target, ["head", "-c", String(limits.maxBytes + 1), this.path], { signal, timeoutMs: limits.timeoutMs, collectStdout: false, onStdoutBytes: receive });
-    signal.throwIfAborted();
-    if (!result.ok)
-      throw new FileError(`Cannot read Pod file: ${this.target.namespace}/${this.target.pod}/${this.target.container} ${this.path}`, { kind: result.timedOut ? "timeout" : "operation_failed", code: result.exitCode ?? undefined });
-  }
-}
-
-class PodFileDataSource extends FileDataSource {
-  kubernetes;
-  path;
-  target;
-  clientKey;
-  #options;
-  constructor(kubernetes, target, path, options) {
-    super();
-    this.kubernetes = kubernetes;
-    if (!posix.isAbsolute(path) || path.includes("\x00")) {
-      throw new FileError("Pod file path must be absolute and contain no NUL", { kind: "invalid_argument" });
-    }
-    if ([target.namespace, target.pod, target.container].some((value) => !value.trim())) {
-      throw new FileError("Pod file namespace, Pod and Container are required", { kind: "invalid_argument" });
-    }
-    this.path = path;
-    this.target = Object.freeze({ namespace: target.namespace, pod: target.pod, container: target.container });
-    this.#options = fileClientOptions(options);
-    this.clientKey = clientKey("pod-file", {
-      access: kubernetes.clientKey,
-      target: this.target,
-      path: this.path,
-      options: this.#options
-    });
-  }
-  createClient(clients, signal) {
-    return new PodFileClient(this.path, this.target, this.#options, signal, () => clients.get(this.kubernetes));
-  }
-}
-
-export { PodFileClient, PodFileDataSource };

package/dist/chunk-mzdz6wwc.js

@@ -1,91 +0,0 @@
-import {
-  FileError,
-  ToolboxError
-} from "./chunk-20kv4wc3.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
-
-// src/file/client.ts
-function fileClientOptions(options) {
-  if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1) {
-    throw new FileError("File concurrency must be a positive integer", { kind: "invalid_argument" });
-  }
-  return Object.freeze({ concurrency: options.concurrency });
-}
-
-class BoundedFileClient {
-  path;
-  #controller = new AbortController;
-  #signal;
-  #pool;
-  #operations = new Set;
-  #ready = false;
-  #disposal;
-  constructor(path, options, signal) {
-    this.path = path;
-    this.#pool = new ConcurrencyPool(fileClientOptions(options).concurrency);
-    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
-  }
-  async initialize() {
-    this.#signal.throwIfAborted();
-    await this.initializeAccess();
-    this.#signal.throwIfAborted();
-    this.#ready = true;
-  }
-  async initializeAccess() {}
-  async read(options) {
-    this.#signal.throwIfAborted();
-    if (!this.#ready)
-      throw new FileError(`File client is not initialized: ${this.path}`, { kind: "operation_failed" });
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0 || options.maxBytes === Number.MAX_SAFE_INTEGER || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2147483647) {
-      throw new FileError(`Invalid file read limits: ${this.path}`, { kind: "invalid_argument" });
-    }
-    const { maxBytes, timeoutMs } = options;
-    const controller = new AbortController;
-    const signal = AbortSignal.any([this.#signal, controller.signal, ...options.signal ? [options.signal] : []]);
-    const timer = setTimeout(() => controller.abort(new FileError(`File read timed out: ${this.path}`, { kind: "timeout" })), timeoutMs);
-    const operation = this.#pool.run(async () => {
-      const chunks = [];
-      let size = 0;
-      await this.capture(signal, { maxBytes, timeoutMs }, (bytes) => {
-        if (signal.aborted)
-          return;
-        if (bytes.byteLength > maxBytes - size) {
-          controller.abort(new FileError(`File exceeds ${maxBytes} bytes: ${this.path}`, { kind: "limit_exceeded" }));
-          return;
-        }
-        chunks.push(Uint8Array.from(bytes));
-        size += bytes.byteLength;
-      });
-      signal.throwIfAborted();
-      const result = new Uint8Array(size);
-      let offset = 0;
-      for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.byteLength;
-      }
-      return result;
-    }, signal);
-    this.#operations.add(operation);
-    try {
-      return await operation;
-    } catch (cause) {
-      signal.throwIfAborted();
-      if (cause instanceof ToolboxError)
-        throw cause;
-      throw new FileError(`Cannot read file: ${this.path}`, { kind: "operation_failed", cause });
-    } finally {
-      clearTimeout(timer);
-      this.#operations.delete(operation);
-    }
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error(`File client disposed: ${this.path}`));
-      await Promise.allSettled(this.#operations);
-    })();
-  }
-}
-
-export { fileClientOptions, BoundedFileClient };