@compforge/harness-toolbox 0.1.2 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # Harness Toolbox
 
-Client, DataSource and ClientManager are owned by the sibling TypeScript package
+Client, ClientProvider, DataSource, EnvironmentContext and ClientManager are owned by the sibling TypeScript package
 `@compforge/harness-common`. Toolbox provides protocol implementations and transports;
 its lifecycle entrypoints re-export the same common symbols.
 
@@ -12,20 +12,77 @@ The package supports Node.js 22+ and Bun. Install with `npm install @compforge/h
 Protocol adapters have separate entry points; importing lifecycle or transport contracts does
 not load database or Kubernetes drivers.
 
-A `DataSource` identifies a reusable client and constructs it. The `Client` owns initialization
+## Workload discovery
+
+Borrow a KubernetesClient through KubernetesEnvironment and the shared ClientManager lifecycle, then call
+`client.resolveWorkload(workload, environmentId)`. The ID is a stable target identity from your
+environment registry, not a display name or kubeconfig path. The Workload's namespace overrides the client's default.
+Resource, Service selector and labels locations return all matching Pod incarnations without
+readiness filtering; successful empty discovery returns an empty array. Missing resources,
+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.
+See [the shared Workload model](../../../docs/workload.md).
+
+```ts
+import { ClientManager, EnvironmentContext } from "@compforge/harness-toolbox";
+import { KubernetesEnvironment } from "@compforge/harness-toolbox/kubernetes/environment";
+
+const clients = new ClientManager();
+try {
+  const ctx = new EnvironmentContext(
+    new KubernetesEnvironment("dev",
+      { kubeconfig: "/config/cluster", context: "dev", namespace: "app" },
+      { timeoutMs: 10_000, concurrency: 4, maxBytes: 8 * 1024 * 1024 }),
+    clients, performance.now() + 30_000,
+  );
+  const kube = await ctx.clients.get(ctx.environment);
+  const pods = await kube.resolveWorkload({
+    name: "api", platform: "kubernetes",
+    location: { kind: "resource", resource_kind: "Deployment", name: "api" },
+  }, "cluster-a/runtime");
+} finally {
+  await clients.dispose();
+}
+```
+
+The context does not cancel work automatically. Its budget is available as remainingMs;
+the root owns cancellation and must join child work before disposing clients.
+
+Catch ToolboxError from the root entry or `@compforge/harness-toolbox/errors`; use `kind` and
+`code` for decisions. Native `cause` may contain sensitive details and is debug-only.
+
+For coordinated common/toolbox development, install and build common before installing toolbox:
+
+```sh
+# From sdks/typescript/toolbox
+(cd ../common && bun install --frozen-lockfile && make build)
+bun install --frozen-lockfile
+make lint
+make test
+```
+
+The toolbox root override resolves common from `../common` only for local development;
+the published dependency remains a registry version. Publish common before toolbox.
+The Makefile builds common before typechecking or building toolbox.
+
+A `ClientProvider` identifies a reusable client and constructs it; `DataSource` adds data-access semantics.
+Accessible environments implement ClientProvider directly without becoming data sources. The `Client` owns initialization
 and idempotent disposal; a `ClientManager` joins concurrent initialization for the same key and
 closes owned clients when the caller finishes. A `ConnectionSource` resolves connection settings
 and available `Transport` paths. Clients execute protocol operations through those paths.
 
 ```ts
