feat(sdk-ts): enterprise upgrade — observability, backpressure, ACKB batching, pool, typed responses (0.1.6)

All additive and backward-compatible; defaults unchanged (silent
observability, unbounded backpressure, ackBatch off, poolSize 1).

- Observability: injectable Logger + onTelemetry sink (zero hard deps);
  Connection extends EventEmitter emitting connect/disconnect/
  reconnect_scheduled; per-command latency, timeout, auth and
  backpressure telemetry. Consumer sink/logger errors are isolated
  (Telemetry.safely) so they can never break the transport hot path.
- Backpressure: optional maxInFlight bounds in-flight commands with a
  waiter queue (released on settle, cleared on teardown).
- ACK batching: opt-in Worker ackBatch coalesces ACKs into ACKB
  round-trips; a job stays active (lock renewed) until its batch is
  confirmed; slots are freed BEFORE event emits and the batcher settles
  each item exactly once even when a callback throws (adversarially
  verified error-path tests included).
- ConnectionPool: round-robin producer-side pool (Queue poolSize);
  workers intentionally stay single-connection.
- Typed responses: generic call<R> over exported response shapes;
  removed internal `as Record<string, unknown>` casts.
- CI: .github/workflows/sdk.yml runs both SDK suites (TS on bun+node,
  Python 3.10/3.12) against a real server on every sdk/src change;
  sdk-release.yml publishes with npm provenance, gated on the e2e suite.

e2e 100/100 on bun AND node; biome clean; build clean. Skeptic PASS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: egeominotti

.github/workflows/sdk-release.yml

