@compforge/harness-toolbox 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,11 @@
 # Harness Toolbox
 
+Client, DataSource 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 and OpenSearch without depending on a particular
+clients to access Kubernetes, MySQL, Redis, OpenSearch and S3-compatible object storage without depending on a particular
 command, plugin protocol, test model or verdict.
 
 The package supports Node.js 22+ and Bun. Install with `npm install @compforge/harness-toolbox`.
@@ -45,3 +49,53 @@ capture policy, shared concurrency pool and byte budget; the package does not ch
 limits. Temporary capture files live until client disposal.
 
 See [toolbox contracts](../../../docs/toolbox.md) for ownership and cross-language semantics.
+
+## Read S3 objects
+
+S3 uses the official AWS SDK behind the same managed lifecycle. Supply resolved connection
+settings and explicit limits; the package does not discover business configuration or credentials.
+
+```ts
+import { ClientManager } from "@compforge/harness-toolbox";
+import { S3DataSource } from "@compforge/harness-toolbox/s3";
+
+const clients = new ClientManager();
+try {
+  const s3 = await clients.get(new S3DataSource({
+    endpoint: "https://s3.example.com", region: "us-east-1",
+    credentials: { accessKeyId: "...", secretAccessKey: "..." },
+  }, { concurrency: 4, connectTimeoutMs: 5_000, requestTimeoutMs: 15_000 }));
+  const object = await s3.headObject("artifacts", "runs/example.json");
+  const prefix = await s3.readObject("artifacts", "runs/example.json", { maxBytes: 65_536 });
+  // prefix.truncated distinguishes a bounded prefix from the complete object.
+} finally {
+  await clients.dispose();
+}
+```
+
+`listObjects` and `listBuckets` return one explicitly bounded page with continuation tokens;
+callers own traversal and total scan budgets. Bucket HEAD and versioning are also available.
+Errors preserve SDK status/code: a failed HEAD is not converted to `exists=false`. Reads stop at
+the byte cap and close the body; request deadlines include queueing and body consumption.
+No write operations, automatic retries or implicit region redirects are exposed.
+
+For a mapped TCP transport, pass `{ key: "cluster/context identity", transport }` as the third
+DataSource argument. The caller owns that transport's lifetime. Path-style addressing is required
+for mapped routes; direct endpoints also support virtual-hosted buckets. Signed Host and TLS
+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-94anqtxh.js

@@ -0,0 +1,35 @@
+import {
+  dataSourceKey
+} from "./chunk-fnc291vk.js";
+import {
+  S3Client
+} from "./chunk-zp1s833x.js";
+import {
+  DirectTransport
+} from "./chunk-xy4g56g4.js";
+
+// src/s3/datasource.ts
+class S3DataSource {
+  key;
+  #target;
+  #limits;
+  #transport;
+  constructor(target, limits, route) {
+    this.#target = structuredClone(target);
+    this.#limits = { ...limits };
+    this.#transport = route?.transport ?? new DirectTransport;
+    this.key = dataSourceKey("s3", {
+      target: this.#target,
+      limits: this.#limits,
+      route: route ? { key: route.key, transport: route.transport.name } : "direct"
+    });
+  }
+  createClient(signal) {
+    return new S3Client({
+      resolve: async () => this.#target,
+      transports: [this.#transport]
+    }, this.#limits, { signal });
+  }
+}
+
+export { S3DataSource };

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

@@ -1,9 +1,13 @@
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 import {
   queryMysqlViaPod
 } from "./chunk-s06hs7a8.js";
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "./chunk-kbewz29a.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 import {
   isConnectionNetworkError
 } from "./chunk-xy4g56g4.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-fnc291vk.js

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

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-vjsr2jb3.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-1vfwvgkj.js";
 import {
   dataSourceKey
-} from "./chunk-hqx7j9xe.js";
+} from "./chunk-fnc291vk.js";
 
 // src/kubernetes/pod-log-client.ts
 import { copyFileSync, mkdtempSync, rmSync } from "node:fs";