-import { ClientManager, dataSourceKey, type DataSource } from "@compforge/harness-toolbox";
+import { ClientManager, clientKey, type DataSource } from "@compforge/harness-toolbox";
 import { MysqlClient } from "@compforge/harness-toolbox/mysql";
 import { DirectTransport } from "@compforge/harness-toolbox/transport";
 
 const target = { host: "localhost", port: 3306, database: "app", user: "reader", password: "..." };
 const source: DataSource<MysqlClient> = {
-  key: dataSourceKey("mysql", target),
-  createClient: signal => new MysqlClient({
+  clientKey: clientKey("mysql", target),
+  createClient: (_clients, signal) => new MysqlClient({
     resolve: async () => target,
     transports: [new DirectTransport()],
   }, { signal, connectTimeoutMs: 5_000, queryTimeoutMs: 10_000 }),

package/dist/{chunk-94anqtxh.js → chunk-0cq1gx86.js}

@@ -1,6 +1,6 @@
 import {
-  dataSourceKey
-} from "./chunk-fnc291vk.js";
+  clientKey
+} from "./chunk-z5pm2emz.js";
 import {
   S3Client
 } from "./chunk-zp1s833x.js";
@@ -10,7 +10,7 @@ import {
 
 // src/s3/datasource.ts
 class S3DataSource {
-  key;
+  clientKey;
   #target;
   #limits;
   #transport;
@@ -18,13 +18,13 @@ class S3DataSource {
     this.#target = structuredClone(target);
     this.#limits = { ...limits };
     this.#transport = route?.transport ?? new DirectTransport;
-    this.key = dataSourceKey("s3", {
+    this.clientKey = clientKey("s3", {
       target: this.#target,
       limits: this.#limits,
       route: route ? { key: route.key, transport: route.transport.name } : "direct"
     });
   }
-  createClient(signal) {
+  createClient(_clients, signal) {
     return new S3Client({
       resolve: async () => this.#target,
       transports: [this.#transport]

package/dist/chunk-1kpbvat9.js

@@ -0,0 +1,89 @@
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+import {
+  KubernetesError,
+  ToolboxError,
+  kubernetesHttpError
+} from "./chunk-ntfm5e85.js";
+
+// src/kubernetes/resources.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import fetch from "node-fetch/lib/index.js";
+function resourceAccess(options, signal, limits) {
+  if (![limits.timeoutMs, limits.concurrency, limits.maxBytes].every((value) => Number.isSafeInteger(value) && value > 0)) {
+    throw new KubernetesError("Resource limits must be positive integers", { kind: "invalid_argument" });
+  }
+  const config = new KubeConfig;
+  try {
+    if (options.kubeconfig)
+      config.loadFromFile(options.kubeconfig);
+    else
+      config.loadFromDefault();
+    if (options.context)
+      config.setCurrentContext(options.context);
+  } catch (cause) {
+    throw new KubernetesError("Cannot load Kubernetes access configuration", { kind: "connection_failed", cause });
+  }
+  const cluster = config.getCurrentCluster();
+  if (!cluster)
+    throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+  if (new URL(cluster.server).protocol === "http:") {
+    config.clusters = config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+  }
+  const pool = new ConcurrencyPool(limits.concurrency);
+  return {
+    get: (namespace, resource, name, selector) => pool.run(async () => {
+      const group = ["pods", "services"].includes(resource) ? "/api/v1" : "/apis/apps/v1";
+      const path = group + "/namespaces/" + encodeURIComponent(namespace) + "/" + resource + (name ? "/" + encodeURIComponent(name) : "");
+      const url = new URL(cluster.server.replace(/\/$/, "") + path);
+      if (selector)
+        url.searchParams.set("labelSelector", selector);
+      const controller = new AbortController;
+      const abort = () => controller.abort(signal.reason);
+      signal.addEventListener("abort", abort, { once: true });
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, limits.timeoutMs);
+      try {
+        signal.throwIfAborted();
+        const init = await config.applyToFetchOptions({});
+        controller.signal.throwIfAborted();
+        const response = await fetch(url.href, { ...init, signal: controller.signal, size: limits.maxBytes });
+        if (!response.ok) {
+          controller.abort();
+          const error = kubernetesHttpError(response.status);
+          throw new KubernetesError("Read " + resource + " in namespace " + namespace + " failed", { kind: error.kind, code: error.code });
+        }
+        return await response.json();
+      } catch (cause) {
+        if (signal.aborted)
+          throw signal.reason;
+        if (cause instanceof ToolboxError)
+          throw cause;
+        const type = cause && typeof cause === "object" && "type" in cause ? cause.type : undefined;
+        const code = cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+        const tls = code !== undefined && [
+          "CERT_HAS_EXPIRED",
+          "DEPTH_ZERO_SELF_SIGNED_CERT",
+          "SELF_SIGNED_CERT_IN_CHAIN",
+          "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+          "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+          "ERR_TLS_CERT_ALTNAME_INVALID"
+        ].includes(code);
+        throw new KubernetesError("Read " + resource + " in namespace " + namespace + " failed", {
+          kind: timedOut ? "timeout" : type === "max-size" ? "limit_exceeded" : type === "invalid-json" ? "invalid_response" : tls ? "tls_verification_failed" : code === "ECONNRESET" ? "connection_lost" : "connection_failed",
+          cause,
+          code
+        });
+      } finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+      }
+    }, signal)
+  };
+}
+
+export { resourceAccess };

package/dist/chunk-4pdwsfcx.js

@@ -0,0 +1,111 @@
+import {
+  ServicePortForwarder
+} from "./chunk-205a4vma.js";
+import {
+  KubectlExecutor
+} from "./chunk-0rs1aacd.js";
+import {
+  resourceAccess
+} from "./chunk-1kpbvat9.js";
+import {
+  resolveWorkload
+} from "./chunk-y3dx8jh6.js";
+import {
+  KubernetesError
+} from "./chunk-ntfm5e85.js";
+
+// src/kubernetes/client.ts
+class KubernetesClient {
+  kube;
+  resourceLimits;
+  #controller = new AbortController;
+  signal;
+  #executors = new Map;
+  #forwarders = new Map;
+  #operations = new Set;
+  #disposal;
+  #resources;
+  constructor(kube, signal, executor, resourceLimits = { timeoutMs: 30000, concurrency: 4, maxBytes: 8 * 1024 * 1024 }, resources) {
+    this.kube = kube;
+    this.resourceLimits = resourceLimits;
+    this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
+    if (executor)
+      this.#executors.set(kube.namespace, executor);
+    this.#resources = resources;
+  }
+  async initialize() {
+    this.signal.throwIfAborted();
+  }
+  resolveWorkload(workload, environment) {
+    return this.#track(() => {
+      const namespace = workload.namespace ?? this.kube.namespace;
+      if (!namespace.trim())
+        throw new KubernetesError("Workload namespace is required", { kind: "invalid_argument" });
+      if (!environment.trim())
+        throw new KubernetesError("Environment identity is required", { kind: "invalid_argument" });
+      this.#resources ??= resourceAccess(this.kube, this.signal, this.resourceLimits);
+      return resolveWorkload(this.#resources, workload, namespace, environment);
+    });
+  }
+  #executor(namespace) {
+    let executor = this.#executors.get(namespace);
+    if (!executor) {
+      executor = new KubectlExecutor({ ...this.kube, namespace });
+      this.#executors.set(namespace, executor);
+    }
+    return executor;
+  }
+  #track(work) {
+    this.signal.throwIfAborted();
+    const pending = Promise.resolve().then(() => {
+      this.signal.throwIfAborted();
+      return work();
+    });
+    this.#operations.add(pending);
+    pending.then(() => this.#operations.delete(pending), () => this.#operations.delete(pending));
+    return pending;
+  }
+  #options(options) {
+    return { ...options, signal: options?.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal };
+  }
+  run(namespace, command, options) {
+    return this.#track(() => this.#executor(namespace).run(command, this.#options(options)));
+  }
+  exec(namespace, target, command, options) {
+    return this.#track(() => this.#executor(namespace).exec(target, command, this.#options(options)));
+  }
+  forward(namespace, target) {
+    return this.#track(async () => {
+      let pending = this.#forwarders.get(namespace);
+      if (!pending) {
+        pending = ServicePortForwarder.create(this.#executor(namespace), { ...this.kube, namespace });
+        this.#forwarders.set(namespace, pending);
+        pending.catch(() => {
+          if (this.#forwarders.get(namespace) === pending)
+            this.#forwarders.delete(namespace);
+        });
+      }
+      const forwarder = await pending;
+      this.signal.throwIfAborted();
+      return forwarder.forward(target);
+    });
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("Kubernetes client disposed"));
+      await Promise.allSettled(this.#operations);
+      const results = await Promise.allSettled([...this.#forwarders.values()].map(async (pending) => {
+        const forwarder = await pending.catch(() => {
+          return;
+        });
+        forwarder?.stop();
+      }));
+      this.#forwarders.clear();
+      const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+      if (errors.length)
+        throw new AggregateError(errors, "Kubernetes client cleanup failed");
+    })();
+  }
+}
+
+export { KubernetesClient };

package/dist/chunk-a9htb6cr.js

@@ -0,0 +1,4 @@
+// src/client.ts
+import { clientKey } from "@compforge/harness-common";
+
+export { clientKey };

package/dist/{chunk-s06hs7a8.js → chunk-m91t44jh.js}

@@ -50,9 +50,20 @@ try:
     )
     try:
         with connection.cursor(pymysql.cursors.DictCursor) as cursor:
-            cursor.execute(request["sql"], request["values"])
-            rows = cursor.fetchall()
-        print(json.dumps({"rows": rows}, default=encode, ensure_ascii=False))
+            statements = request.get("statements")
+            if statements is None:
+                cursor.execute(request["sql"], request["values"])
+                rows = cursor.fetchall()
+                print(json.dumps({"rows": rows}, default=encode, ensure_ascii=False))
+            else:
+                # Batch: one process and one connection for independent statements;
+                # the per-statement deadline is re-armed before each execute.
+                results = []
+                for statement in statements:
+                    signal.alarm(math.ceil(request["queryTimeoutMs"] / 1000))
+                    cursor.execute(statement["sql"], statement["values"])
+                    results.append({"rows": cursor.fetchall()})
+                print(json.dumps({"results": results}, default=encode, ensure_ascii=False))
     finally:
         connection.close()
 except Exception as error:
@@ -62,6 +73,9 @@ except Exception as error:
 finally:
     signal.alarm(0)
 `;
+function parsePodResponse(raw) {
+  return JSON.parse(raw, (_key, value) => value?.type === "Buffer" && Array.isArray(value.data) ? Buffer.from(value.data) : value);
+}
 async function queryMysqlViaPod(transport, target, sql, values, options) {
   const raw = await transport.run(POD_QUERY, {
     target,
@@ -69,11 +83,28 @@ async function queryMysqlViaPod(transport, target, sql, values, options) {
     values,
     ...options
   }, options.queryTimeoutMs + 3000);
-  const response = JSON.parse(raw, (_key, value) => value?.type === "Buffer" && Array.isArray(value.data) ? Buffer.from(value.data) : value);
+  const response = parsePodResponse(raw);
   if (response.error || !Array.isArray(response.rows)) {
     throw new Error(`MySQL via Pod failed: ${response.error ?? "invalid response"}${response.code ? ` (${response.code})` : ""}`);
   }
   return response.rows;
 }
+async function queryMysqlViaPodBatch(transport, target, statements, options) {
+  const raw = await transport.run(POD_QUERY, {
+    target,
+    statements: statements.map(({ sql, values }) => ({ sql: preparePodSql(sql, values), values })),
+    ...options
+  }, options.connectTimeoutMs + options.queryTimeoutMs * statements.length + 3000);
+  const response = parsePodResponse(raw);
+  if (response.error || !Array.isArray(response.results)) {
+    throw new Error(`MySQL via Pod batch failed: ${response.error ?? "invalid response"}${response.code ? ` (${response.code})` : ""}`);
+  }
+  return response.results.map((result, index) => {
+    if (!Array.isArray(result.rows)) {
+      throw new Error(`MySQL via Pod batch statement ${index} returned no rows`);
+    }
+    return result.rows;
+  });
+}
 
-export { preparePodSql, queryMysqlViaPod };
+export { preparePodSql, queryMysqlViaPod, queryMysqlViaPodBatch };

package/dist/{chunk-vjsr2jb3.js → chunk-mnad4zkp.js}

@@ -9,8 +9,8 @@ import {
   LogCaptureFile
 } from "./chunk-1vfwvgkj.js";
 import {
-  dataSourceKey
-} from "./chunk-fnc291vk.js";
+  clientKey
+} from "./chunk-a9htb6cr.js";
 
 // src/kubernetes/pod-log-client.ts
 import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
@@ -40,7 +40,7 @@ class PodLogClient {
     this.signal.throwIfAborted();
     if (!this.#directory || this.#disposal)
       throw new Error("Log capture session is not active");
-    const key = scope.instance && request.sinceTime ? dataSourceKey("pod-log", {
+    const key = scope.instance && request.sinceTime ? clientKey("pod-log", {
       scope,
       pod: request.pod,
       container: request.container,

package/dist/chunk-ntfm5e85.js

@@ -0,0 +1,27 @@
+// src/errors.ts
+class ToolboxError extends Error {
+  kind;
+  code;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.kind = options.kind;
+    this.code = options.code;
+  }
+}
+
+class KubernetesError extends ToolboxError {
+}
+function kubernetesHttpError(status) {
+  const kind = {
+    401: "authentication_failed",
+    403: "permission_denied",
+    404: "resource_not_found",
+    408: "timeout",
+    429: "limit_exceeded",
+    504: "timeout"
+  }[status] ?? "operation_failed";
+  return new KubernetesError("Kubernetes resource request failed", { kind, code: status });
+}
+
+export { ToolboxError, KubernetesError, kubernetesHttpError };

package/dist/{chunk-9x1apyp4.js → chunk-ssdxknsk.js}

@@ -1,10 +1,11 @@
-import {
-  queryMysqlViaPod
-} from "./chunk-s06hs7a8.js";
 import {
   queryReadonlySession,
   validateQueryLimits
 } from "./chunk-kbewz29a.js";
+import {
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "./chunk-m91t44jh.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -28,6 +29,22 @@ class MysqlDatabase {
   query(target, sql, values) {
     return this.#queries.run(() => this.#query(target, sql, values), this.options.signal);
   }
+  queryBatch(target, statements) {
+    return this.#queries.run(async () => {
+      if (!statements.length)
+        return [];
+      return this.#withSession(target, async (session) => {
+        if (session.kind === "python")
+          return queryMysqlViaPodBatch(session.transport, target, statements, this.options);
+        const results = [];
+        for (const { sql, values } of statements) {
+          const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
+          results.push(rows);
+        }
+        return results;
+      });
+    }, this.options.signal);
+  }
   queryReadonly(target, sql, values, limits) {
     validateQueryLimits(limits);
     return this.#queries.run(async () => {
@@ -60,7 +77,7 @@ class MysqlDatabase {
     }
     return pending;
   }
-  async#query(target, sql, values) {
+  async#withSession(target, run) {
     this.options.signal?.throwIfAborted();
     const key = [target.host, target.port, target.database, target.user, target.password].join("\x00");
     const pending = this.#session(target);
@@ -68,10 +85,7 @@ class MysqlDatabase {
     try {
       session = await pending;
       this.options.signal?.throwIfAborted();
-      if (session.kind === "python")
-        return await queryMysqlViaPod(session.transport, target, sql, values, this.options);
-      const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
-      return rows;
+      return await run(session);
     } catch (error) {
       if (this.#connections.get(key) === pending)
         this.#connections.delete(key);
@@ -80,6 +94,14 @@ class MysqlDatabase {
       throw error;
     }
   }
+  async#query(target, sql, values) {
+    return this.#withSession(target, async (session) => {
+      if (session.kind === "python")
+        return queryMysqlViaPod(session.transport, target, sql, values, this.options);
+      const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
+      return rows;
+    });
+  }
   async#open(target) {
     let reason;
     for (let i = 0;i < this.transports.length; i++) {

package/dist/chunk-y3dx8jh6.js

@@ -0,0 +1,94 @@
+import {
+  KubernetesError
+} from "./chunk-ntfm5e85.js";
+
+// src/kubernetes/workload.ts
+function failure(message, kind) {
+  throw new KubernetesError(message, { kind });
+}
+function selector(value, service = false) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return failure("Resource has no Pod selector", "unsupported_operation");
+  }
+  const input = value;
+  const labels = service ? value : input.matchLabels ?? {};
+  const terms = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => {
+    if (!key || /[,=()!\s]/.test(key) || typeof item !== "string" || /[,=()!\s]/.test(item)) {
+      return failure("Invalid label selector", "invalid_argument");
+    }
+    return key + "=" + item;
+  });
+  for (const entry of service ? [] : input.matchExpressions ?? []) {
+    const values = entry.values ?? [];
+    if (!entry.key || /[,=()!\s]/.test(entry.key) || values.some((v) => /[,=()!\s]/.test(v))) {
+      return failure("Invalid selector expression", "invalid_response");
+    }
+    if ((entry.operator === "In" || entry.operator === "NotIn") && values.length) {
+      terms.push(entry.key + (entry.operator === "In" ? " in (" : " notin (") + [...values].sort().join(",") + ")");
+    } else if (entry.operator === "Exists" && !values.length)
+      terms.push(entry.key);
+    else if (entry.operator === "DoesNotExist" && !values.length)
+      terms.push("!" + entry.key);
+    else
+      return failure("Unsupported selector expression", "invalid_response");
+  }
+  if (!terms.length)
+    return failure("Resource has no Pod selector", "unsupported_operation");
+  return terms.join(",");
+}
+async function resolveWorkload(access, workload, namespace, environment) {
+  if (!environment.trim())
+    return failure("Environment identity is required", "invalid_argument");
+  if (!namespace.trim())
+    return failure("Workload namespace is required", "invalid_argument");
+  const location = workload.location;
+  let selected;
+  let pods;
+  if (location.kind === "labels") {
+    if (!Object.keys(location.labels).length)
+      return failure("Pod labels must be nonempty", "invalid_argument");
+    selected = selector(location.labels, true);
+    const result = await access.get(namespace, "pods", undefined, selected);
+    if (!Array.isArray(result.items))
+      return failure("Pod list lacks items", "invalid_response");
+    pods = result.items;
+  } else {
+    const resource = location.kind === "service" ? "services" : {
+      Pod: "pods",
+      Deployment: "deployments",
+      StatefulSet: "statefulsets",
+      DaemonSet: "daemonsets"
+    }[location.resource_kind];
+    if (!resource)
+      return failure("Unsupported workload resource", "unsupported_operation");
+    if (!location.name.trim())
+      return failure("Resource name is required", "invalid_argument");
+    const item = await access.get(namespace, resource, location.name);
+    if (resource === "pods")
+      pods = [item];
+    else {
+      selected = selector(item.spec?.selector, resource === "services");
+      const result = await access.get(namespace, "pods", undefined, selected);
+      if (!Array.isArray(result.items))
+        return failure("Pod list lacks items", "invalid_response");
+      pods = result.items;
+    }
+  }
+  return pods.map((pod) => {
+    const metadata = pod.metadata;
+    if (!metadata?.name || !metadata.uid || metadata.namespace !== namespace) {
+      return failure("Pod response lacks identity or has a different namespace", "invalid_response");
+    }
+    return {
+      platform: "kubernetes",
+      environment,
+      workload: workload.name,
+      namespace,
+      pod: metadata.name,
+      uid: metadata.uid,
+      container: workload.container
+    };
+  }).sort((a, b) => a.pod.localeCompare(b.pod) || a.uid.localeCompare(b.uid));
+}
+
+export { resolveWorkload };

package/dist/chunk-z5pm2emz.js

@@ -0,0 +1,4 @@
+// src/datasource.ts
+import { clientKey, ClientManager, EnvironmentContext } from "@compforge/harness-common";
+
+export { clientKey, ClientManager, EnvironmentContext };

package/dist/client-manager.d.ts

@@ -1 +1 @@
-export { ClientManager, type ClientProvider } from "@compforge/harness-common";
+export { ClientManager } from "@compforge/harness-common";

package/dist/client.d.ts

@@ -1 +1 @@
-export type { Client } from "@compforge/harness-common";
+export { clientKey, type Client, type ClientManager, type ClientProvider } from "@compforge/harness-common";

package/dist/client.js

@@ -0,0 +1,6 @@
+import {
+  clientKey
+} from "./chunk-a9htb6cr.js";
+export {
+  clientKey
+};

package/dist/datasource.d.ts

@@ -1,5 +1,6 @@
-export { dataSourceKey, ClientManager, type Client, type ClientProvider, type DataSource, type ServiceDataSource } from "@compforge/harness-common";
+export { clientKey, ClientManager, EnvironmentContext, type Client, type ClientProvider, type DataSource, type ServiceDataSource } from "@compforge/harness-common";
 import type { Transport } from "./transport";
+export { ToolboxError, KubernetesError, type ErrorKind } from "./errors";
 /** Resolution owns configuration semantics; transports preserve the resolved target and identity. */
 export interface ConnectionSource<Target> {
     resolve(): Promise<Target>;

package/dist/datasource.js

@@ -1,8 +1,16 @@
 import {
   ClientManager,
-  dataSourceKey
-} from "./chunk-fnc291vk.js";
+  EnvironmentContext,
+  clientKey
+} from "./chunk-z5pm2emz.js";
+import {
+  KubernetesError,
+  ToolboxError
+} from "./chunk-ntfm5e85.js";
 export {
-  dataSourceKey,
+  clientKey,
+  ToolboxError,
+  KubernetesError,
+  EnvironmentContext,
   ClientManager
 };

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/** Stable toolbox failure semantics; native causes are for debugging, not user reports. */
+export type ErrorKind = "connection_failed" | "connection_lost" | "tls_verification_failed" | "authentication_failed" | "permission_denied" | "resource_not_found" | "timeout" | "limit_exceeded" | "invalid_response" | "operation_failed" | "invalid_argument" | "unsupported_operation";
+export declare class ToolboxError extends Error {
+    readonly kind: ErrorKind;
+    readonly code?: number | string;
+    constructor(message: string, options: {
+        kind: ErrorKind;
+        code?: number | string;
+        cause?: unknown;
+    });
+}
+export declare class KubernetesError extends ToolboxError {
+}
+export declare function kubernetesHttpError(status: number): KubernetesError;

package/dist/errors.js

@@ -0,0 +1,10 @@
+import {
+  KubernetesError,
+  ToolboxError,
+  kubernetesHttpError
+} from "./chunk-ntfm5e85.js";
+export {
+  kubernetesHttpError,
+  ToolboxError,
+  KubernetesError
+};

package/dist/kubernetes/client.d.ts

@@ -1,15 +1,20 @@
 import type { Client } from "../client";
 import { type Executor, type KubectlOptions, type ExecTarget, type RunOptions } from "./executor";
 import type { KubernetesEndpoint } from "./endpoint";
+import type { Workload, WorkloadInstance } from "@compforge/harness-common";
+import { type ResourceAccess, type ResourceLimits } from "./resources";
 /** Owns cluster transports; protocol callers borrow this client without closing it. */
 export declare class KubernetesClient implements Client {
     #private;
     private readonly kube;
+    private readonly resourceLimits;
     readonly signal: AbortSignal;
     constructor(kube: KubectlOptions & {
         namespace: string;
-    }, signal?: AbortSignal, executor?: Executor);
+    }, signal?: AbortSignal, executor?: Executor, resourceLimits?: ResourceLimits, resources?: ResourceAccess);
     initialize(): Promise<void>;
+    /** environment is a stable target ID from the caller's registry, not access configuration. */
+    resolveWorkload(workload: Workload, environment: string): Promise<WorkloadInstance[]>;
     run(namespace: string, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
     exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
     forward(namespace: string, target: KubernetesEndpoint): Promise<import("./service-port-forward").ForwardedEndpoint>;

package/dist/kubernetes/client.js

@@ -1,92 +1,16 @@
 import {
-  ServicePortForwarder
-} from "../chunk-205a4vma.js";
+  KubernetesClient
+} from "../chunk-4pdwsfcx.js";
+import"../chunk-205a4vma.js";
 import"../chunk-hv2kx47y.js";
-import {
-  KubectlExecutor
-} from "../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-
-// src/kubernetes/client.ts
-class KubernetesClient {
-  kube;
-  #controller = new AbortController;
-  signal;
-  #executors = new Map;
-  #forwarders = new Map;
-  #operations = new Set;
-  #disposal;
-  constructor(kube, signal, executor) {
-    this.kube = kube;
-    this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
-    if (executor)
-      this.#executors.set(kube.namespace, executor);
-  }
-  async initialize() {
-    this.signal.throwIfAborted();
-  }
-  #executor(namespace) {
-    let executor = this.#executors.get(namespace);
-    if (!executor) {
-      executor = new KubectlExecutor({ ...this.kube, namespace });
-      this.#executors.set(namespace, executor);
-    }
-    return executor;
-  }
-  #track(work) {
-    this.signal.throwIfAborted();
-    const pending = Promise.resolve().then(() => {
-      this.signal.throwIfAborted();
-      return work();
-    });
-    this.#operations.add(pending);
-    pending.then(() => this.#operations.delete(pending), () => this.#operations.delete(pending));
-    return pending;
-  }
-  #options(options) {
-    return { ...options, signal: options?.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal };
-  }
-  run(namespace, command, options) {
-    return this.#track(() => this.#executor(namespace).run(command, this.#options(options)));
-  }
-  exec(namespace, target, command, options) {
-    return this.#track(() => this.#executor(namespace).exec(target, command, this.#options(options)));
-  }
-  forward(namespace, target) {
-    return this.#track(async () => {
-      let pending = this.#forwarders.get(namespace);
-      if (!pending) {
-        pending = ServicePortForwarder.create(this.#executor(namespace), { ...this.kube, namespace });
-        this.#forwarders.set(namespace, pending);
-        pending.catch(() => {
-          if (this.#forwarders.get(namespace) === pending)
-            this.#forwarders.delete(namespace);
-        });
-      }
-      const forwarder = await pending;
-      this.signal.throwIfAborted();
-      return forwarder.forward(target);
-    });
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error("Kubernetes client disposed"));
-      await Promise.allSettled(this.#operations);
-      const results = await Promise.allSettled([...this.#forwarders.values()].map(async (pending) => {
-        const forwarder = await pending.catch(() => {
-          return;
-        });
-        forwarder?.stop();
-      }));
-      this.#forwarders.clear();
-      const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
-      if (errors.length)
-        throw new AggregateError(errors, "Kubernetes client cleanup failed");
-    })();
-  }
-}
+import"../chunk-0rs1aacd.js";
+import"../chunk-ztenxgjv.js";
+import"../chunk-1kpbvat9.js";
+import"../chunk-y3dx8jh6.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-ntfm5e85.js";
 export {
   KubernetesClient
 };

package/dist/kubernetes/environment.d.ts

@@ -0,0 +1,19 @@
+import { type ClientProvider, type ClientManager } from "../client";
+import type { Environment } from "@compforge/harness-common";
+import { KubernetesClient } from "./client";
+import type { KubectlOptions } from "./executor";
+import type { ResourceLimits } from "./resources";
+/** Cluster access is a client provider; the execution owns client lifetime. */
+export declare class KubernetesEnvironment implements Environment, ClientProvider<KubernetesClient> {
+    #private;
+    readonly name: string;
+    readonly kind = "kubernetes";
+    readonly clientKey: string;
+    /** Deployment metadata only; not part of client reuse or access configuration. */
+    readonly imageRegistry?: string;
+    constructor(name: string, kube: KubectlOptions & {
+        namespace: string;
+        imageRegistry?: string;
+    }, limits: ResourceLimits);
+    createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): KubernetesClient;
+}

package/dist/kubernetes/environment.js

@@ -0,0 +1,43 @@
+import {
+  KubernetesClient
+} from "../chunk-4pdwsfcx.js";
+import"../chunk-205a4vma.js";
+import"../chunk-hv2kx47y.js";
+import"../chunk-j46x7j7c.js";
+import"../chunk-6fnhzhdb.js";
+import"../chunk-0rs1aacd.js";
+import"../chunk-ztenxgjv.js";
+import"../chunk-1kpbvat9.js";
+import"../chunk-y3dx8jh6.js";
+import {
+  clientKey
+} from "../chunk-a9htb6cr.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-ntfm5e85.js";
+
+// src/kubernetes/environment.ts
+class KubernetesEnvironment {
+  name;
+  kind = "kubernetes";
+  clientKey;
+  imageRegistry;
+  #kube;
+  #limits;
+  constructor(name, kube, limits) {
+    this.name = name;
+    this.imageRegistry = kube.imageRegistry;
+    this.#kube = Object.freeze({
+      namespace: kube.namespace,
+      kubeconfig: kube.kubeconfig,
+      context: kube.context
+    });
+    this.#limits = Object.freeze({ ...limits });
+    this.clientKey = clientKey("kubernetes-client", [this.#kube, this.#limits]);
+  }
+  createClient(_clients, signal) {
+    return new KubernetesClient(this.#kube, signal, undefined, this.#limits);
+  }
+}
+export {
+  KubernetesEnvironment
+};

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

@@ -1,10 +1,10 @@
 import {
   PodLogClient
-} from "../chunk-vjsr2jb3.js";
+} from "../chunk-mnad4zkp.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
-import"../chunk-fnc291vk.js";
+import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
 export {
   PodLogClient

package/dist/kubernetes/pod-log-datasource.d.ts

@@ -1,4 +1,4 @@
-import { type DataSource } from "../datasource";
+import { type DataSource, type ClientManager } from "../datasource";
 import type { ConcurrencyPool } from "../concurrency";
 import { PodLogClient } from "./pod-log-client";
 import type { PodLogByteBudget, PodLogCapturePolicy } from "./log-capture-plan";
@@ -7,11 +7,11 @@ export declare class PodLogDataSource implements DataSource<PodLogClient> {
     private readonly pool;
     private readonly budget;
     private readonly policy;
-    readonly key: string;
+    readonly clientKey: string;
     constructor(target: {
         kubeconfig?: string;
         context?: string;
         namespace: string;
     }, pool: ConcurrencyPool, budget: PodLogByteBudget, policy: PodLogCapturePolicy);
-    createClient(signal: AbortSignal): PodLogClient;
+    createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): PodLogClient;
 }

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

@@ -1,27 +1,29 @@
 import {
   PodLogClient
-} from "../chunk-vjsr2jb3.js";
+} from "../chunk-mnad4zkp.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-a9htb6cr.js";
 import {
-  dataSourceKey
-} from "../chunk-fnc291vk.js";
+  clientKey
+} from "../chunk-z5pm2emz.js";
 import"../chunk-v3hxvnrc.js";
+import"../chunk-ntfm5e85.js";
 
 // src/kubernetes/pod-log-datasource.ts
 class PodLogDataSource {
   pool;
   budget;
   policy;
-  key;
+  clientKey;
   constructor(target, pool, budget, policy) {
     this.pool = pool;
     this.budget = budget;
     this.policy = policy;
-    this.key = dataSourceKey("pod-log", target);
+    this.clientKey = clientKey("pod-log", target);
   }
-  createClient(signal) {
+  createClient(_clients, signal) {
     return new PodLogClient(this.pool, signal, this.policy, this.budget);
   }
 }

package/dist/kubernetes/resources.d.ts

@@ -0,0 +1,23 @@
+import type { KubectlOptions } from "./executor";
+export interface Resource {
+    metadata?: {
+        name?: string;
+        namespace?: string;
+        uid?: string;
+    };
+    spec?: {
+        selector?: unknown;
+    };
+    items?: Resource[];
+    kind?: string;
+}
+export interface ResourceAccess {
+    get(namespace: string, resource: string, name?: string, selector?: string): Promise<Resource>;
+}
+export interface ResourceLimits {
+    timeoutMs: number;
+    concurrency: number;
+    maxBytes: number;
+}
+/** Native JSON reads use the same client-node auth/TLS path as native Pod logs. */
+export declare function resourceAccess(options: KubectlOptions, signal: AbortSignal, limits: ResourceLimits): ResourceAccess;

package/dist/kubernetes/resources.js

@@ -0,0 +1,8 @@
+import {
+  resourceAccess
+} from "../chunk-1kpbvat9.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-ntfm5e85.js";
+export {
+  resourceAccess
+};

package/dist/kubernetes/service-port-forward.js

@@ -2,10 +2,10 @@ import {
   ServicePortForwarder
 } from "../chunk-205a4vma.js";
 import"../chunk-hv2kx47y.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
+import"../chunk-0rs1aacd.js";
+import"../chunk-ztenxgjv.js";
 export {
   ServicePortForwarder
 };

package/dist/kubernetes/workload.d.ts

@@ -0,0 +1,7 @@
+import type { Workload, WorkloadInstance } from "@compforge/harness-common";
+import type { ResourceAccess } from "./resources";
+/**
+ * No readiness filter or replica selection; consumers own collection policy.
+ * @rule environment is the caller's stable, non-secret target ID, independent of access routes.
+ */
+export declare function resolveWorkload(access: ResourceAccess, workload: Workload, namespace: string, environment: string): Promise<WorkloadInstance[]>;

package/dist/kubernetes/workload.js

@@ -0,0 +1,7 @@
+import {
+  resolveWorkload
+} from "../chunk-y3dx8jh6.js";
+import"../chunk-ntfm5e85.js";
+export {
+  resolveWorkload
+};

package/dist/mysql/client.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "../client";
 import { type Connection, type ConnectionOptions } from "mysql2/promise";
-import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult } from "./types";
+import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult, SqlStatement } from "./types";
 import type { ConnectionSource, ClientLifecycle } from "../datasource";
 import { type Transport } from "../transport";
 export interface MysqlDatabaseOptions extends ClientLifecycle {
@@ -16,6 +16,12 @@ export declare class MysqlDatabase implements Database {
     private readonly connect;
     constructor(transports: readonly Transport[], options: MysqlDatabaseOptions, connect?: ConnectionFactory);
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
+    /**
+     * Independent statements in submission order, one session: a Pod transport pays the exec
+     * and connection cost once instead of per statement. Fail-fast like query(); use query()
+     * when a statement depends on an earlier result.
+     */
+    queryBatch(target: DatabaseTarget, statements: readonly SqlStatement[]): Promise<DatabaseRow[][]>;
     /** Bounded, single-statement prepared execution on an isolated READ ONLY session (native only). */
     queryReadonly(target: DatabaseTarget, sql: string, values: readonly unknown[], limits: DatabaseQueryLimits): Promise<DatabaseQueryResult>;
     initialize(target: DatabaseTarget): Promise<void>;

package/dist/mysql/client.js

@@ -2,9 +2,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-9x1apyp4.js";
-import"../chunk-s06hs7a8.js";
+} from "../chunk-ssdxknsk.js";
 import"../chunk-kbewz29a.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-xy4g56g4.js";
 export {

package/dist/mysql/index.js

@@ -6,9 +6,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-9x1apyp4.js";
-import"../chunk-s06hs7a8.js";
+} from "../chunk-ssdxknsk.js";
 import"../chunk-kbewz29a.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-xy4g56g4.js";
 export {

package/dist/mysql/pod.d.ts

@@ -1,7 +1,16 @@
-import type { DatabaseRow, DatabaseTarget } from "./types";
+import type { DatabaseRow, DatabaseTarget, SqlStatement } from "./types";
 import type { PodPythonTransport } from "../transport";
 export declare function preparePodSql(sql: string, values: readonly unknown[]): string;
 export declare function queryMysqlViaPod(transport: PodPythonTransport, target: DatabaseTarget, sql: string, values: readonly unknown[], options: {
     connectTimeoutMs: number;
     queryTimeoutMs: number;
 }): Promise<DatabaseRow[]>;
+/**
+ * Independent statements over one Pod process and one MySQL connection: the per-exec cost
+ * (kubectl handshake, interpreter start, auth) is paid once. Fail-fast: a statement error
+ * aborts the batch, later statements never execute, and the whole batch throws.
+ */
+export declare function queryMysqlViaPodBatch(transport: PodPythonTransport, target: DatabaseTarget, statements: readonly SqlStatement[], options: {
+    connectTimeoutMs: number;
+    queryTimeoutMs: number;
+}): Promise<DatabaseRow[][]>;

package/dist/mysql/pod.js

@@ -1,8 +1,10 @@
 import {
   preparePodSql,
-  queryMysqlViaPod
-} from "../chunk-s06hs7a8.js";
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "../chunk-m91t44jh.js";
 export {
+  queryMysqlViaPodBatch,
   queryMysqlViaPod,
   preparePodSql
 };

package/dist/mysql/types.d.ts

@@ -8,6 +8,10 @@ export interface DatabaseTarget extends DatabaseIdentity {
     database: string;
 }
 export type DatabaseRow = Record<string, unknown>;
+export interface SqlStatement {
+    sql: string;
+    values: readonly unknown[];
+}
 export interface DatabaseQueryLimits {
     timeoutMs: number;
     maxRows: number;

package/dist/redis/index.js

@@ -1,3 +1,6 @@
+import {
+  discoverRedisTopology
+} from "../chunk-c6z919qb.js";
 import {
   RedisAccess,
   RedisClient,
@@ -9,9 +12,6 @@ import {
   collectRedisKeyStats,
   redisGroupedSampleSizes
 } from "../chunk-jr9y0ghr.js";
-import {
-  discoverRedisTopology
-} from "../chunk-c6z919qb.js";
 export {
   redisGroupedSampleSizes,
   parseRedisInfo,

package/dist/s3/datasource.d.ts

@@ -1,14 +1,14 @@
-import { type DataSource } from "../datasource";
+import { type DataSource, type ClientManager } from "../datasource";
 import { type TcpTransport } from "../transport";
 import { S3Client } from "./client";
 import type { S3Limits, S3Target } from "./types";
 /** Connection details are resolved by the caller; route identity includes the cluster/context, not just a transport name. */
 export declare class S3DataSource implements DataSource<S3Client> {
     #private;
-    readonly key: string;
+    readonly clientKey: string;
     constructor(target: S3Target, limits: S3Limits, route?: {
         key: string;
         transport: TcpTransport;
     });
-    createClient(signal: AbortSignal): S3Client;
+    createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): S3Client;
 }

package/dist/s3/datasource.js

@@ -1,11 +1,12 @@
 import {
   S3DataSource
-} from "../chunk-94anqtxh.js";
-import"../chunk-fnc291vk.js";
+} from "../chunk-0cq1gx86.js";
+import"../chunk-z5pm2emz.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
 import"../chunk-xy4g56g4.js";
+import"../chunk-ntfm5e85.js";
 export {
   S3DataSource
 };

package/dist/s3/index.js

@@ -1,13 +1,14 @@
 import {
   S3DataSource
-} from "../chunk-94anqtxh.js";
-import"../chunk-fnc291vk.js";
+} from "../chunk-0cq1gx86.js";
+import"../chunk-z5pm2emz.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
 import"../chunk-xy4g56g4.js";
+import"../chunk-ntfm5e85.js";
 export {
   S3DataSource,
   S3Client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.1.2",
+  "version": "0.3.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -9,6 +9,10 @@
     "build": "bun scripts/build.ts && tsc -p tsconfig.build.json"
   },
   "exports": {
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
     ".": {
       "types": "./dist/datasource.d.ts",
       "import": "./dist/datasource.js"
@@ -83,7 +87,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@compforge/harness-common": "0.0.1",
+    "@compforge/harness-common": "0.3.0",
     "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",

package/dist/chunk-fnc291vk.js

@@ -1,4 +0,0 @@
-// src/datasource.ts
-import { dataSourceKey, ClientManager } from "@compforge/harness-common";
-
-export { dataSourceKey, ClientManager };