@@ -0,0 +1,45 @@
+name: SDK Release (npm)
+
+# Publishes the TypeScript SDK to npm with build provenance
+# (https://docs.npmjs.com/generating-provenance-statements). Trigger by pushing
+# a tag like `sdk-ts-v1.0.0`. Requires an NPM_TOKEN secret (automation token).
+
+on:
+  push:
+    tags: ['sdk-ts-v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # required for npm provenance
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - name: Install server deps (for bun src/main.ts)
+        run: bun install --frozen-lockfile || bun install
+      - name: Build + verify SDK
+        working-directory: sdk/typescript
+        run: |
+          bun install --frozen-lockfile || bun install
+          bun run build
+          bun run check
+      - name: Test gate (never publish an untested tag)
+        working-directory: sdk/typescript
+        run: |
+          bun tests/integration.ts
+          bun tests/e2e.ts
+      - name: Publish with provenance
+        working-directory: sdk/typescript
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/sdk.yml

@@ -0,0 +1,82 @@
+name: SDK
+
+# CI for the polyglot client SDKs (sdk/typescript, sdk/python). Both spawn a
+# real server (bun src/main.ts) and run their e2e suites against it.
+
+on:
+  push:
+    branches: [main, master]
+    paths: ['sdk/**', 'src/**', '.github/workflows/sdk.yml']
+  pull_request:
+    paths: ['sdk/**', 'src/**', '.github/workflows/sdk.yml']
+
+concurrency:
+  group: sdk-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  typescript:
+    name: TypeScript (${{ matrix.runtime }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [bun, node]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install server deps (for bun src/main.ts)
+        run: bun install --frozen-lockfile || bun install
+      - name: Install + build SDK
+        working-directory: sdk/typescript
+        run: |
+          bun install --frozen-lockfile || bun install
+          bun run build
+      - name: Lint (biome)
+        working-directory: sdk/typescript
+        run: bun run check
+      - name: Integration + e2e (bun)
+        if: matrix.runtime == 'bun'
+        working-directory: sdk/typescript
+        run: |
+          bun tests/integration.ts
+          bun tests/e2e.ts
+      - name: Integration + e2e (node)
+        if: matrix.runtime == 'node'
+        working-directory: sdk/typescript
+        run: |
+          node --experimental-strip-types tests/integration.ts
+          node --experimental-strip-types tests/e2e.ts
+
+  python:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install server deps (for bun src/main.ts)
+        run: bun install --frozen-lockfile || bun install
+      - name: Set up venv + msgpack
+        working-directory: sdk/python
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install --quiet msgpack
+      - name: Integration + e2e
+        working-directory: sdk/python
+        run: |
+          .venv/bin/python tests/test_integration.py
+          .venv/bin/python tests/run_e2e.py

sdk/typescript/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to `bunqueue-client` (TypeScript SDK) are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6] - 2026-07-09
+
+Enterprise-grade hardening. All additive and backward-compatible; defaults are
+unchanged (observability is silent, backpressure unbounded, ACK batching off).
+
+### Added
+
+- **Observability.** Every `Connection`/`Queue`/`Worker`/`FlowProducer` accepts
+  an injectable `logger` and an `onTelemetry` sink (zero hard deps — bridge it to
+  OpenTelemetry/Prometheus yourself). `TelemetryEvent` is a typed union covering
+  per-command latency, connect/disconnect/reconnect, auth and backpressure.
+  `Connection` is now an `EventEmitter` emitting `connect` / `disconnect` /
+  `reconnect_scheduled`. Ships `noopLogger` (default) and `consoleLogger`.
+- **Backpressure.** `maxInFlight` bounds concurrent in-flight commands; callers
+  park until a slot frees instead of growing memory unbounded under load.
+- **ACK batching.** Opt-in `Worker({ ackBatch: { enabled: true } })` coalesces
+  completed-job ACKs into `ACKB` round-trips for higher throughput; a job stays
+  active (lock renewed) until its batch is confirmed.
+- **Connection pool.** `Queue({ poolSize: N })` fans producer commands across N
+  round-robin connections (`ConnectionPool`, producer-side; workers stay single-
+  connection by design).
+- **Typed responses.** `call<R>()` is generic over the exported response shapes
+  (`JobResponse`, `PulledJobsResponse`, `JobCountsResponse`, …); internal
+  `as Record<string, unknown>` casts removed across the query/control/flow paths.
+
+### CI
+
+- GitHub Actions runs both SDK suites on every `sdk/`/`src/` change (TypeScript
+  on Bun + Node, Python 3.10/3.12); an npm release workflow publishes with
+  build provenance.
+
 ## [0.1.5] - 2026-07-08
 
 Protocol-coherence audit against the bunqueue server. Every fix ships with a

sdk/typescript/README.md

@@ -272,6 +272,49 @@ const queue = new Queue('emails', {
 
 Authentication uses server side tokens (`AUTH_TOKENS`). Transport security uses native TLS, with support for system certificate authorities, a custom CA bundle, or disabled verification for development environments.
 
+## Observability
+
+Inject a logger and a telemetry sink to bridge the client into your stack. There are no hard dependencies — you wire OpenTelemetry, Prometheus or your own logger. Defaults are silent.
+
+```typescript
+import { Queue, consoleLogger, type TelemetryEvent } from 'bunqueue-client';
+
+const queue = new Queue('emails', {
+  logger: consoleLogger('info'), // or your own { debug, info, warn, error }
+  onTelemetry: (e: TelemetryEvent) => {
+    // per-command latency, connect/disconnect/reconnect, auth, backpressure
+    if (e.type === 'command') metrics.observe(e.cmd, e.durationMs, e.ok);
+  },
+});
+
+// Connection is an EventEmitter for lifecycle hooks:
+queue.connection.on('reconnect_scheduled', (i) => log.warn('reconnecting', i));
+queue.connection.on('disconnect', () => log.warn('link down'));
+```
+
+## Throughput and resilience
+
+```typescript
+// Bound in-flight commands (backpressure) — parks callers instead of growing memory:
+const queue = new Queue('emails', { maxInFlight: 10_000 });
+
+// Fan producer commands across N connections (round-robin, producer-side):
+const pooled = new Queue('emails', { poolSize: 4 });
+
+// Batch worker ACKs into ACKB round-trips (opt-in) for high-volume consumers:
+const worker = new Worker('emails', process, {
+  ackBatch: { enabled: true, maxSize: 50, maxDelayMs: 5 },
+});
+```
+
+Always attach a `worker.on('error', …)` listener: per Node `EventEmitter` semantics an unhandled `error` event throws. The worker frees each job's concurrency slot before emitting, so even a throwing listener cannot degrade throughput — but the error itself is yours to observe.
+
+Half-open links are detected via TCP keepalive and a consecutive-timeout teardown, so a silently dropped connection (cloud LB/NAT idle drop) recovers in seconds rather than minutes.
+
+## Typed responses
+
+`connection.call<R>()` and `queue.call<R>()` are generic over the exported response shapes (`JobResponse`, `PulledJobsResponse`, `JobCountsResponse`, `WaitJobResponse`, …), so raw command access is fully typed without casting.
+
 ## API surface
 
 | Area | Capabilities |

sdk/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Cross-runtime TypeScript client for the bunqueue job queue server \u2014 Node.js, Bun, Deno and Cloudflare Workers",
   "license": "MIT",
   "type": "module",

sdk/typescript/src/ack-batcher.ts

@@ -0,0 +1,76 @@
+/**
+ * Batches completed-job ACKs into ACKB round-trips for higher throughput.
+ *
+ * Opt-in (see WorkerOptions.ackBatch). Items flush when the buffer reaches
+ * `maxSize` or after `maxDelayMs`, whichever comes first; `flush()` drains the
+ * rest on shutdown. Each item's `onSettled` fires after the batch is acked
+ * (or errored), so the worker keeps a job "active" — and its lock renewed —
+ * until the server has confirmed the ack.
+ */
+
+import type { Connection } from './connection.js';
+import { compact } from './frame.js';
+
+export interface AckItem {
+  id: string;
+  token: string;
+  result: unknown;
+  /** Called once the batch settles: `err` set on failure, undefined on ack. */
+  onSettled: (err?: unknown) => void;
+}
+
+export class AckBatcher {
+  private buffer: AckItem[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly connection: Connection,
+    private readonly maxSize: number,
+    private readonly maxDelayMs: number
+  ) {}
+
+  add(item: AckItem): void {
+    this.buffer.push(item);
+    if (this.buffer.length >= this.maxSize) {
+      void this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => void this.flush(), this.maxDelayMs);
+      this.timer.unref?.(); // don't keep the process alive for a pending flush
+    }
+  }
+
+  /** Send the buffered ACKs as one ACKB (no-op when empty). */
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    // Capture the wire outcome first; settle callbacks run OUTSIDE the try so
+    // a throwing callback can neither be re-invoked with an error (double
+    // settle) nor starve the remaining items of their callback.
+    let error: unknown;
+    try {
+      await this.connection.call(
+        compact({
+          cmd: 'ACKB',
+          ids: batch.map((b) => b.id),
+          tokens: batch.map((b) => b.token),
+          results: batch.map((b) => b.result),
+        }) as { cmd: string }
+      );
+    } catch (err) {
+      error = err ?? new Error('ACKB failed');
+    }
+    for (const item of batch) {
+      try {
+        item.onSettled(error);
+      } catch {
+        // A callback error (e.g. an unhandled 'error' emit in the worker)
+        // must never prevent the other items from settling.
+      }
+    }
+  }
+}

sdk/typescript/src/backpressure.ts

@@ -0,0 +1,40 @@
+/**
+ * Backpressure gate: bounds the number of in-flight commands on a connection.
+ *
+ * When the in-flight count reaches `max`, `acquire()` parks the caller until a
+ * slot frees (a pending command settles). This turns unbounded memory growth
+ * under a fast producer / slow server into cooperative flow control. `max <= 0`
+ * disables the gate (unbounded, the default).
+ */
+export class Backpressure {
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(
+    private readonly max: number,
+    private readonly onWait?: () => void
+  ) {}
+
+  /** Resolve immediately if under the limit, else park until a slot frees. */
+  acquire(inFlight: number): Promise<void> | void {
+    if (this.max <= 0 || inFlight < this.max) return;
+    this.onWait?.();
+    return new Promise<void>((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  /** Release one parked caller (call when a pending command settles). */
+  release(): void {
+    this.waiters.shift()?.();
+  }
+
+  /** Release every parked caller (call on teardown so none hang forever). */
+  clear(): void {
+    while (this.waiters.length > 0) this.waiters.shift()?.();
+  }
+
+  /** Number of callers currently parked. */
+  get waiting(): number {
+    return this.waiters.length;
+  }
+}