@smoothbricks/lmao 0.1.4 → 0.2.1

package/src/lib/cloudflare/__tests__/classSplit.test.ts

@@ -0,0 +1,171 @@
+// Configure Node.js timestamp implementation - MUST be first import
+import '../../__tests__/test-helpers.js';
+
+import { describe, expect, it } from 'bun:test';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineLogSchema, defineOpContext, S } from '../../defineOpContext.js';
+import { Err, Ok } from '../../result.js';
+import { ClassSplitTracer, type DeliveryClassifier } from '../classSplit.js';
+import { type CollectorSendFailure, FakeCollectorClient } from '../collectorClient.js';
+import type { TraceRow } from '../traceRows.js';
+
+const testSchema = defineLogSchema({
+  lane: S.category(),
+});
+
+const opContext = defineOpContext({ logSchema: testSchema });
+const { defineOp } = opContext;
+
+// Injected classifier seam — here: a row is billing-grade iff it carries the billing lane tag.
+const classifyByLane: DeliveryClassifier = (row) => (row.lane === 'billing' ? 'billing-grade' : 'diagnostic');
+
+const billableOp = defineOp('billable', (ctx) => {
+  ctx.tag.lane('billing');
+  return ctx.ok('charged');
+});
+
+const diagnosticOp = defineOp('diagnostic', (ctx) => ctx.ok('observed'));
+
+interface Harness {
+  tracer: ClassSplitTracer<typeof opContext>;
+  collector: FakeCollectorClient;
+  diagnosticBatches: (readonly TraceRow[])[];
+  diagnosticErrors: unknown[];
+  lateFailures: CollectorSendFailure[];
+}
+
+function makeHarness(options?: { diagnosticsFail?: boolean }): Harness {
+  const collector = new FakeCollectorClient();
+  const diagnosticBatches: (readonly TraceRow[])[] = [];
+  const diagnosticErrors: unknown[] = [];
+  const lateFailures: CollectorSendFailure[] = [];
+  const tracer = new ClassSplitTracer(opContext, {
+    ...createTestTracerOptions(),
+    collector,
+    diagnostics: {
+      send: async (rows) => {
+        if (options?.diagnosticsFail) throw new Error('diagnostic lane down');
+        diagnosticBatches.push(rows);
+      },
+    },
+    classify: classifyByLane,
+    onDiagnosticSendError: (error) => {
+      diagnosticErrors.push(error);
+    },
+    onLateBillableSendFailure: (failure) => {
+      lateFailures.push(failure);
+    },
+  });
+  return { tracer, collector, diagnosticBatches, diagnosticErrors, lateFailures };
+}
+
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe('ClassSplitTracer', () => {
+  describe('settleBillable (awaited within the request)', () => {
+    it('returns Ok(null) when the request produced no billing-grade rows', async () => {
+      const { tracer, collector, diagnosticBatches } = makeHarness();
+      await tracer.trace('req', diagnosticOp);
+
+      const settled = await tracer.settleBillable();
+      expect(settled).toBeInstanceOf(Ok);
+      if (settled instanceof Ok) expect(settled.value).toBeNull();
+      expect(collector.acked).toHaveLength(0);
+      // Diagnostic rows are staged, not sent yet — that is flush()'s lazy job.
+      expect(diagnosticBatches).toHaveLength(0);
+    });
+
+    it('sends billing-grade rows to the collector and resolves only on its ack', async () => {
+      const { tracer, collector } = makeHarness();
+      collector.holdSends();
+      await tracer.trace('req', billableOp);
+
+      let settledFlag = false;
+      const pending = tracer.settleBillable().then((result) => {
+        settledFlag = true;
+        return result;
+      });
+
+      await tick();
+      // Send-before-response: the request must still be blocked here.
+      expect(settledFlag).toBe(false);
+      expect(collector.pendingCount).toBe(1);
+
+      collector.ackNext();
+      const settled = await pending;
+      expect(settled).toBeInstanceOf(Ok);
+      expect(collector.acked).toHaveLength(1);
+      expect(collector.acked[0].every((row) => row.lane === 'billing')).toBe(true);
+      // No billing-grade rows may remain buffered in the isolate.
+      expect(tracer.queue).toHaveLength(0);
+    });
+
+    it('returns Err when the collector is unavailable — the billable request must fail', async () => {
+      const { tracer, collector } = makeHarness();
+      collector.failNext({ code: 'collector-unavailable', message: 'shard down' });
+      await tracer.trace('req', billableOp);
+
+      const settled = await tracer.settleBillable();
+      expect(settled).toBeInstanceOf(Err);
+      if (settled instanceof Err) expect(settled.error.code).toBe('collector-unavailable');
+    });
+
+    it('routes rows of one trace to both lanes per the injected classifier', async () => {
+      const { tracer, collector, diagnosticBatches } = makeHarness();
+      await tracer.trace('req', billableOp);
+      await tracer.trace('req', diagnosticOp);
+
+      const settled = await tracer.settleBillable();
+      expect(settled).toBeInstanceOf(Ok);
+      expect(collector.acked).toHaveLength(1);
+
+      await tracer.flush();
+      expect(diagnosticBatches).toHaveLength(1);
+      const diagnosticRows = diagnosticBatches[0];
+      expect(diagnosticRows.length).toBeGreaterThan(0);
+      expect(diagnosticRows.every((row) => row.lane !== 'billing')).toBe(true);
+    });
+  });
+
+  describe('flush (lazy, waitUntil-schedulable)', () => {
+    it('sends staged + newly drained diagnostic rows and never rejects on transport failure', async () => {
+      const { tracer, diagnosticErrors } = makeHarness({ diagnosticsFail: true });
+      await tracer.trace('req', diagnosticOp);
+
+      await tracer.flush();
+      expect(diagnosticErrors).toHaveLength(1);
+      expect(diagnosticErrors[0]).toBeInstanceOf(Error);
+    });
+
+    it('still delivers billing rows found at flush time (settle skipped), awaited', async () => {
+      const { tracer, collector, lateFailures } = makeHarness();
+      await tracer.trace('req', billableOp);
+
+      await tracer.flush();
+      expect(collector.acked).toHaveLength(1);
+      expect(lateFailures).toHaveLength(0);
+    });
+
+    it('escalates late billable send failures via onLateBillableSendFailure without rejecting', async () => {
+      const { tracer, collector, lateFailures } = makeHarness();
+      collector.failNext({ code: 'collector-rejected', message: 'commit failed' });
+      await tracer.trace('req', billableOp);
+
+      await tracer.flush();
+      expect(lateFailures).toHaveLength(1);
+      expect(lateFailures[0].code).toBe('collector-rejected');
+    });
+
+    it('does not resend diagnostic rows on a second flush', async () => {
+      const { tracer, diagnosticBatches } = makeHarness();
+      await tracer.trace('req', diagnosticOp);
+
+      await tracer.settleBillable();
+      await tracer.flush();
+      await tracer.flush();
+      expect(diagnosticBatches).toHaveLength(1);
+    });
+  });
+});

