@compforge/harness-toolbox 0.3.9 → 0.3.11

package/README.md

@@ -16,6 +16,48 @@ claiming snapshot consistency; callers supply cancellation and decide how to per
 Protocol adapters have separate entry points; importing lifecycle or transport contracts does
 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.
+
+```ts
+import { ClientManager, FileDataSource } from "@compforge/harness-common";
+import { LocalFileDataSource, PodFileDataSource } from "@compforge/harness-toolbox/file";
+
+const source = new LocalFileDataSource("./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));
+  }
+} finally {
+  await clients.dispose();
+}
+
+// `environment` is a KubernetesEnvironment (or an equivalent ClientProvider).
+// Resolve Workloads first and create one source per chosen Pod/container.
+const podSource = new PodFileDataSource(environment,
+  { namespace: "app", pod: "worker-abc", container: "worker" },
+  "/etc/app/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.
+
 ## Workload discovery
 
 Borrow a KubernetesClient through KubernetesEnvironment and the shared ClientManager lifecycle, then call
@@ -250,3 +292,13 @@ Disposal closes forwards and the exec stream; EOF closes remote listeners/connec
 connection is lost without EOF, a 30-second heartbeat lease bounds remote process lifetime.
 A dead relay invalidates its routes and fails callers; no SQL or other protocol operation is replayed.
 The root should finish or cancel protocol work before disposing the transport.
+
+### OpenSearch connection preparation
+
+`openOpenSearch` probes the resolved endpoint before returning. It tries the supplied TCP transports
+in order only for connection failures; HTTP authorization/server errors stop preparation, and failed
+reads are never replayed on another route. `onRoute` reports the selected transport and safe fallback
+reason. The caller owns shared transports such as `PodRelayTransport` and their cleanup.
+
+Routed HTTPS preserves the original TLS server name. Bun disables HTTP keep-alive because its reused
+socket recovery can replay a failed request below the driver; Node retains connection pooling.

package/dist/{chunk-zhkrydeg.js → chunk-20kv4wc3.js}

@@ -12,6 +12,9 @@ class ToolboxError extends Error {
 
 class KubernetesError extends ToolboxError {
 }
+
+class FileError extends ToolboxError {
+}
 function kubernetesHttpError(status) {
   const kind = {
     401: "authentication_failed",
@@ -38,4 +41,4 @@ function kubernetesCommandError(result) {
   return status ? kubernetesHttpError(status) : new KubernetesError("Kubernetes resource request failed", { kind: "operation_failed" });
 }
 
-export { ToolboxError, KubernetesError, kubernetesHttpError, kubernetesCommandError };
+export { ToolboxError, KubernetesError, FileError, kubernetesHttpError, kubernetesCommandError };

package/dist/{chunk-p6k59m3q.js → chunk-8axd2y2m.js}

@@ -1,6 +1,6 @@
 import {
   KubernetesError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 
 // src/kubernetes/workload.ts
 function failure(message, kind) {

package/dist/{chunk-w3a4p6jm.js → chunk-8mb6natq.js}

@@ -1,15 +1,30 @@
+import {
+  ToolboxError
+} from "./chunk-20kv4wc3.js";
+import {
+  isConnectionNetworkError
+} from "./chunk-h8fwx0k7.js";
+
 // src/opensearch/client.ts
-import { Client } from "@opensearch-project/opensearch";
+import { Client, Connection, errors } from "@opensearch-project/opensearch";
 function isOpenSearchReadApi(search) {
   return typeof search.request === "function";
 }
+
+class OpenSearchConnection extends Connection {
+  buildRequestObject(params) {
+    return { ...super.buildRequestObject(params), servername: this.ssl?.servername };
+  }
+}
 function createClient(options) {
   return new Client({
     node: options.node,
+    Connection: OpenSearchConnection,
     auth: options.auth.username && options.auth.password ? { username: options.auth.username, password: options.auth.password } : undefined,
-    ssl: { rejectUnauthorized: false },
+    ssl: { rejectUnauthorized: false, servername: options.servername },
     requestTimeout: options.requestTimeoutMs ?? 60000,
-    maxRetries: 0
+    maxRetries: 0,
+    agent: { keepAlive: !process.versions.bun }
   });
 }
 
@@ -36,8 +51,18 @@ class OpenSearchEngine {
     });
     return response.body;
   }
-  ping() {
-    return this.client.ping();
+  async ping(signal, timeoutMs) {
+    signal?.throwIfAborted();
+    const request = this.client.ping({}, timeoutMs === undefined ? undefined : { requestTimeout: timeoutMs });
+    const abort = () => {
+      request.abort?.();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      return await request;
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
   }
   close() {
     return this.client.close();
@@ -46,6 +71,7 @@ class OpenSearchEngine {
 
 class OpenSearchClient {
   source;
+  lifecycle;
   #controller = new AbortController;
   signal;
   #initialization;
@@ -54,6 +80,7 @@ class OpenSearchClient {
   #operations = new Set;
   constructor(source, lifecycle = {}) {
     this.source = source;
+    this.lifecycle = lifecycle;
     this.signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
   }
   initialize() {
@@ -61,15 +88,42 @@ class OpenSearchClient {
     return this.#initialization ??= (async () => {
       const target = await this.source.resolve();
       this.signal.throwIfAborted();
-      const transport = this.source.transports[0];
-      if (!transport || transport.kind !== "tcp")
-        throw new Error("OpenSearch requires a TCP transport");
-      const url = new URL(target.node);
-      const endpoint = await transport.connect({ host: url.hostname, port: Number(url.port || (url.protocol === "https:" ? 443 : 80)) });
-      this.signal.throwIfAborted();
-      url.hostname = endpoint.host;
-      url.port = String(endpoint.port);
-      this.#engine = new OpenSearchEngine({ ...target, node: url.toString() });
+      const original = new URL(target.node);
+      let reason;
+      for (const [index, transport] of this.source.transports.entries()) {
+        this.signal.throwIfAborted();
+        if (transport.kind !== "tcp")
+          throw new Error("OpenSearch requires a TCP transport");
+        let engine;
+        try {
+          const endpoint = await transport.connect({
+            host: original.hostname,
+            port: Number(original.port || (original.protocol === "https:" ? 443 : 80)),
+            servername: target.servername ?? original.hostname
+          });
+          this.signal.throwIfAborted();
+          const url = new URL(original);
+          url.hostname = endpoint.host;
+          url.port = String(endpoint.port);
+          engine = new OpenSearchEngine({ ...target, node: url.toString(), servername: endpoint.servername ?? target.servername ?? original.hostname });
+          await engine.ping(this.signal, target.connectTimeoutMs ?? target.requestTimeoutMs ?? 1e4);
+          this.signal.throwIfAborted();
+          this.lifecycle.onRoute?.({ transport: transport.name, reason });
+          this.#engine = engine;
+          return;
+        } catch (error) {
+          await engine?.close();
+          this.signal.throwIfAborted();
+          const network = isConnectionNetworkError(error);
+          if (!network && !(error instanceof errors.ConnectionError) && !(error instanceof errors.TimeoutError))
+            throw error;
+          reason = network ? String(error.code) : error.name;
+          if (index === this.source.transports.length - 1) {
+            throw new ToolboxError(`OpenSearch connect failed (${reason})`, { kind: "connection_failed", code: reason, cause: error });
+          }
+        }
+      }
+      throw new Error("OpenSearch DataSource has no transport");
     })();
   }
   #ready() {

package/dist/{chunk-fhtbvj0s.js → chunk-9n9z2pty.js}

@@ -2,7 +2,7 @@ import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-y94xq8b4.js → chunk-a1cb44ga.js}

@@ -1,15 +1,15 @@
+import {
+  resolveWorkload
+} from "./chunk-8axd2y2m.js";
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
 import {
   resourceAccess
-} from "./chunk-fhtbvj0s.js";
-import {
-  resolveWorkload
-} from "./chunk-p6k59m3q.js";
+} from "./chunk-9n9z2pty.js";
 import {
   KubernetesError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 import {
   KubectlExecutor
 } from "./chunk-hmah9t8e.js";

package/dist/chunk-ba883sdp.js

@@ -0,0 +1,60 @@
+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-ahc00qs5.js → chunk-h73h2b7y.js}

@@ -1,3 +1,7 @@
+import {
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "./chunk-m91t44jh.js";
 import {
   queryReadonlySession,
   validateQueryLimits
@@ -5,13 +9,9 @@ import {
 import {
   destroyMysqlConnection
 } from "./chunk-136egyff.js";
-import {
-  queryMysqlViaPod,
-  queryMysqlViaPodBatch
-} from "./chunk-m91t44jh.js";
 import {
   ToolboxError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/chunk-mxyvpy79.js

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,91 @@
+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 };

package/dist/datasource.js

@@ -6,7 +6,7 @@ import {
 import {
   KubernetesError,
   ToolboxError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 export {
   clientKey,
   ToolboxError,

package/dist/errors.d.ts

@@ -11,6 +11,8 @@ export declare class ToolboxError extends Error {
 }
 export declare class KubernetesError extends ToolboxError {
 }
+export declare class FileError extends ToolboxError {
+}
 export declare function kubernetesHttpError(status: number): KubernetesError;
 /**
  * Normalize a failed kubectl resource request at the transport boundary.

package/dist/errors.js

@@ -1,12 +1,14 @@
 import {
+  FileError,
   KubernetesError,
   ToolboxError,
   kubernetesCommandError,
   kubernetesHttpError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 export {
   kubernetesHttpError,
   kubernetesCommandError,
   ToolboxError,
-  KubernetesError
+  KubernetesError,
+  FileError
 };

package/dist/file/client.d.ts

@@ -0,0 +1,17 @@
+import type { FileClient, FileReadOptions } from "@compforge/harness-common";
+export interface FileClientOptions {
+    concurrency: number;
+}
+export declare function fileClientOptions(options: FileClientOptions): Readonly<FileClientOptions>;
+/** Shared limits and lifecycle; transports stream bytes and own per-read resource cleanup. */
+export declare abstract class BoundedFileClient implements FileClient {
+    #private;
+    readonly path: string;
+    constructor(path: 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>;
+    dispose(): Promise<void>;
+}

package/dist/file/client.js

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

package/dist/file/index.d.ts

@@ -0,0 +1,5 @@
+export { FileDataSource, type FileClient, type FileReadOptions } from "@compforge/harness-common";
+export { FileError } from "../errors";
+export type { FileClientOptions } from "./client";
+export { LocalFileDataSource, LocalFileClient } from "./local";
+export { PodFileDataSource, PodFileClient, type PodFileTarget } from "./pod";

package/dist/file/index.js

@@ -0,0 +1,24 @@
+import {
+  PodFileClient,
+  PodFileDataSource
+} from "../chunk-mxyvpy79.js";
+import {
+  LocalFileClient,
+  LocalFileDataSource
+} from "../chunk-ba883sdp.js";
+import"../chunk-mzdz6wwc.js";
+import {
+  FileError
+} from "../chunk-20kv4wc3.js";
+import"../chunk-v3hxvnrc.js";
+
+// src/file/index.ts
+import { FileDataSource } from "@compforge/harness-common";
+export {
+  PodFileDataSource,
+  PodFileClient,
+  LocalFileDataSource,
+  LocalFileClient,
+  FileError,
+  FileDataSource
+};

package/dist/file/local.d.ts

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

package/dist/file/local.js

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

package/dist/file/pod.d.ts

@@ -0,0 +1,31 @@
+import { FileDataSource, type ClientManager, type ClientProvider, type FileReadOptions } from "@compforge/harness-common";
+import type { KubernetesClient } from "../kubernetes/client";
+import { BoundedFileClient, type FileClientOptions } from "./client";
+export interface PodFileTarget {
+    namespace: string;
+    pod: string;
+    container: string;
+}
+export type PodFileAccess = Pick<KubernetesClient, "initialize" | "dispose" | "exec">;
+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>);
+    protected initializeAccess(): Promise<void>;
+    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+}
+/**
+ * @spec One explicit Pod/container/path per source; workload discovery and replica traversal belong to callers.
+ * @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 target: Readonly<PodFileTarget>;
+    readonly clientKey: string;
+    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, path: string, options: FileClientOptions);
+    createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): PodFileClient;
+}

package/dist/file/pod.js

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

package/dist/kubernetes/client.js

@@ -1,12 +1,12 @@
 import {
   KubernetesClient
-} from "../chunk-y94xq8b4.js";
+} from "../chunk-a1cb44ga.js";
+import"../chunk-8axd2y2m.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-fhtbvj0s.js";
-import"../chunk-p6k59m3q.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-9n9z2pty.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";
 import"../chunk-hmah9t8e.js";

package/dist/kubernetes/environment.js

@@ -1,15 +1,15 @@
 import {
   KubernetesClient
-} from "../chunk-y94xq8b4.js";
+} from "../chunk-a1cb44ga.js";
+import"../chunk-8axd2y2m.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-fhtbvj0s.js";
-import"../chunk-p6k59m3q.js";
+import"../chunk-9n9z2pty.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";
 import"../chunk-hmah9t8e.js";

package/dist/kubernetes/pod-log-datasource.js

@@ -8,7 +8,7 @@ import"../chunk-a9htb6cr.js";
 import {
   clientKey
 } from "../chunk-z5pm2emz.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts

package/dist/kubernetes/resources.js

@@ -1,7 +1,7 @@
 import {
   resourceAccess
-} from "../chunk-fhtbvj0s.js";
-import"../chunk-zhkrydeg.js";
+} from "../chunk-9n9z2pty.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {
   resourceAccess

package/dist/kubernetes/workload.js

@@ -1,7 +1,7 @@
 import {
   resolveWorkload
-} from "../chunk-p6k59m3q.js";
-import"../chunk-zhkrydeg.js";
+} from "../chunk-8axd2y2m.js";
+import"../chunk-20kv4wc3.js";
 export {
   resolveWorkload
 };

package/dist/mysql/client.js

@@ -2,11 +2,11 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-ahc00qs5.js";
+} from "../chunk-h73h2b7y.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-age65q4n.js";
 import"../chunk-136egyff.js";
-import"../chunk-m91t44jh.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/mysql/index.js

@@ -1,12 +1,3 @@
-import {
-  parseMysqlEnvTarget
-} from "../chunk-qq77x9ek.js";
-import {
-  limitedRows,
-  limitedStatement,
-  queryLimited
-} from "../chunk-1gyshqd9.js";
-import"../chunk-pfar9cm3.js";
 import {
   withReadScope
 } from "../chunk-4sqvppz7.js";
@@ -14,11 +5,20 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-ahc00qs5.js";
+} from "../chunk-h73h2b7y.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-age65q4n.js";
+import {
+  parseMysqlEnvTarget
+} from "../chunk-qq77x9ek.js";
+import {
+  limitedRows,
+  limitedStatement,
+  queryLimited
+} from "../chunk-1gyshqd9.js";
 import"../chunk-136egyff.js";
-import"../chunk-m91t44jh.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-pfar9cm3.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/opensearch/client.d.ts

@@ -9,6 +9,10 @@ export interface OpenSearchOptions {
     node: string;
     auth: OpenSearchAuth;
     requestTimeoutMs?: number;
+    /** Deadline for the initialization probe; query deadlines remain independent. */
+    connectTimeoutMs?: number;
+    /** Original TLS identity when a transport maps the socket to localhost. */
+    servername?: string;
 }
 export interface OpenSearchClientApi {
     count(params: Record<string, unknown>): Promise<{
@@ -19,7 +23,11 @@ export interface OpenSearchClientApi {
     search(params: Record<string, unknown>): Promise<{
         body: SearchResult;
     }>;
-    ping(params?: Record<string, unknown>): Promise<unknown>;
+    ping(params?: Record<string, unknown>, options?: {
+        requestTimeout?: number;
+    }): Promise<unknown> & {
+        abort?(): void;
+    };
     transport?: {
         request(params: {
             method: string;
@@ -43,12 +51,18 @@ export declare class OpenSearchEngine implements OpenSearchReadApi {
     count(index: string, query: SearchQuery): Promise<number>;
     search(index: string, body: SearchQuery): Promise<SearchResult>;
     request(path: string, query?: SearchQuery): Promise<unknown>;
-    ping(): Promise<unknown>;
+    ping(signal?: AbortSignal, timeoutMs?: number): Promise<unknown>;
     close(): Promise<void>;
 }
+/**
+ * @spec Only connection preparation may advance to another Transport; reads are never replayed.
+ * @why The official client connects lazily and wraps socket errors, so creating it does not prove reachability.
+ * @case id=opensearch_connect_fallback,desc=`Host cannot reach target`,expect=`Probe next TCP route`,forbid=`Replay a failed search`
+ */
 export declare class OpenSearchClient implements ManagedClient, OpenSearchReadApi {
     #private;
     private readonly source;
+    private readonly lifecycle;
     readonly signal: AbortSignal;
     constructor(source: ConnectionSource<OpenSearchOptions>, lifecycle?: ClientLifecycle);
     initialize(): Promise<void>;

package/dist/opensearch/client.js

@@ -3,7 +3,14 @@ import {
   OpenSearchEngine,
   isOpenSearchReadApi,
   openOpenSearch
-} from "../chunk-w3a4p6jm.js";
+} from "../chunk-8mb6natq.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   openOpenSearch,
   isOpenSearchReadApi,

package/dist/opensearch/index.js

@@ -1,9 +1,3 @@
-import {
-  OpenSearchClient,
-  OpenSearchEngine,
-  isOpenSearchReadApi,
-  openOpenSearch
-} from "../chunk-w3a4p6jm.js";
 import {
   searchAfterPages
 } from "../chunk-99p0zt4f.js";
@@ -11,6 +5,19 @@ import {
   parseOpenSearchEndpoint
 } from "../chunk-s1sjyem7.js";
 import"../chunk-djk4kmxb.js";
+import {
+  OpenSearchClient,
+  OpenSearchEngine,
+  isOpenSearchReadApi,
+  openOpenSearch
+} from "../chunk-8mb6natq.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   searchAfterPages,
   parseOpenSearchEndpoint,

package/dist/s3/datasource.js

@@ -2,7 +2,7 @@ import {
   S3DataSource
 } from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-20kv4wc3.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";

package/dist/s3/index.js

@@ -2,7 +2,7 @@ import {
   S3DataSource
 } from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
-import"../chunk-zhkrydeg.js";
+import"../chunk-20kv4wc3.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -88,6 +88,10 @@
     "./data-loader": {
       "types": "./dist/data-loader.d.ts",
       "import": "./dist/data-loader.js"
+    },
+    "./file": {
+      "types": "./dist/file/index.d.ts",
+      "import": "./dist/file/index.js"
     }
   },
   "files": [
@@ -95,7 +99,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@compforge/harness-common": "0.3.0",
+    "@compforge/harness-common": "0.5.3",
     "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
@@ -110,9 +114,6 @@
     "@types/node-fetch": "2.6.13",
     "@types/node": "^22"
   },
-  "overrides": {
-    "@compforge/harness-common": "file:../common"
-  },
   "publishConfig": {
     "access": "public"
   },