package/dist/chunk-x4ntb898.js

@@ -0,0 +1,46 @@
+// src/s3/handler.ts
+import { Agent as HttpAgent } from "node:http";
+import { Agent as HttpsAgent } from "node:https";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+function s3Handler(target, route, limits) {
+  const endpoint = new URL(target.endpoint);
+  const mapped = route.host !== endpoint.hostname || route.port !== Number(endpoint.port || (endpoint.protocol === "https:" ? 443 : 80));
+  if (mapped && target.forcePathStyle === false) {
+    throw new Error("S3 mapped transports require path-style addressing to preserve bucket and TLS identity");
+  }
+  const pool = { keepAlive: true, maxSockets: limits.concurrency, maxTotalSockets: limits.concurrency };
+  const httpAgent = new HttpAgent(pool);
+  const httpsAgent = new HttpsAgent({
+    ...pool,
+    ca: target.ca,
+    rejectUnauthorized: true,
+    ...mapped ? { servername: endpoint.hostname } : {}
+  });
+  const transport = new NodeHttpHandler({
+    httpAgent,
+    httpsAgent,
+    connectionTimeout: limits.connectTimeoutMs,
+    requestTimeout: limits.requestTimeoutMs,
+    throwOnRequestTimeout: true
+  });
+  const handler = {
+    handle(request, options) {
+      if (!mapped)
+        return transport.handle(request, options);
+      const routed = request.clone();
+      routed.hostname = route.host;
+      routed.port = route.port;
+      return transport.handle(routed, options);
+    },
+    destroy() {
+      transport.destroy();
+    }
+  };
+  return { handler, destroy: () => {
+    handler.destroy();
+    httpAgent.destroy();
+    httpsAgent.destroy();
+  } };
+}
+
+export { s3Handler };

package/dist/chunk-zp1s833x.js