package/src/lib/cloudflare/__tests__/collectorClient.test.ts

@@ -0,0 +1,104 @@
+// Configure Node.js timestamp implementation - MUST be first import
+import '../../__tests__/test-helpers.js';
+
+import { describe, expect, it } from 'bun:test';
+import { Err, Ok } from '../../result.js';
+import { COLLECTOR_ACK, FakeCollectorClient } from '../collectorClient.js';
+import type { TraceRow } from '../traceRows.js';
+
+const rows: TraceRow[] = [
+  {
+    trace_id: 't1',
+    span_id: 1,
+    parent_span_id: 0,
+    row_index: 0,
+    entry_type: 1,
+    timestamp_ns: 1_000_000,
+    message: 'op',
+  },
+];
+
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe('CollectorClient contract (via FakeCollectorClient)', () => {
+  describe('ack semantics', () => {
+    it('resolves Ok with the durability ack and records the batch', async () => {
+      const client = new FakeCollectorClient();
+      const result = await client.send(rows);
+
+      expect(result).toBeInstanceOf(Ok);
+      if (result instanceof Ok) expect(result.value).toBe(COLLECTOR_ACK);
+      expect(client.acked).toEqual([rows]);
+    });
+
+    it('send resolves ONLY when the collector acks (durability point)', async () => {
+      const client = new FakeCollectorClient();
+      client.holdSends();
+
+      let settled = false;
+      const pending = client.send(rows).then((result) => {
+        settled = true;
+        return result;
+      });
+
+      await tick();
+      // No ack yet — the send-before-response contract means the caller is still blocked here.
+      expect(settled).toBe(false);
+      expect(client.pendingCount).toBe(1);
+      expect(client.acked).toHaveLength(0);
+
+      client.ackNext();
+      const result = await pending;
+      expect(settled).toBe(true);
+      expect(result).toBeInstanceOf(Ok);
+      expect(client.acked).toEqual([rows]);
+    });
+
+    it('supports injected ack latency', async () => {
+      const client = new FakeCollectorClient();
+      client.setLatency(20);
+
+      const start = Date.now();
+      const result = await client.send(rows);
+      expect(result).toBeInstanceOf(Ok);
+      expect(Date.now() - start).toBeGreaterThanOrEqual(15);
+    });
+  });
+
+  describe('failure semantics', () => {
+    it('returns Err (never throws) on injected failure — the billable request must fail', async () => {
+      const client = new FakeCollectorClient();
+      client.failNext({ code: 'collector-unavailable', message: 'shard down' });
+
+      const result = await client.send(rows);
+      expect(result).toBeInstanceOf(Err);
+      if (result instanceof Err) expect(result.error.code).toBe('collector-unavailable');
+      // A failed send is NOT durable — nothing may be recorded as acked.
+      expect(client.acked).toHaveLength(0);
+    });
+
+    it('held sends can be rejected with an operational failure', async () => {
+      const client = new FakeCollectorClient();
+      client.holdSends();
+
+      const pending = client.send(rows);
+      client.rejectNext({ code: 'collector-rejected', message: 'storage commit failed' });
+
+      const result = await pending;
+      expect(result).toBeInstanceOf(Err);
+      if (result instanceof Err) expect(result.error.code).toBe('collector-rejected');
+      expect(client.acked).toHaveLength(0);
+    });
+
+    it('recovers after a failure: subsequent sends ack normally', async () => {
+      const client = new FakeCollectorClient();
+      client.failNext({ code: 'collector-unavailable', message: 'blip' });
+
+      expect(await client.send(rows)).toBeInstanceOf(Err);
+      expect(await client.send(rows)).toBeInstanceOf(Ok);
+      expect(client.acked).toEqual([rows]);
+    });
+  });
+});

