@compforge/harness-toolbox 0.4.3 → 0.4.5

package/dist/{chunk-h73h2b7y.js → chunk-t4hrnaj0.js}

@@ -5,13 +5,18 @@ import {
 import {
   queryReadonlySession,
   validateQueryLimits
-} from "./chunk-age65q4n.js";
+} from "./chunk-db4an9td.js";
 import {
+  connectMysql,
   destroyMysqlConnection
-} from "./chunk-136egyff.js";
+} from "./chunk-835fssgz.js";
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "./chunk-gm4swndx.js";
 import {
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -20,7 +25,6 @@ import {
 } from "./chunk-h8fwx0k7.js";
 
 // src/mysql/client.ts
-import { createConnection } from "mysql2/promise";
 function mysqlOperationError(error, phase) {
   if (!error || typeof error !== "object" || !("code" in error) || error.code !== "PROTOCOL_CONNECTION_LOST")
     return error;
@@ -37,7 +41,7 @@ class MysqlDatabase {
   connect;
   #queries = new ConcurrencyPool(1);
   #connections = new Map;
-  constructor(transports, options, connect = createConnection) {
+  constructor(transports, options, connect = connectMysql) {
     this.transports = transports;
     this.options = options;
     this.connect = connect;
@@ -120,39 +124,40 @@ class MysqlDatabase {
       return rows;
     });
   }
-  async#open(target) {
-    let reason;
-    for (let i = 0;i < this.transports.length; i++) {
-      const transport = this.transports[i];
-      this.options.signal?.throwIfAborted();
-      if (transport.kind === "python") {
-        this.options.onRoute?.({ transport: transport.name, reason });
-        return { kind: "python", transport };
-      }
-      try {
-        const endpoint = await transport.connect(target);
-        const connection = await this.connect({
-          host: endpoint.host,
-          port: endpoint.port,
-          user: target.user,
-          password: target.password,
-          database: target.database,
-          connectTimeout: this.options.connectTimeoutMs,
-          dateStrings: true,
-          supportBigNumbers: true,
-          bigNumberStrings: true
-        });
-        this.options.onRoute?.({ transport: endpoint.host === target.host && endpoint.port === target.port ? "direct" : transport.name, reason });
-        return { kind: "tcp", connection };
-      } catch (error) {
-        const failure = mysqlOperationError(error, "connect");
-        const connectionLost = failure instanceof ToolboxError && failure.kind === "connection_lost";
-        if (!isConnectionNetworkError(failure) && !connectionLost || i === this.transports.length - 1)
-          throw failure;
-        reason = String(failure.code);
-      }
-    }
-    throw new Error("MySQL DataSource has no transport");
+  #open(target) {
+    return acquireConnection(this.transports, {
+      name: "MySQL connection",
+      ...this.options,
+      open: async (transport, attempt) => {
+        if (transport.kind === "python")
+          return { connection: { kind: "python", transport }, transport: transport.name };
+        try {
+          const endpoint = await transport.connect(target);
+          const connection = await this.connect({
+            host: endpoint.host,
+            port: endpoint.port,
+            user: target.user,
+            password: target.password,
+            database: target.database,
+            connectTimeout: attempt.remainingMs(),
+            dateStrings: true,
+            supportBigNumbers: true,
+            bigNumberStrings: true
+          }, attempt.signal);
+          return {
+            connection: { kind: "tcp", connection },
+            transport: endpoint.host === target.host && endpoint.port === target.port ? "direct" : transport.name
+          };
+        } catch (error) {
+          throw mysqlOperationError(error, "connect");
+        }
+      },
+      close: (session) => {
+        if (session.kind === "tcp")
+          destroyMysqlConnection(session.connection);
+      },
+      retryReason: (error) => isConnectionNetworkError(error) || error instanceof ToolboxError && error.kind === "connection_lost" ? String(error.code) : undefined
+    });
   }
   async queryOne(target, sql, values) {
     return (await this.query(target, sql, values))[0];
@@ -186,7 +191,7 @@ class MysqlClient {
   initialize() {
     this.signal.throwIfAborted();
     return this.#initialization ??= (async () => {
-      this.#target = await this.source.resolve();
+      this.#target = await awaitWithSignal(this.source.resolve(), this.signal);
       this.signal.throwIfAborted();
       this.#database = new MysqlDatabase(this.source.transports, { ...this.options, signal: this.signal });
       await this.#database.initialize(this.#target);

package/dist/{chunk-kkts16w9.js → chunk-ww11q58v.js}

@@ -1,7 +1,7 @@
 import {
   FileError,
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-4ms037k2.js → chunk-x0yhfg29.js}

@@ -1,6 +1,6 @@
 import {
   resourcePath
-} from "./chunk-ftkrjqkc.js";
+} from "./chunk-dpcge1xt.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";
@@ -8,7 +8,7 @@ import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/chunk-z15gwjvg.js

@@ -0,0 +1,145 @@
+import {
+  KubernetesError
+} from "./chunk-rkt41za2.js";
+
+// src/kubernetes/compute-quantity.ts
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function invalid(message) {
+  throw new KubernetesError(message, { kind: "invalid_response" });
+}
+function requiredString(value, field) {
+  if (typeof value !== "string" || !value)
+    return invalid(`Kubernetes response lacks ${field}`);
+  return value;
+}
+function parseComputeQuantity(value) {
+  if (typeof value !== "string")
+    return invalid("Kubernetes quantity must be a string");
+  const match = /^([+-]?(?:\d+(?:\.\d*)?|\.\d+))([eE][+-]?\d+|[numkMGTPE]|[KMGTPE]i)?$/.exec(value);
+  if (!match)
+    return invalid("Invalid Kubernetes quantity");
+  const suffix = match[2] ?? "";
+  const factors = {
+    "": 1,
+    n: 0.000000001,
+    u: 0.000001,
+    m: 0.001,
+    k: 1000,
+    M: 1e6,
+    G: 1e9,
+    T: 1000000000000,
+    P: 1000000000000000,
+    E: 1000000000000000000,
+    Ki: 2 ** 10,
+    Mi: 2 ** 20,
+    Gi: 2 ** 30,
+    Ti: 2 ** 40,
+    Pi: 2 ** 50,
+    Ei: 2 ** 60
+  };
+  const result = Number(match[1]) * (/^[eE][+-]?\d+$/.test(suffix) ? 10 ** Number(suffix.slice(1)) : factors[suffix]);
+  if (!Number.isFinite(result) || result < 0 || result > Number.MAX_SAFE_INTEGER) {
+    return invalid("Kubernetes quantity is outside the supported numeric range");
+  }
+  return result;
+}
+var zero = () => ({ cpu: 0, memory: 0 });
+function add(left, right) {
+  return { cpu: left.cpu + right.cpu, memory: left.memory + right.memory };
+}
+function max(left, right) {
+  return { cpu: Math.max(left.cpu, right.cpu), memory: Math.max(left.memory, right.memory) };
+}
+function quantities(value, required = false) {
+  const input = object(value);
+  return {
+    cpu: input.cpu === undefined && !required ? 0 : parseComputeQuantity(input.cpu),
+    memory: input.memory === undefined && !required ? 0 : parseComputeQuantity(input.memory)
+  };
+}
+function sum(values) {
+  return values.reduce(add, zero());
+}
+function containers(value) {
+  if (!Array.isArray(value))
+    return invalid("Pod response lacks containers");
+  return value.map((item) => {
+    const container = object(item);
+    requiredString(container.name, "container.name");
+    return container;
+  });
+}
+function podCompute(value) {
+  const meta = object(value.metadata), spec = object(value.spec), status = object(value.status);
+  const app = containers(spec.containers);
+  if (!app.length)
+    return invalid("Pod must contain an application container");
+  const init = containers(spec.initContainers ?? []);
+  const effective = (field) => {
+    let steady = sum(app.map((c) => quantities(object(c.resources)[field])));
+    let sidecars = zero(), peak = zero();
+    for (const container of init) {
+      const current = quantities(object(container.resources)[field]);
+      if (container.restartPolicy === "Always") {
+        sidecars = add(sidecars, current);
+        steady = add(steady, current);
+        peak = max(peak, sidecars);
+      } else
+        peak = max(peak, add(sidecars, current));
+    }
+    const result = max(steady, peak);
+    const podLevel = object(object(spec.resources)[field]);
+    const overhead = quantities(spec.overhead);
+    for (const key of ["cpu", "memory"]) {
+      if (podLevel[key] !== undefined)
+        result[key] = parseComputeQuantity(podLevel[key]);
+      if (field === "requests" || result[key] > 0)
+        result[key] += overhead[key];
+    }
+    return result;
+  };
+  const without = zero();
+  for (const container of [...app, ...init]) {
+    const limits = object(object(container.resources).limits);
+    for (const key of ["cpu", "memory"])
+      if (limits[key] === undefined)
+        without[key]++;
+  }
+  const conditions = Array.isArray(status.conditions) ? status.conditions.map(object) : [];
+  const states = [
+    ...Array.isArray(status.containerStatuses) ? status.containerStatuses : [],
+    ...Array.isArray(status.initContainerStatuses) ? status.initContainerStatuses : []
+  ].map(object);
+  return {
+    namespace: requiredString(meta.namespace, "metadata.namespace"),
+    name: requiredString(meta.name, "metadata.name"),
+    uid: requiredString(meta.uid, "metadata.uid"),
+    createdAt: typeof meta.creationTimestamp === "string" ? meta.creationTimestamp : undefined,
+    node: typeof spec.nodeName === "string" && spec.nodeName ? spec.nodeName : undefined,
+    phase: requiredString(status.phase, "status.phase"),
+    ready: conditions.some((c) => c.type === "Ready" && c.status === "True"),
+    restarts: states.reduce((n, c) => n + (typeof c.restartCount === "number" ? c.restartCount : 0), 0),
+    containers: [...app, ...init.filter((c) => c.restartPolicy === "Always")].map((c) => String(c.name)),
+    requests: effective("requests"),
+    configuredLimits: effective("limits"),
+    containersWithoutLimits: without
+  };
+}
+function summarizePods(pods) {
+  const active = pods.filter((p) => p.phase !== "Succeeded" && p.phase !== "Failed");
+  const scheduled = active.filter((p) => p.node);
+  return {
+    pods: pods.length,
+    activePods: active.length,
+    scheduledPods: scheduled.length,
+    readyPods: active.filter((p) => p.ready).length,
+    requests: sum(active.map((p) => p.requests)),
+    scheduledRequests: sum(scheduled.map((p) => p.requests)),
+    configuredLimits: sum(active.map((p) => p.configuredLimits)),
+    containersWithoutLimits: sum(active.map((p) => p.containersWithoutLimits))
+  };
+}
+
+export { object, requiredString, parseComputeQuantity, zero, add, quantities, sum, podCompute, summarizePods };

package/dist/connection/acquire.d.ts

@@ -0,0 +1,34 @@
+import type { ClientLifecycle } from "../datasource";
+/** Stop waiting without leaving rejected preparation promises unobserved. */
+export declare function awaitWithSignal<T>(pending: Promise<T>, signal: AbortSignal, cancel?: () => void): Promise<T>;
+export interface ConnectionAttempt {
+    readonly signal: AbortSignal;
+    /** Remaining mapping + handshake budget, not a fresh timeout for each phase. */
+    remainingMs(): number;
+}
+interface Acquisition<R, C> {
+    name: string;
+    connectTimeoutMs: number;
+    acquireTimeoutMs?: number;
+    signal?: AbortSignal;
+    open(route: R, attempt: ConnectionAttempt): Promise<{
+        connection: C;
+        transport: string;
+    }>;
+    close(connection: C): void | Promise<void>;
+    /** Undefined means terminal; authentication and protocol errors must not change route. */
+    retryReason(error: unknown): string | undefined;
+    onRoute?: ClientLifecycle["onRoute"];
+}
+/**
+ * @spec One acquisition owns ordered attempts and a deadline covering mapping and handshake.
+ * @spec Cancellation keeps its original reason; a late successful connection is closed, never published.
+ * @rule Only connection preparation enters this function. Commands and queries must never be replayed.
+ * @why Protocol adapters own partial handles and error classification; all protocols share the same lifecycle.
+ * @see {@link component://docs/toolbox.md}
+ * @case id=connection_mapping_cancel,desc=`Cancel while mapping a route`,expect=`Acquisition exits without a late handshake`
+ */
+export declare function acquireConnection<R extends {
+    readonly name: string;
+}, C>(routes: readonly R[], options: Acquisition<R, C>): Promise<C>;
+export {};

package/dist/connection/acquire.js

@@ -0,0 +1,9 @@
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
+export {
+  awaitWithSignal,
+  acquireConnection
+};

package/dist/datasource.js

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

package/dist/errors.d.ts

@@ -13,6 +13,10 @@ export declare class KubernetesError extends ToolboxError {
 }
 export declare class FileError extends ToolboxError {
 }
+/** A local deadline expiry, distinct from a connection failure reported by a driver. */
+export declare class TimeoutError extends ToolboxError {
+    constructor(message: string, options?: ErrorOptions);
+}
 export declare function kubernetesHttpError(status: number): KubernetesError;
 /**
  * Normalize a failed kubectl resource request at the transport boundary.

package/dist/errors.js

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

package/dist/file/client.js

@@ -2,8 +2,8 @@ import {
   BoundedFileClient,
   fileClientOptions,
   filePaths
-} from "../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   filePaths,

package/dist/file/index.js

@@ -1,15 +1,15 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-grpygk6f.js";
+} from "../chunk-dx6yvj81.js";
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-sqbew04a.js";
-import"../chunk-kkts16w9.js";
+} from "../chunk-f3vq900j.js";
+import"../chunk-ww11q58v.js";
 import {
   FileError
-} from "../chunk-20kv4wc3.js";
+} from "../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/file/index.ts

package/dist/file/local.js

@@ -1,9 +1,9 @@
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-sqbew04a.js";
-import"../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-f3vq900j.js";
+import"../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   LocalFileDataSource,

package/dist/file/pod.js

@@ -1,9 +1,9 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-grpygk6f.js";
-import"../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-dx6yvj81.js";
+import"../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   PodFileDataSource,

package/dist/kubernetes/client.d.ts

@@ -23,6 +23,10 @@ export declare class KubernetesClient implements Client {
      */
     get(ref: ResourceRef, options?: ResourceRequestOptions): Promise<import("./resources").Resource>;
     list(query: ResourceListQuery, options?: ResourceRequestOptions): Promise<import("./resources").ResourceList>;
+    /** Explicit root scope for Nodes and all-namespace lists; no default namespace is inserted.
+     * @spec This view borrows root transport, cancellation and cleanup just like namespace views.
+     */
+    clusterResources(): ResourceAccess;
     inNamespace(namespace: string): NamespaceResources;
     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,15 +1,15 @@
 import {
   KubernetesClient
-} from "../chunk-8kts470p.js";
-import"../chunk-4ms037k2.js";
-import"../chunk-0s27bgga.js";
+} from "../chunk-g2bac2jd.js";
+import"../chunk-ae84rzq5.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-ftkrjqkc.js";
-import"../chunk-shsabpc1.js";
+import"../chunk-x0yhfg29.js";
+import"../chunk-dpcge1xt.js";
+import"../chunk-r3rnsvwv.js";
 import"../chunk-a9htb6cr.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";
 import"../chunk-hmah9t8e.js";

package/dist/kubernetes/compute-model.d.ts

@@ -0,0 +1,115 @@
+import type { ErrorKind } from "../errors";
+/** CPU cores and bytes; never percentages or unitless Kubernetes quantity strings. */
+export interface ComputeQuantity {
+    cpu: number;
+    memory: number;
+}
+export interface ComputeIssue {
+    source: string;
+    kind: ErrorKind;
+    message: string;
+    code?: string | number;
+}
+export interface ComputeRead<T> {
+    status: "complete" | "partial" | "unavailable";
+    items: T[];
+    issues: ComputeIssue[];
+}
+export interface ComputeUsage extends ComputeQuantity {
+    timestamp: string;
+    window: string;
+}
+export interface NodeCompute {
+    name: string;
+    uid: string;
+    ready: boolean;
+    unschedulable: boolean;
+    capacity: ComputeQuantity;
+    allocatable: ComputeQuantity;
+}
+export interface PodCompute {
+    namespace: string;
+    name: string;
+    uid: string;
+    createdAt?: string;
+    node?: string;
+    phase: string;
+    ready: boolean;
+    restarts: number;
+    /** Steady-state application and native sidecar container names, for metrics coverage. */
+    containers: string[];
+    /** Spec-based effective requests, including init/sidecar peak, Pod-level overrides and overhead. */
+    requests: ComputeQuantity;
+    /** Sum/peak of declared limits, NOT an upper bound when containers have no limit. */
+    configuredLimits: ComputeQuantity;
+    /** Container counts, not cores/bytes; a Pod-level budget can still apply. */
+    containersWithoutLimits: {
+        cpu: number;
+        memory: number;
+    };
+}
+export interface NodeComputeUsage extends ComputeUsage {
+    name: string;
+}
+export interface PodComputeUsage extends ComputeUsage {
+    namespace: string;
+    name: string;
+    uid: string;
+}
+export interface PodComputeSummary {
+    pods: number;
+    activePods: number;
+    scheduledPods: number;
+    readyPods: number;
+    /** Active Pods only; unscheduled requests are demand, not allocated node capacity. */
+    requests: ComputeQuantity;
+    scheduledRequests: ComputeQuantity;
+    configuredLimits: ComputeQuantity;
+    /** Container counts, not cores/bytes; a Pod-level budget can still apply. */
+    containersWithoutLimits: {
+        cpu: number;
+        memory: number;
+    };
+}
+export interface ClusterCompute {
+    environment: string;
+    observedAt: string;
+    scope: "cluster";
+    nodes: ComputeRead<NodeCompute>;
+    pods: ComputeRead<PodCompute>;
+    usage: ComputeRead<NodeComputeUsage>;
+    /** Totals describe acquired evidence only; consult each read's coverage before claiming cluster totals. */
+    summary: {
+        capacity?: ComputeQuantity;
+        allocatable?: ComputeQuantity;
+        pods?: PodComputeSummary;
+        usage?: ComputeQuantity;
+    };
+}
+export interface WorkloadCompute {
+    environment: string;
+    observedAt: string;
+    /** Scope is exactly the supplied instance set, not a claim of complete Service discovery. */
+    scope: "instances";
+    workloads: readonly {
+        namespace: string;
+        workload: string;
+        pod: string;
+        uid: string;
+    }[];
+    pods: ComputeRead<PodCompute>;
+    usage: ComputeRead<PodComputeUsage>;
+    summary: {
+        pods?: PodComputeSummary;
+        usage?: ComputeQuantity;
+    };
+}
+export interface ComputeOptions {
+    environment: string;
+    signal?: AbortSignal;
+    /** Whole collection budget, including all pages and metrics reads. */
+    timeoutMs: number;
+    maxPods: number;
+    maxNodes: number;
+    pageSize: number;
+}

package/dist/kubernetes/compute-quantity.d.ts

@@ -0,0 +1,18 @@
+import type { ComputeQuantity, PodCompute, PodComputeSummary } from "./compute-model";
+import type { Resource } from "./resources";
+type ObjectValue = Record<string, unknown>;
+export declare function object(value: unknown): ObjectValue;
+export declare function requiredString(value: unknown, field: string): string;
+/**
+ * @why client-node 1.4 quantityToScalar uses BigInt for binary suffixes and rejects valid fractional Gi values.
+ * @spec Quantities normalize to cores/bytes; invalid or unrepresentable values never become zero usage.
+ */
+export declare function parseComputeQuantity(value: unknown): number;
+export declare const zero: () => ComputeQuantity;
+export declare function add(left: ComputeQuantity, right: ComputeQuantity): ComputeQuantity;
+export declare function quantities(value: unknown, required?: boolean): ComputeQuantity;
+export declare function sum(values: readonly ComputeQuantity[]): ComputeQuantity;
+/** Spec projection only: do not claim current cgroup allocation or scheduler admission headroom. */
+export declare function podCompute(value: Resource): PodCompute;
+export declare function summarizePods(pods: readonly PodCompute[]): PodComputeSummary;
+export {};

package/dist/kubernetes/compute-quantity.js

@@ -0,0 +1,23 @@
+import {
+  add,
+  object,
+  parseComputeQuantity,
+  podCompute,
+  quantities,
+  requiredString,
+  sum,
+  summarizePods,
+  zero
+} from "../chunk-z15gwjvg.js";
+import"../chunk-rkt41za2.js";
+export {
+  zero,
+  summarizePods,
+  sum,
+  requiredString,
+  quantities,
+  podCompute,
+  parseComputeQuantity,
+  object,
+  add
+};

package/dist/kubernetes/compute.d.ts

@@ -0,0 +1,17 @@
+import type { WorkloadInstance } from "@compforge/harness-common";
+import type { ResourceAccess } from "./resources";
+import type { ClusterCompute, ComputeOptions, WorkloadCompute } from "./compute-model";
+export type * from "./compute-model";
+export { parseComputeQuantity } from "./compute-quantity";
+/**
+ * @spec Cluster reads are independent: forbidden Nodes/metrics are coverage gaps, not cluster-health failures.
+ * @rule access must be an explicit cluster-scoped view, e.g. KubernetesClient.clusterResources().
+ * No namespace fallback, client creation or cleanup occurs here.
+ */
+export declare function collectClusterCompute(access: ResourceAccess, options: ComputeOptions): Promise<ClusterCompute>;
+/**
+ * @spec Whole-Pod accounting deduplicates physical UID across Workload aliases and container defaults.
+ * @spec Only caller-supplied instances are read; cluster permissions are not needed.
+ * @rule The caller retains discovery coverage. This result never asserts that input covers all Service instances.
+ */
+export declare function collectWorkloadCompute(access: ResourceAccess, instances: readonly WorkloadInstance[], options: ComputeOptions): Promise<WorkloadCompute>;