@@ -0,0 +1,200 @@
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+import {
+  s3Handler
+} from "./chunk-x4ntb898.js";
+
+// src/s3/client.ts
+import {
+  S3Client as AwsS3Client,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  ListBucketsCommand,
+  ListObjectsV2Command,
+  GetBucketVersioningCommand,
+  GetObjectCommand
+} from "@aws-sdk/client-s3";
+import { Readable } from "node:stream";
+function positive(value, name, maximum = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+  }
+}
+function metadata(value) {
+  return {
+    size: value.ContentLength,
+    etag: value.ETag,
+    lastModified: value.LastModified,
+    contentType: value.ContentType,
+    versionId: value.VersionId,
+    metadata: value.Metadata ?? {}
+  };
+}
+
+class S3Client {
+  source;
+  limits;
+  lifecycle;
+  #controller = new AbortController;
+  signal;
+  #pool;
+  #operations = new Set;
+  #initialization;
+  #disposal;
+  #sdk;
+  #http;
+  constructor(source, limits, lifecycle = {}) {
+    this.source = source;
+    this.limits = limits;
+    this.lifecycle = lifecycle;
+    positive(limits.concurrency, "concurrency");
+    positive(limits.connectTimeoutMs, "connectTimeoutMs", 2147483647);
+    positive(limits.requestTimeoutMs, "requestTimeoutMs", 2147483647);
+    this.#pool = new ConcurrencyPool(limits.concurrency);
+    this.signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
+  }
+  initialize() {
+    this.signal.throwIfAborted();
+    return this.#initialization ??= this.#initialize();
+  }
+  async#initialize() {
+    const target = await this.source.resolve();
+    this.signal.throwIfAborted();
+    const url = new URL(target.endpoint);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+      throw new Error("S3 endpoint must be an HTTP(S) URL without embedded credentials, query or fragment");
+    }
+    const transport = this.source.transports[0];
+    if (!transport || transport.kind !== "tcp")
+      throw new Error("S3 requires a TCP transport");
+    const route = await transport.connect({
+      host: url.hostname,
+      port: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
+      servername: url.hostname
+    });
+    this.signal.throwIfAborted();
+    this.#http = s3Handler(target, route, this.limits);
+    this.#sdk = new AwsS3Client({
+      endpoint: target.endpoint,
+      region: target.region,
+      credentials: target.credentials,
+      forcePathStyle: target.forcePathStyle ?? true,
+      requestHandler: this.#http.handler,
+      maxAttempts: 1,
+      followRegionRedirects: false,
+      responseChecksumValidation: "WHEN_REQUIRED"
+    });
+    this.lifecycle.onRoute?.({ transport: transport.name });
+  }
+  #run(options, operation) {
+    this.signal.throwIfAborted();
+    const sdk = this.#sdk;
+    if (!sdk)
+      throw new Error("S3 client is not initialized");
+    const timeout = new AbortController;
+    const timer = setTimeout(() => timeout.abort(new Error("S3 request deadline exceeded")), this.limits.requestTimeoutMs);
+    timer.unref();
+    const signal = AbortSignal.any([this.signal, timeout.signal, ...options.signal ? [options.signal] : []]);
+    const pending = this.#pool.run(() => operation(sdk, signal), signal).finally(() => clearTimeout(timer));
+    this.#operations.add(pending);
+    pending.then(() => this.#operations.delete(pending), () => this.#operations.delete(pending));
+    return pending;
+  }
+  headBucket(bucket, options = {}) {
+    return this.#run(options, async (sdk, signal) => {
+      await sdk.send(new HeadBucketCommand({ Bucket: bucket }), { abortSignal: signal });
+    });
+  }
+  headObject(bucket, key, options = {}) {
+    return this.#run(options, async (sdk, signal) => metadata(await sdk.send(new HeadObjectCommand({ Bucket: bucket, Key: key, VersionId: options.versionId }), { abortSignal: signal })));
+  }
+  listObjects(bucket, options) {
+    positive(options.maxKeys, "maxKeys", 1000);
+    return this.#run(options, async (sdk, signal) => {
+      const page = await sdk.send(new ListObjectsV2Command({
+        Bucket: bucket,
+        MaxKeys: options.maxKeys,
+        Prefix: options.prefix,
+        Delimiter: options.delimiter,
+        ContinuationToken: options.continuationToken
+      }), { abortSignal: signal });
+      return {
+        objects: (page.Contents ?? []).filter((item) => item.Key !== undefined).map((item) => ({
+          key: item.Key,
+          size: item.Size,
+          etag: item.ETag,
+          lastModified: item.LastModified
+        })),
+        prefixes: (page.CommonPrefixes ?? []).flatMap((item) => item.Prefix === undefined ? [] : [item.Prefix]),
+        truncated: page.IsTruncated ?? false,
+        continuationToken: page.NextContinuationToken
+      };
+    });
+  }
+  listBuckets(options) {
+    positive(options.maxBuckets, "maxBuckets", 1e4);
+    return this.#run(options, async (sdk, signal) => {
+      const page = await sdk.send(new ListBucketsCommand({
+        MaxBuckets: options.maxBuckets,
+        ContinuationToken: options.continuationToken
+      }), { abortSignal: signal });
+      return { buckets: (page.Buckets ?? []).filter((item) => item.Name !== undefined).map((item) => ({ name: item.Name, creationDate: item.CreationDate })), continuationToken: page.ContinuationToken };
+    });
+  }
+  getBucketVersioning(bucket, options = {}) {
+    return this.#run(options, async (sdk, signal) => {
+      const result = await sdk.send(new GetBucketVersioningCommand({ Bucket: bucket }), { abortSignal: signal });
+      if (result.Status === "Enabled")
+        return "enabled";
+      return result.Status === "Suspended" ? "suspended" : "disabled";
+    });
+  }
+  readObject(bucket, key, options) {
+    positive(options.maxBytes, "maxBytes");
+    return this.#run(options, async (sdk, signal) => {
+      const result = await sdk.send(new GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        VersionId: options.versionId
+      }), { abortSignal: signal });
+      const body = result.Body;
+      if (!(body instanceof Readable))
+        throw new Error("S3 response is missing a Node readable body");
+      const abort = () => body.destroy(new Error("S3 object read aborted", { cause: signal.reason }));
+      signal.addEventListener("abort", abort, { once: true });
+      const chunks = [];
+      let size = 0;
+      let truncated = false;
+      try {
+        signal.throwIfAborted();
+        for await (const chunk of body) {
+          signal.throwIfAborted();
+          const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          const remaining = options.maxBytes - size;
+          chunks.push(Buffer.from(bytes.subarray(0, remaining)));
+          size += Math.min(remaining, bytes.length);
+          if (bytes.length > remaining || size === options.maxBytes && result.ContentLength !== undefined && result.ContentLength > size) {
+            truncated = true;
+            break;
+          }
+        }
+        return { ...metadata(result), bytes: Buffer.concat(chunks, size), truncated };
+      } finally {
+        signal.removeEventListener("abort", abort);
+        body.destroy();
+      }
+    });
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("S3 client disposed"));
+      await this.#initialization?.catch(() => {});
+      await Promise.allSettled(this.#operations);
+      this.#sdk?.destroy();
+      this.#http?.destroy();
+    })();
+  }
+}
+
+export { S3Client };

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, type ClientProvider } 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 type { Client } from "@compforge/harness-common";