package/src/lib/cloudflare/__tests__/diagnosticDrain.test.ts

@@ -0,0 +1,165 @@
+// Configure Node.js timestamp implementation - MUST be first import
+import '../../__tests__/test-helpers.js';
+
+import { describe, expect, it } from 'bun:test';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineLogSchema, defineOpContext, S } from '../../defineOpContext.js';
+import {
+  DiagnosticDrainTracer,
+  PipelinesStreamTransport,
+  QueuesFallbackTransport,
+  type TraceChunkQueueMessage,
+} from '../diagnosticDrain.js';
+import type { TraceRow } from '../traceRows.js';
+
+const testSchema = defineLogSchema({
+  userId: S.category(),
+});
+
+const opContext = defineOpContext({ logSchema: testSchema });
+const { defineOp } = opContext;
+
+function makeRows(count: number): TraceRow[] {
+  const rows: TraceRow[] = [];
+  for (let i = 0; i < count; i++) {
+    rows.push({
+      trace_id: 'trace-x',
+      span_id: 1,
+      parent_span_id: 0,
+      row_index: i,
+      entry_type: 1,
+      timestamp_ns: (i + 1) * 1_000_000,
+      message: null,
+    });
+  }
+  return rows;
+}
+
+describe('DiagnosticDrainTracer', () => {
+  it('flush drains completed roots and sends them as rows through the Pipelines-shaped binding', async () => {
+    const sentBatches: TraceRow[][] = [];
+    // env.TRACE_STREAM.send-shaped fn — array of JSON-serializable records, resolves on ingest.
+    const transport = new PipelinesStreamTransport(async (rows) => {
+      sentBatches.push(rows);
+    });
+    const tracer = new DiagnosticDrainTracer(opContext, { ...createTestTracerOptions(), transport });
+    const { trace, flush } = tracer;
+
+    const op = defineOp('work', (ctx) => {
+      ctx.tag.userId('user-1');
+      return ctx.ok('done');
+    });
+    await trace('first', op);
+    await trace('second', op);
+
+    expect(tracer.queue).toHaveLength(2);
+    await flush();
+
+    // One send per completed root buffer, queue fully drained.
+    expect(tracer.queue).toHaveLength(0);
+    expect(sentBatches).toHaveLength(2);
+
+    const firstRows = sentBatches[0];
+    expect(firstRows.length).toBeGreaterThan(0);
+    expect(firstRows[0].trace_id).toBeString();
+    expect(firstRows[0].message).toBe('first');
+    expect(firstRows[0].entry_type).toBeNumber();
+    expect(firstRows[0].timestamp_ns).toBeNumber();
+    // User schema columns ride flat on the row.
+    expect(firstRows.some((row) => row.userId === 'user-1')).toBe(true);
+    // Rows must be JSON-serializable records.
+    expect(JSON.parse(JSON.stringify(firstRows))).toEqual(firstRows);
+  });
+
+  it('flush never rejects on transport failure — errors surface via onSendError only', async () => {
+    const errors: { error: unknown; rows: readonly TraceRow[] }[] = [];
+    const tracer = new DiagnosticDrainTracer(opContext, {
+      ...createTestTracerOptions(),
+      transport: {
+        send: () => Promise.reject(new Error('pipeline unavailable')),
+      },
+      onSendError: (error, rows) => {
+        errors.push({ error, rows });
+      },
+    });
+    const { trace, flush } = tracer;
+
+    const op = defineOp('work', (ctx) => ctx.ok('done'));
+    await trace('doomed', op);
+
+    await flush();
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].error).toBeInstanceOf(Error);
+    expect(errors[0].rows.length).toBeGreaterThan(0);
+    // Buffers are consumed even on failure — no unbounded isolate accumulation.
+    expect(tracer.queue).toHaveLength(0);
+  });
+
+  it('flush with an empty queue is a no-op', async () => {
+    const sentBatches: TraceRow[][] = [];
+    const tracer = new DiagnosticDrainTracer(opContext, {
+      ...createTestTracerOptions(),
+      transport: new PipelinesStreamTransport(async (rows) => {
+        sentBatches.push(rows);
+      }),
+    });
+
+    await tracer.flush();
+    expect(sentBatches).toHaveLength(0);
+  });
+});
+
+describe('QueuesFallbackTransport', () => {
+  it('ships batched chunk-envelope messages, never per-span messages', async () => {
+    const messages: TraceChunkQueueMessage[] = [];
+    const transport = new QueuesFallbackTransport({
+      fileRef: 'queue://test-worker',
+      maxRowsPerMessage: 2,
+      sendMessage: async (message) => {
+        messages.push(message);
+      },
+    });
+
+    await transport.send(makeRows(5));
+
+    expect(messages).toHaveLength(3);
+    expect(messages.map((m) => m.rows.length)).toEqual([2, 2, 1]);
+    for (const message of messages) {
+      expect(message.envelope.chunk_id).toStartWith('chunk_');
+      expect(message.envelope.file_ref).toBe('queue://test-worker');
+      expect(message.envelope.row_count).toBe(message.rows.length);
+      expect(message.envelope.started_at_ms).toBeLessThanOrEqual(message.envelope.ended_at_ms);
+    }
+  });
+
+  it('chunk_id is deterministic for the same batch — redelivery dedupes by chunk_id', async () => {
+    const chunkIds: string[] = [];
+    const transport = new QueuesFallbackTransport({
+      fileRef: 'queue://test-worker',
+      maxRowsPerMessage: 10,
+      sendMessage: async (message) => {
+        chunkIds.push(message.envelope.chunk_id);
+      },
+    });
+
+    const batch = makeRows(3);
+    await transport.send(batch);
+    await transport.send(batch);
+    await transport.send(makeRows(4));
+
+    expect(chunkIds[0]).toBe(chunkIds[1]);
+    expect(chunkIds[2]).not.toBe(chunkIds[0]);
+  });
+
+  it('rejects a non-positive batch size at construction', () => {
+    expect(
+      () =>
+        new QueuesFallbackTransport({
+          fileRef: 'queue://test-worker',
+          maxRowsPerMessage: 0,
+          sendMessage: async () => {},
+        }),
+    ).toThrow('maxRowsPerMessage');
+  });
+});

