@compforge/harness-toolbox 0.1.1 → 0.3.1

package/README.md

@@ -1,5 +1,9 @@
 # Harness Toolbox
 
+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.
+
 Shared infrastructure for diagnostic tools, test runners and business adapters. Use the same
 clients to access Kubernetes, MySQL, Redis, OpenSearch and S3-compatible object storage without depending on a particular
 command, plugin protocol, test model or verdict.
@@ -8,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 }),
@@ -81,3 +142,17 @@ for mapped routes; direct endpoints also support virtual-hosted buckets. Signed
 identity remain the logical endpoint, not the forwarded address. Private CAs may be supplied
 explicitly with `ca`; certificate verification stays enabled. Initialization prepares the client
 and route without listing buckets or claiming that credentials have been validated.
+
+## Bounded MySQL reads
+
+`MysqlClient.database.queryReadonly(target, sql, values, { timeoutMs, maxRows, maxBytes })` uses
+the shared query slot and a disposable native session with `NO_BACKSLASH_ESCAPES`, a SELECT deadline,
+and a READ ONLY transaction. Prepared execution binds values and retains rows incrementally,
+returning `rows`, `columns`, `bytes`, `truncated`, and `truncation`. An extra row proves row truncation;
+a row exceeding the remaining byte budget is not retained.
+
+Callers own SQL classification, function policy, and least-privilege identities: READ ONLY alone
+is not an arbitrary-SQL sandbox. This API requires MySQL 5.7.8+ `max_execution_time` and does not
+fall back to Pod Python. Completion, truncation, timeout, and cancellation destroy the disposable
+session without replay or changes to ordinary borrowed sessions. Disconnect does not prove immediate
+server cancellation. The byte budget limits retained JSON rows, not individual wire packets or fields.

package/dist/{chunk-9j36zvn4.js → chunk-0cq1gx86.js}

@@ -1,6 +1,6 @@
 import {
-  dataSourceKey
-} from "./chunk-hqx7j9xe.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-sry9e02n.js → chunk-jkpwa8tb.js}

@@ -1,3 +1,7 @@
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "./chunk-kbewz29a.js";
 import {
   queryMysqlViaPod
 } from "./chunk-s06hs7a8.js";
@@ -24,6 +28,19 @@ class MysqlDatabase {
   query(target, sql, values) {
     return this.#queries.run(() => this.#query(target, sql, values), this.options.signal);
   }
+  queryReadonly(target, sql, values, limits) {
+    validateQueryLimits(limits);
+    return this.#queries.run(async () => {
+      const session = await this.#open(target);
+      if (session.kind !== "tcp")
+        throw new Error("Bounded readonly MySQL queries require a native TCP transport");
+      try {
+        return await queryReadonlySession(session.connection, sql, values, limits, this.options.signal);
+      } finally {
+        session.connection.destroy();
+      }
+    }, this.options.signal);
+  }
   initialize(target) {
     return this.#queries.run(async () => {
       await this.#session(target);

package/dist/chunk-kbewz29a.js

@@ -0,0 +1,95 @@
+// src/mysql/readonly.ts
+function validateQueryLimits(limits) {
+  for (const name of ["timeoutMs", "maxRows", "maxBytes"]) {
+    const value = limits[name];
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) {
+      throw new Error(`${name} must be a positive integer <= 2147483647`);
+    }
+  }
+}
+async function queryReadonlySession(connection, sql, values, limits, signal) {
+  validateQueryLimits(limits);
+  signal?.throwIfAborted();
+  let timer;
+  let abort;
+  try {
+    return await Promise.race([
+      (async () => {
+        await connection.query("SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_BACKSLASH_ESCAPES'");
+        await connection.query(`SET SESSION max_execution_time = ${limits.timeoutMs}`);
+        await connection.query("START TRANSACTION READ ONLY");
+        signal?.throwIfAborted();
+        return await collectRows(connection, sql, values, limits);
+      })(),
+      new Promise((_resolve, reject) => {
+        const fail = (reason) => {
+          connection.destroy();
+          reject(reason);
+        };
+        abort = () => fail(signal?.reason ?? new Error("MySQL query cancelled"));
+        signal?.addEventListener("abort", abort, { once: true });
+        timer = setTimeout(() => fail(new Error("MySQL readonly query timed out")), limits.timeoutMs);
+        if (signal?.aborted)
+          abort();
+      })
+    ]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    if (abort)
+      signal?.removeEventListener("abort", abort);
+    connection.destroy();
+  }
+}
+function collectRows(connection, sql, values, limits) {
+  const native = connection.connection;
+  return new Promise((resolve, reject) => {
+    const result = { rows: [], columns: [], bytes: 0, truncated: false };
+    let settled = false;
+    const finish = (truncation) => {
+      if (settled)
+        return;
+      settled = true;
+      result.truncated = !!truncation;
+      if (truncation)
+        result.truncation = truncation;
+      resolve(result);
+    };
+    const query = native.execute({ sql, values: [...values], timeout: limits.timeoutMs });
+    query.on("fields", (fields) => {
+      result.columns = fields?.map((field) => field.name) ?? [];
+    });
+    query.on("result", (row) => {
+      if (settled)
+        return;
+      if (result.rows.length >= limits.maxRows) {
+        finish("rows");
+        connection.destroy();
+        return;
+      }
+      try {
+        const bytes = Buffer.byteLength(JSON.stringify(row));
+        if (result.bytes + bytes > limits.maxBytes) {
+          finish("bytes");
+          connection.destroy();
+          return;
+        }
+        result.rows.push(row);
+        result.bytes += bytes;
+      } catch (error) {
+        settled = true;
+        connection.destroy();
+        reject(error);
+      }
+    });
+    query.on("error", (error) => {
+      if (!settled) {
+        settled = true;
+        reject(error);
+      }
+    });
+    query.on("end", () => finish());
+  });
+}
+
+export { validateQueryLimits, queryReadonlySession };

package/dist/{chunk-1at7zs0z.js → chunk-mnad4zkp.js}

@@ -9,8 +9,8 @@ import {
   LogCaptureFile
 } from "./chunk-1vfwvgkj.js";
 import {
-  dataSourceKey
-} from "./chunk-hqx7j9xe.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-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,14 +1 @@
-import type { Client } from "./client";
-import type { DataSource } from "./datasource";
-/** Consumers borrow clients; only the root owner receives the disposal capability. */
-export interface ClientProvider {
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
-}
-/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
-export declare class ClientManager implements ClientProvider {
-    #private;
-    readonly signal: AbortSignal;
-    constructor(signal?: AbortSignal);
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
-    dispose(): Promise<void>;
-}
+export { ClientManager } from "@compforge/harness-common";

package/dist/client-manager.js

@@ -1,6 +1,5 @@
-import {
-  ClientManager
-} from "./chunk-3dt25p98.js";
+// src/client-manager.ts
+import { ClientManager } from "@compforge/harness-common";
 export {
   ClientManager
 };

package/dist/client.d.ts

@@ -1,5 +1 @@
-/** A protocol client owns its initialization and idempotent cleanup, including partial initialization. */
-export interface Client {
-    initialize(): Promise<void>;
-    dispose(): Promise<void>;
-}
+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
+};