package/dist/datasource.d.ts

@@ -1,13 +1,5 @@
-export type { Client } from "./client";
-export { ClientManager, type ClientProvider } from "./client-manager";
-import type { Client } from "./client";
+export { dataSourceKey, ClientManager, type Client, type ClientProvider, type DataSource, type ServiceDataSource } from "@compforge/harness-common";
 import type { Transport } from "./transport";
-/** Identity must include protocol, target, configuration and credentials; never an object address. */
-export interface DataSource<C extends Client> {
-    readonly key: string;
-    /** Construct only; Client.initialize owns external work. */
-    createClient(signal: AbortSignal): C;
-}
 /** Resolution owns configuration semantics; transports preserve the resolved target and identity. */
 export interface ConnectionSource<Target> {
     resolve(): Promise<Target>;
@@ -22,5 +14,3 @@ export interface ClientLifecycle {
         reason?: string;
     }) => void;
 }
-/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
-export declare function dataSourceKey(protocol: string, configuration: unknown): string;

package/dist/datasource.js

@@ -1,9 +1,7 @@
 import {
+  ClientManager,
   dataSourceKey
-} from "./chunk-hqx7j9xe.js";
-import {
-  ClientManager
-} from "./chunk-3dt25p98.js";
+} from "./chunk-fnc291vk.js";
 export {
   dataSourceKey,
   ClientManager

package/dist/kubernetes/client.js

@@ -2,12 +2,12 @@ import {
   ServicePortForwarder
 } from "../chunk-205a4vma.js";
 import"../chunk-hv2kx47y.js";
-import"../chunk-j46x7j7c.js";
-import"../chunk-6fnhzhdb.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 {

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

@@ -1,11 +1,10 @@
 import {
   PodLogClient
-} from "../chunk-1at7zs0z.js";
+} from "../chunk-vjsr2jb3.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
-import"../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+import"../chunk-fnc291vk.js";
 import"../chunk-v3hxvnrc.js";
 export {
   PodLogClient

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

@@ -1,13 +1,12 @@
 import {
   PodLogClient
-} from "../chunk-1at7zs0z.js";
+} from "../chunk-vjsr2jb3.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
 import {
   dataSourceKey
-} from "../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+} from "../chunk-fnc291vk.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts

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