package/src/lib/cloudflare/classSplit.ts

@@ -0,0 +1,139 @@
+/**
+ * Class-split flush adapter — routes each completed root buffer's rows by delivery class.
+ *
+ * Per specs/lmao/01u_cloudflare_trace_segments.md §Delivery Classes every trace row belongs to
+ * exactly one class:
+ * - billing-grade rows go to the CollectorClient, AWAITED within the request via
+ *   `settleBillable()` before/alongside response completion — an Err fails the billable request
+ *   (backpressure ownership: never silently queue billing-grade rows in the isolate)
+ * - diagnostic rows go to the drain transport lazily, on the waitUntil-scheduled `flush()`
+ *
+ * The classifier is an injected function: the spec fixes the CLASSES, not the classification
+ * mechanism, so the mapping from row to class stays a seam (constructor-injected like the
+ * transports).
+ *
+ * Canonical request flow (01s wrapper seam):
+ *   const settled = await tracer.settleBillable();   // before returning the response
+ *   if (settled instanceof Err) return failBillableRequest(settled.error);
+ *   ctx.waitUntil(tracer.flush());                    // diagnostics, fire-and-forget
+ */
+
+import type { OpContextBinding } from '../opContext/types.js';
+import { Err, Ok, type Result } from '../result.js';
+import type { TracerOptions } from '../tracer.js';
+import { ArrayQueueTracer } from '../tracers/ArrayQueueTracer.js';
+import type { CollectorAck, CollectorClient, CollectorSendFailure } from './collectorClient.js';
+import type { DiagnosticTransport } from './diagnosticDrain.js';
+import { spanBufferToTraceRows, type TraceRow } from './traceRows.js';
+
+export type DeliveryClass = 'billing-grade' | 'diagnostic';
+
+/** Injected classification seam — decides which lane one row rides. */
+export type DeliveryClassifier = (row: TraceRow) => DeliveryClass;
+
+/** Singleton for the common "nothing billable in this request" settle outcome. */
+const SETTLED_NOTHING_BILLABLE: Ok<null> = new Ok(null);
+
+export interface ClassSplitOptions<
+  T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema,
+> extends TracerOptions<T> {
+  collector: CollectorClient;
+  diagnostics: DiagnosticTransport;
+  classify: DeliveryClassifier;
+  /** Diagnostic-lane failure hook: emit metrics; drop is within the class's loss budget. */
+  onDiagnosticSendError?: (error: unknown, rows: readonly TraceRow[]) => void;
+  /**
+   * Billing rows found only at flush() time (the wrapper skipped settleBillable) whose late
+   * awaited send failed. This is a broken-integration alarm — page on it; the rows are lost to
+   * this isolate and only replay/reconciliation (01u §Zero-Loss Sources) can heal the gap.
+   */
+  onLateBillableSendFailure?: (failure: CollectorSendFailure, rows: readonly TraceRow[]) => void;
+}
+
+interface PartitionedRows {
+  billing: TraceRow[];
+  diagnostic: TraceRow[];
+}
+
+/**
+ * Tracer tying the two lanes together over onTraceEnd (queue) + settleBillable/flush (drain).
+ *
+ * Diagnostic rows discovered during settleBillable are held for the same request's flush() —
+ * request-scoped staging only, never cross-request accumulation of billing-grade data.
+ */
+export class ClassSplitTracer<B extends OpContextBinding = OpContextBinding> extends ArrayQueueTracer<B> {
+  private readonly collector: CollectorClient;
+  private readonly diagnostics: DiagnosticTransport;
+  private readonly classify: DeliveryClassifier;
+  private readonly onDiagnosticSendError: ((error: unknown, rows: readonly TraceRow[]) => void) | undefined;
+  private readonly onLateBillableSendFailure:
+    | ((failure: CollectorSendFailure, rows: readonly TraceRow[]) => void)
+    | undefined;
+  private pendingDiagnosticRows: TraceRow[] = [];
+
+  constructor(binding: B, options: ClassSplitOptions<B['logBinding']['logSchema']>) {
+    super(binding, options);
+    this.collector = options.collector;
+    this.diagnostics = options.diagnostics;
+    this.classify = options.classify;
+    this.onDiagnosticSendError = options.onDiagnosticSendError;
+    this.onLateBillableSendFailure = options.onLateBillableSendFailure;
+  }
+
+  private partitionDrained(): PartitionedRows {
+    const billing: TraceRow[] = [];
+    const diagnostic: TraceRow[] = [];
+    for (const buffer of this.drain()) {
+      let rows: TraceRow[];
+      try {
+        rows = spanBufferToTraceRows(buffer);
+      } finally {
+        this.bufferStrategy.releaseBuffer(buffer);
+      }
+      for (const row of rows) {
+        (this.classify(row) === 'billing-grade' ? billing : diagnostic).push(row);
+      }
+    }
+    return { billing, diagnostic };
+  }
+
+  /**
+   * Drain completed traces and durably deliver the billing-grade rows — awaited within the
+   * request. Ok(null) means no billing rows were produced; Err means the collector could not
+   * make the revenue records durable and the billable request must fail. Diagnostic rows are
+   * staged for this request's flush().
+   */
+  async settleBillable(): Promise<Result<CollectorAck | null, CollectorSendFailure>> {
+    const { billing, diagnostic } = this.partitionDrained();
+    this.pendingDiagnosticRows.push(...diagnostic);
+    if (billing.length === 0) return SETTLED_NOTHING_BILLABLE;
+    return this.collector.send(billing);
+  }
+
+  /**
+   * Lazy, waitUntil-schedulable drain: never rejects. Diagnostic rows (staged + newly drained)
+   * go to the drain transport; failures hit onDiagnosticSendError per the class's loss budget.
+   * Billing rows found here mean settleBillable was skipped — they are still sent awaited (never
+   * silently dropped or left buffered), with failures escalated via onLateBillableSendFailure.
+   */
+  override async flush(): Promise<void> {
+    const { billing, diagnostic } = this.partitionDrained();
+    const diagnosticRows = this.pendingDiagnosticRows.concat(diagnostic);
+    this.pendingDiagnosticRows = [];
+
+    if (billing.length > 0) {
+      const result = await this.collector.send(billing);
+      if (result instanceof Err) {
+        this.onLateBillableSendFailure?.(result.error, billing);
+      }
+    }
+
+    if (diagnosticRows.length > 0) {
+      try {
+        await this.diagnostics.send(diagnosticRows);
+      } catch (error) {
+        this.onDiagnosticSendError?.(error, diagnosticRows);
+      }
+    }
+  }
+}

package/src/lib/cloudflare/collectorClient.ts

@@ -0,0 +1,117 @@
+/**
+ * Billing-grade collector client.
+ *
+ * Per specs/lmao/01u_cloudflare_trace_segments.md §Delivery Classes / §Zero-Loss Sources:
+ * `send(rows)` resolves Ok only when the collector has ACKED — and the ack means the collector
+ * DO's transactional-storage commit completed, which IS the durability point. From that moment
+ * the rows are durable and replay-owned.
+ *
+ * Send-before-response contract: the caller awaits `send` within the request; an Err fails the
+ * billable request (same principle as any payment-gateway outage). Implementations and callers
+ * must NEVER buffer billing-grade rows in the isolate across requests — an isolate eviction
+ * between requests silently destroys revenue records.
+ *
+ * The collector DO itself is not deployed yet; this module ships the interface plus an in-memory
+ * fake with ack/fail/latency injection so lane composition is testable today.
+ */
+
+import { Err, Ok, type Result } from '../result.js';
+import type { TraceRow } from './traceRows.js';
+
+/** Proof of collector durability: the DO transactional-storage commit completed. */
+export interface CollectorAck {
+  readonly durable: true;
+}
+
+/** Singleton ack — the ack carries no data, so never allocate it per send. */
+export const COLLECTOR_ACK: CollectorAck = { durable: true };
+
+/** Operational send failure — the caller must fail the billable request on this. */
+export interface CollectorSendFailure {
+  readonly code: 'collector-unavailable' | 'collector-rejected';
+  readonly message: string;
+}
+
+/**
+ * Transport to the billing-grade collector shard.
+ *
+ * `send` resolves Ok(CollectorAck) only after the collector's DO transactional-storage commit;
+ * operational failures come back as Err (never throw) so the request path can fail deliberately.
+ */
+export interface CollectorClient {
+  send(rows: readonly TraceRow[]): Promise<Result<CollectorAck, CollectorSendFailure>>;
+}
+
+interface HeldSend {
+  readonly rows: readonly TraceRow[];
+  readonly resolve: (result: Result<CollectorAck, CollectorSendFailure>) => void;
+}
+
+/**
+ * In-memory CollectorClient fake with ack/fail/latency injection.
+ *
+ * Modes:
+ * - default: every send acks immediately (after optional injected latency)
+ * - `failNext(failure)`: queue an Err for upcoming sends
+ * - `holdSends()`: sends stay pending until the test calls `ackNext()`/`rejectNext()` — this is
+ *   how contract tests prove "resolves only when the collector acks"
+ */
+export class FakeCollectorClient implements CollectorClient {
+  /** Row batches the fake has durably acked, in ack order. */
+  readonly acked: (readonly TraceRow[])[] = [];
+
+  private readonly failures: CollectorSendFailure[] = [];
+  private readonly held: HeldSend[] = [];
+  private holding = false;
+  private latencyMs = 0;
+
+  /** Queue an Err result for the next send (FIFO across multiple calls). */
+  failNext(failure: CollectorSendFailure): void {
+    this.failures.push(failure);
+  }
+
+  /** Inject artificial ack latency for subsequent sends. */
+  setLatency(ms: number): void {
+    this.latencyMs = ms;
+  }
+
+  /** Switch to manual mode: sends stay pending until ackNext()/rejectNext(). */
+  holdSends(): void {
+    this.holding = true;
+  }
+
+  /** Number of sends currently awaiting a manual ack. */
+  get pendingCount(): number {
+    return this.held.length;
+  }
+
+  /** Ack the oldest held send (DO commit happened). */
+  ackNext(): void {
+    const pending = this.held.shift();
+    if (!pending) throw new Error('FakeCollectorClient.ackNext: no held send');
+    this.acked.push(pending.rows);
+    pending.resolve(new Ok(COLLECTOR_ACK));
+  }
+
+  /** Fail the oldest held send with an operational failure. */
+  rejectNext(failure: CollectorSendFailure): void {
+    const pending = this.held.shift();
+    if (!pending) throw new Error('FakeCollectorClient.rejectNext: no held send');
+    pending.resolve(new Err(failure));
+  }
+
+  async send(rows: readonly TraceRow[]): Promise<Result<CollectorAck, CollectorSendFailure>> {
+    if (this.latencyMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.latencyMs));
+    }
+    if (this.holding) {
+      return new Promise((resolve) => {
+        this.held.push({ rows, resolve });
+      });
+    }
+    const failure = this.failures.shift();
+    if (failure) return new Err(failure);
+    this.acked.push(rows);
+    return new Ok(COLLECTOR_ACK);
+  }
+}