@@ -2,10 +2,10 @@ import {
   ServicePortForwarder
 } from "../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-j46x7j7c.js";
+import"../chunk-6fnhzhdb.js";
 export {
   ServicePortForwarder
 };

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 } from "./types";
+import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult } from "./types";
 import type { ConnectionSource, ClientLifecycle } from "../datasource";
 import { type Transport } from "../transport";
 export interface MysqlDatabaseOptions extends ClientLifecycle {
@@ -16,6 +16,8 @@ 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[]>;
+    /** 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>;
     queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
     close(): Promise<void>;
@@ -28,7 +30,7 @@ export declare class MysqlClient<Target extends DatabaseTarget = DatabaseTarget>
     readonly signal: AbortSignal;
     constructor(source: ConnectionSource<Target>, options: MysqlDatabaseOptions);
     initialize(): Promise<void>;
-    get database(): Database;
+    get database(): MysqlDatabase;
     get target(): Target;
     dispose(): Promise<void>;
 }

package/dist/mysql/client.js

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

package/dist/mysql/index.js

@@ -1,14 +1,15 @@
-import {
-  MysqlClient,
-  MysqlDatabase,
-  openMysql
-} from "../chunk-mkhyty75.js";
-import"../chunk-v3hxvnrc.js";
 import {
   parseMysqlEnvTarget
 } from "../chunk-qq77x9ek.js";
 import"../chunk-pfar9cm3.js";
+import {
+  MysqlClient,
+  MysqlDatabase,
+  openMysql
+} from "../chunk-9x1apyp4.js";
 import"../chunk-s06hs7a8.js";
+import"../chunk-kbewz29a.js";
+import"../chunk-v3hxvnrc.js";
 import"../chunk-xy4g56g4.js";
 export {
   parseMysqlEnvTarget,

package/dist/mysql/readonly.d.ts

@@ -0,0 +1,9 @@
+import type { Connection } from "mysql2/promise";
+import type { DatabaseQueryLimits, DatabaseQueryResult } from "./types";
+export declare function validateQueryLimits(limits: DatabaseQueryLimits): void;
+/**
+ * Owns a disposable session: setup, execution and cancellation cannot affect another borrower.
+ * Caller must classify SQL and use a least-privilege identity. READ ONLY is not a SQL sandbox
+ * (for example routines and temporary tables need additional caller policy).
+ */
+export declare function queryReadonlySession(connection: Connection, sql: string, values: readonly unknown[], limits: DatabaseQueryLimits, signal?: AbortSignal): Promise<DatabaseQueryResult>;

package/dist/mysql/readonly.js

@@ -0,0 +1,8 @@
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "../chunk-kbewz29a.js";
+export {
+  validateQueryLimits,
+  queryReadonlySession
+};

package/dist/mysql/types.d.ts

@@ -8,6 +8,19 @@ export interface DatabaseTarget extends DatabaseIdentity {
     database: string;
 }
 export type DatabaseRow = Record<string, unknown>;
+export interface DatabaseQueryLimits {
+    timeoutMs: number;
+    maxRows: number;
+    /** Maximum retained UTF-8 JSON row bytes, not a limit on an individual wire packet. */
+    maxBytes: number;
+}
+export interface DatabaseQueryResult {
+    rows: DatabaseRow[];
+    columns: string[];
+    bytes: number;
+    truncated: boolean;
+    truncation?: "rows" | "bytes";
+}
 /** Storage-neutral operations shared by infrastructure consumers. */
 export interface Database {
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;

package/dist/redis/index.js

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

package/dist/s3/client.d.ts

@@ -0,0 +1,40 @@
+import type { Client } from "../client";
+import type { ClientLifecycle, ConnectionSource } from "../datasource";
+import type { S3Target, S3Limits, S3RequestOptions, S3ObjectMetadata, S3ObjectPage, S3BucketPage, S3ObjectRead } from "./types";
+/**
+ * @spec Read-only S3 operations share a bounded pool; no failed protocol operation is replayed.
+ * @spec HTTP errors retain SDK status/code, including ambiguous HEAD 403/404 responses.
+ * @why Initialization prepares a route without requiring account-wide bucket-list permission.
+ */
+export declare class S3Client implements Client {
+    #private;
+    private readonly source;
+    private readonly limits;
+    private readonly lifecycle;
+    readonly signal: AbortSignal;
+    constructor(source: ConnectionSource<S3Target>, limits: S3Limits, lifecycle?: ClientLifecycle);
+    initialize(): Promise<void>;
+    /** A failed HEAD remains an error, not a misleading exists=false. */
+    headBucket(bucket: string, options?: S3RequestOptions): Promise<void>;
+    headObject(bucket: string, key: string, options?: S3RequestOptions & {
+        versionId?: string;
+    }): Promise<S3ObjectMetadata>;
+    /** One bounded page; callers own traversal and total scan budgets. */
+    listObjects(bucket: string, options: S3RequestOptions & {
+        maxKeys: number;
+        prefix?: string;
+        delimiter?: string;
+        continuationToken?: string;
+    }): Promise<S3ObjectPage>;
+    listBuckets(options: S3RequestOptions & {
+        maxBuckets: number;
+        continuationToken?: string;
+    }): Promise<S3BucketPage>;
+    getBucketVersioning(bucket: string, options?: S3RequestOptions): Promise<"enabled" | "suspended" | "disabled">;
+    /** Read a bounded prefix. Own and close the response stream before returning the pool slot. */
+    readObject(bucket: string, key: string, options: S3RequestOptions & {
+        maxBytes: number;
+        versionId?: string;
+    }): Promise<S3ObjectRead>;
+    dispose(): Promise<void>;
+}

package/dist/s3/client.js

@@ -0,0 +1,8 @@
+import {
+  S3Client
+} from "../chunk-zp1s833x.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-x4ntb898.js";
+export {
+  S3Client
+};

package/dist/s3/datasource.d.ts

@@ -0,0 +1,14 @@
+import { type DataSource } 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;
+    constructor(target: S3Target, limits: S3Limits, route?: {
+        key: string;
+        transport: TcpTransport;
+    });
+    createClient(signal: AbortSignal): S3Client;
+}

package/dist/s3/datasource.js

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

package/dist/s3/handler.d.ts

@@ -0,0 +1,13 @@
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+import type { Endpoint } from "../transport";
+import type { S3Limits, S3Target } from "./types";
+/** Routing changes only the socket destination, never the signed HTTP Host or TLS identity. */
+export declare function s3Handler(target: S3Target, route: Endpoint, limits: S3Limits): {
+    handler: {
+        handle(request: Parameters<NodeHttpHandler["handle"]>[0], options: Parameters<NodeHttpHandler["handle"]>[1]): Promise<{
+            response: import("@smithy/core/transport").HttpResponse;
+        }>;
+        destroy(): void;
+    };
+    destroy: () => void;
+};

package/dist/s3/handler.js

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

package/dist/s3/index.d.ts

@@ -0,0 +1,3 @@
+export { S3Client } from "./client";
+export { S3DataSource } from "./datasource";
+export type * from "./types";

package/dist/s3/index.js

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

package/dist/s3/types.d.ts

@@ -0,0 +1,51 @@
+export interface S3Target {
+    endpoint: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    forcePathStyle?: boolean;
+    /** Additional trust is explicit; TLS verification is never disabled for a tunnel. */
+    ca?: string;
+}
+/** Root-owned policy, not product defaults. Request time includes queueing and body consumption. */
+export interface S3Limits {
+    concurrency: number;
+    connectTimeoutMs: number;
+    requestTimeoutMs: number;
+}
+export interface S3RequestOptions {
+    signal?: AbortSignal;
+}
+export interface S3ObjectMetadata {
+    size?: number;
+    etag?: string;
+    lastModified?: Date;
+    contentType?: string;
+    versionId?: string;
+    metadata: Record<string, string>;
+}
+export interface S3ObjectPage {
+    objects: Array<{
+        key: string;
+        size?: number;
+        etag?: string;
+        lastModified?: Date;
+    }>;
+    prefixes: string[];
+    truncated: boolean;
+    continuationToken?: string;
+}
+export interface S3BucketPage {
+    buckets: Array<{
+        name: string;
+        creationDate?: Date;
+    }>;
+    continuationToken?: string;
+}
+export interface S3ObjectRead extends S3ObjectMetadata {
+    bytes: Uint8Array;
+    truncated: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -57,6 +57,14 @@
       "types": "./dist/opensearch/*.d.ts",
       "import": "./dist/opensearch/*.js"
     },
+    "./s3": {
+      "types": "./dist/s3/index.d.ts",
+      "import": "./dist/s3/index.js"
+    },
+    "./s3/*": {
+      "types": "./dist/s3/*.d.ts",
+      "import": "./dist/s3/*.js"
+    },
     "./client": {
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
@@ -75,10 +83,13 @@
     "README.md"
   ],
   "dependencies": {
-    "mysql2": "3.23.1",
-    "@redis/client": "6.1.0",
-    "@opensearch-project/opensearch": "3.6.0",
+    "@compforge/harness-common": "0.0.1",
+    "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
+    "@opensearch-project/opensearch": "3.6.0",
+    "@redis/client": "6.1.0",
+    "@smithy/node-http-handler": "4.12.1",
+    "mysql2": "3.23.1",
     "node-fetch": "2.7.0"
   },
   "devDependencies": {

package/dist/chunk-3dt25p98.js

@@ -1,59 +0,0 @@
-// src/client-manager.ts
-class ClientManager {
-  #controller = new AbortController;
-  signal;
-  #clients = new Map;
-  #ready = [];
-  #disposal;
-  constructor(signal) {
-    this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
-  }
-  get(source) {
-    this.signal.throwIfAborted();
-    const existing = this.#clients.get(source.key);
-    if (existing)
-      return existing;
-    const pending = Promise.resolve().then(async () => {
-      this.signal.throwIfAborted();
-      const client = source.createClient(this.signal);
-      try {
-        await client.initialize();
-        this.signal.throwIfAborted();
-        this.#ready.push(client);
-        return client;
-      } catch (error) {
-        try {
-          await client.dispose();
-        } catch (cleanup) {
-          throw new AggregateError([error, cleanup], "Client initialization and cleanup failed");
-        }
-        throw error;
-      }
-    });
-    this.#clients.set(source.key, pending);
-    pending.catch(() => {
-      if (this.#clients.get(source.key) === pending)
-        this.#clients.delete(source.key);
-    });
-    return pending;
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error("Client manager disposed"));
-      const settled = await Promise.allSettled(this.#clients.values());
-      this.#clients.clear();
-      const errors = settled.flatMap((result) => result.status === "rejected" && result.reason instanceof AggregateError ? [result.reason] : []);
-      for (const client of this.#ready.splice(0).reverse()) {
-        try {
-          await client.dispose();
-        } catch (error) {
-          errors.push(error);
-        }
-      }
-      if (errors.length)
-        throw new AggregateError(errors, "Client cleanup failed");
-    })();
-  }
-}
-
-export { ClientManager };

package/dist/chunk-hqx7j9xe.js

@@ -1,14 +0,0 @@
-// src/datasource.ts
-import { createHash } from "node:crypto";
-function dataSourceKey(protocol, configuration) {
-  const canonical = (value) => {
-    if (Array.isArray(value))
-      return value.map(canonical);
-    if (value && typeof value === "object")
-      return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
-    return value;
-  };
-  return `${protocol}:${createHash("sha256").update(JSON.stringify(canonical(configuration))).digest("hex")}`;
-}
-
-export { dataSourceKey };