@noego/wood 0.4.6 → 0.4.7

package/dist/tracing/renderer_trace_batch_transport.js

@@ -0,0 +1,292 @@
+import {
+  BoundedMetadataSnapshotter,
+  DEFAULT_METADATA_SNAPSHOT_LIMITS
+} from "@noego/telemetry/core";
+import { WoodTraceBatchContract } from "./wood_trace_batch_contract.js";
+class RendererTraceBatchTransport {
+  constructor(options) {
+    this.options = options;
+    this.contract = new WoodTraceBatchContract();
+    this.queue = [];
+    this.state = "accepting";
+    this.port = null;
+    this.unsubscribePort = null;
+    this.inFlight = null;
+    this.nextSequence = 0;
+    this.drainScheduled = false;
+    this.droppedCapacity = 0;
+    this.droppedClosed = 0;
+    this.droppedRejected = 0;
+    this.droppedRetryExhausted = 0;
+    this.committedBatches = 0;
+    this.retryAttempts = 0;
+    this.metadataTruncatedValues = 0;
+    this.metadataRedactedValues = 0;
+    this.metadataSerializationFailures = 0;
+    this.validateOptions();
+    this.metadataSnapshotter = new BoundedMetadataSnapshotter(
+      options.metadataSnapshotLimits ?? DEFAULT_METADATA_SNAPSHOT_LIMITS
+    );
+  }
+  admit(event) {
+    const sequence = this.nextSequence;
+    this.nextSequence += 1;
+    if (this.state !== "accepting") {
+      this.droppedClosed += 1;
+      return { kind: "dropped", sequence, reason: "closed" };
+    }
+    const retainedEvents = this.queue.length + (this.inFlight?.batch.events.length ?? 0);
+    if (retainedEvents >= this.options.maxQueuedEvents) {
+      this.droppedCapacity += 1;
+      return { kind: "dropped", sequence, reason: "capacity" };
+    }
+    this.queue.push(Object.freeze({ sequence, event: this.snapshotEvent(event, sequence) }));
+    this.scheduleDrain();
+    return { kind: "admitted", sequence };
+  }
+  attachPort(port) {
+    this.detachPort();
+    this.port = port;
+    this.unsubscribePort = port.subscribe((message) => this.handleAcknowledgement(message));
+    if (this.inFlight) {
+      this.inFlight.awaitingAcknowledgement = false;
+      this.inFlight.retryReady = true;
+      this.inFlight.retryGeneration += 1;
+    }
+    this.scheduleDrain();
+  }
+  status() {
+    return Object.freeze({
+      state: this.state,
+      producerId: this.options.producerId,
+      nextSequence: this.nextSequence,
+      queuedEvents: this.queue.length,
+      inFlightBatchId: this.inFlight?.batch.batchId ?? null,
+      droppedCapacity: this.droppedCapacity,
+      droppedClosed: this.droppedClosed,
+      droppedRejected: this.droppedRejected,
+      droppedRetryExhausted: this.droppedRetryExhausted,
+      metadataTruncatedValues: this.metadataTruncatedValues,
+      metadataRedactedValues: this.metadataRedactedValues,
+      metadataSerializationFailures: this.metadataSerializationFailures,
+      committedBatches: this.committedBatches,
+      retryAttempts: this.retryAttempts
+    });
+  }
+  async flush(deadlineMs) {
+    this.scheduleDrain();
+    while (this.hasPendingEvents() && this.options.now() < deadlineMs) {
+      await this.options.delay(1);
+      this.scheduleDrain();
+    }
+  }
+  async close(deadlineMs) {
+    if (this.state === "stopped") {
+      return;
+    }
+    this.state = "draining";
+    await this.flush(deadlineMs);
+    const abandonedEvents = this.queue.length + (this.inFlight?.batch.events.length ?? 0);
+    this.droppedClosed += abandonedEvents;
+    this.queue.length = 0;
+    this.inFlight = null;
+    this.detachPort();
+    this.state = "stopped";
+  }
+  abandonRetryExhausted() {
+    if (!this.inFlight) {
+      return;
+    }
+    this.droppedRetryExhausted += this.inFlight.batch.events.length;
+    this.inFlight = null;
+    this.scheduleDrain();
+  }
+  createInFlightBatch() {
+    if (this.inFlight || this.queue.length === 0 || !this.port) {
+      return;
+    }
+    const entries = this.queue.splice(0, this.options.maxBatchEvents);
+    const first = entries[0];
+    if (!first) {
+      return;
+    }
+    this.inFlight = {
+      batch: this.contract.create(
+        this.options.producerId,
+        first.sequence,
+        entries.map((entry) => entry.event)
+      ),
+      attempts: 0,
+      awaitingAcknowledgement: false,
+      retryReady: true,
+      retryGeneration: 0
+    };
+  }
+  detachPort() {
+    this.unsubscribePort?.();
+    this.unsubscribePort = null;
+    this.port?.close();
+    this.port = null;
+  }
+  drain() {
+    this.createInFlightBatch();
+    this.sendInFlightBatch();
+  }
+  handleAcknowledgement(message) {
+    const parsed = this.contract.parseAcknowledgement(message);
+    if (!parsed.ok || !this.inFlight) {
+      return;
+    }
+    const acknowledgement = parsed.acknowledgement;
+    if (acknowledgement.batchId !== this.inFlight.batch.batchId) {
+      return;
+    }
+    this.inFlight.retryGeneration += 1;
+    this.inFlight.awaitingAcknowledgement = false;
+    if (acknowledgement.kind === "committed") {
+      if (acknowledgement.acceptedEvents !== this.inFlight.batch.events.length) {
+        this.scheduleRetry(0);
+        return;
+      }
+      this.committedBatches += 1;
+      this.inFlight = null;
+      this.scheduleDrain();
+      return;
+    }
+    if (acknowledgement.kind === "rejected") {
+      this.droppedRejected += this.inFlight.batch.events.length;
+      this.inFlight = null;
+      this.scheduleDrain();
+      return;
+    }
+    this.scheduleRetry(acknowledgement.retryAfterMs);
+  }
+  handleAcknowledgementTimeout(batchId, attempt) {
+    if (!this.inFlight || this.inFlight.batch.batchId !== batchId || this.inFlight.attempts !== attempt || !this.inFlight.awaitingAcknowledgement) {
+      return;
+    }
+    this.inFlight.awaitingAcknowledgement = false;
+    this.scheduleRetry(this.retryDelay(attempt));
+  }
+  hasPendingEvents() {
+    return this.queue.length > 0 || this.inFlight !== null;
+  }
+  retryDelay(attempt) {
+    return this.options.retryBaseDelayMs * 2 ** Math.max(0, attempt - 1);
+  }
+  scheduleDrain() {
+    if (this.drainScheduled) {
+      return;
+    }
+    this.drainScheduled = true;
+    this.options.schedule(() => {
+      this.drainScheduled = false;
+      this.drain();
+    });
+  }
+  scheduleRetry(requestedDelayMs) {
+    if (!this.inFlight) {
+      return;
+    }
+    if (this.inFlight.attempts > this.options.retryLimit) {
+      this.abandonRetryExhausted();
+      return;
+    }
+    this.inFlight.retryReady = false;
+    const generation = this.inFlight.retryGeneration + 1;
+    this.inFlight.retryGeneration = generation;
+    const delayMs = Math.max(requestedDelayMs, this.retryDelay(this.inFlight.attempts));
+    void this.options.delay(delayMs).then(() => {
+      if (!this.inFlight || this.inFlight.retryGeneration !== generation) {
+        return;
+      }
+      this.inFlight.retryReady = true;
+      this.scheduleDrain();
+    });
+  }
+  sendInFlightBatch() {
+    const current = this.inFlight;
+    const port = this.port;
+    if (!current || !port || current.awaitingAcknowledgement || !current.retryReady) {
+      return;
+    }
+    if (current.attempts > this.options.retryLimit) {
+      this.abandonRetryExhausted();
+      return;
+    }
+    current.attempts += 1;
+    if (current.attempts > 1) {
+      this.retryAttempts += 1;
+    }
+    current.awaitingAcknowledgement = true;
+    current.retryReady = false;
+    const attempt = current.attempts;
+    try {
+      port.postMessage(current.batch);
+    } catch {
+      current.awaitingAcknowledgement = false;
+      this.detachPort();
+      return;
+    }
+    void this.options.delay(this.options.acknowledgementTimeoutMs).then(() => {
+      this.handleAcknowledgementTimeout(current.batch.batchId, attempt);
+    });
+  }
+  snapshotEvent(event, sequence) {
+    const snapshot = this.metadataSnapshotter.snapshot(event);
+    this.metadataTruncatedValues += snapshot.stats.truncatedValues;
+    this.metadataRedactedValues += snapshot.stats.redactedValues;
+    this.metadataSerializationFailures += snapshot.stats.serializationFailures;
+    const input = snapshot.metadata;
+    const occurredAt = new Date(this.options.now());
+    const timestamp = Number.isNaN(occurredAt.getTime()) ? (/* @__PURE__ */ new Date(0)).toISOString() : occurredAt.toISOString();
+    return Object.freeze({
+      source: this.snapshotString(input.source, "unknown"),
+      type: this.snapshotString(input.type, "unknown"),
+      level: this.snapshotString(input.level, "info"),
+      process: "renderer",
+      timestamp,
+      traceSeq: sequence + 1,
+      ...this.snapshotOptionalString("message", input.message),
+      ...this.snapshotConversationId(input.conversationId),
+      ...this.snapshotPayload(input.payload),
+      ...this.snapshotOptionalString("windowId", input.windowId),
+      ...this.snapshotOptionalNumber("webContentsId", input.webContentsId),
+      ...this.snapshotOptionalString("routeKey", input.routeKey),
+      ...this.snapshotOptionalString("harnessId", input.harnessId)
+    });
+  }
+  snapshotConversationId(value) {
+    return typeof value === "string" || typeof value === "number" ? { conversationId: value } : {};
+  }
+  snapshotOptionalNumber(key, value) {
+    return typeof value === "number" && Number.isFinite(value) ? { [key]: value } : {};
+  }
+  snapshotOptionalString(key, value) {
+    return typeof value === "string" ? { [key]: value } : {};
+  }
+  snapshotPayload(value) {
+    if (value === void 0) {
+      return {};
+    }
+    const payload = this.isJsonObject(value) ? value : Object.freeze({ __telemetry: value });
+    return { payload };
+  }
+  snapshotString(value, fallback) {
+    return typeof value === "string" && value.trim().length > 0 ? value : fallback;
+  }
+  isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  validateOptions() {
+    const validCapacity = Number.isSafeInteger(this.options.maxQueuedEvents) && this.options.maxQueuedEvents > 0 && Number.isSafeInteger(this.options.maxBatchEvents) && this.options.maxBatchEvents > 0 && this.options.maxBatchEvents <= this.options.maxQueuedEvents;
+    const validRetry = Number.isSafeInteger(this.options.retryLimit) && this.options.retryLimit >= 0 && Number.isFinite(this.options.retryBaseDelayMs) && this.options.retryBaseDelayMs >= 0 && Number.isFinite(this.options.acknowledgementTimeoutMs) && this.options.acknowledgementTimeoutMs > 0;
+    if (!this.options.producerId.trim() || !validCapacity || !validRetry) {
+      throw new Error("Renderer trace batch transport options are invalid");
+    }
+  }
+}
+export {
+  RendererTraceBatchTransport
+};
+//# sourceMappingURL=renderer_trace_batch_transport.js.map

package/dist/tracing/renderer_trace_batch_transport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tracing/renderer_trace_batch_transport.ts"],"sourcesContent":["import {\n  BoundedMetadataSnapshotter,\n  DEFAULT_METADATA_SNAPSHOT_LIMITS,\n  type TelemetryJsonObject,\n  type TelemetryJsonValue,\n} from '@noego/telemetry/core';\nimport { WoodTraceBatchContract } from './wood_trace_batch_contract.js';\nimport type {\n  WoodRendererTraceEvent,\n  WoodRendererTraceInput,\n  WoodTraceBatch,\n  WoodTraceBatchAdmissionResult,\n  WoodTraceBatchPort,\n  WoodTraceBatchTransportOptions,\n  WoodTraceBatchTransportStatus,\n} from './types/wood_trace_batch.types.js';\n\ntype QueuedTraceEvent = Readonly<{\n  sequence: number;\n  event: WoodRendererTraceEvent;\n}>;\n\ntype InFlightTraceBatch = {\n  batch: WoodTraceBatch;\n  attempts: number;\n  awaitingAcknowledgement: boolean;\n  retryReady: boolean;\n  retryGeneration: number;\n};\n\nexport class RendererTraceBatchTransport {\n  private readonly contract = new WoodTraceBatchContract();\n  private readonly metadataSnapshotter: BoundedMetadataSnapshotter;\n  private readonly queue: QueuedTraceEvent[] = [];\n  private state: 'accepting' | 'draining' | 'stopped' = 'accepting';\n  private port: WoodTraceBatchPort | null = null;\n  private unsubscribePort: (() => void) | null = null;\n  private inFlight: InFlightTraceBatch | null = null;\n  private nextSequence = 0;\n  private drainScheduled = false;\n  private droppedCapacity = 0;\n  private droppedClosed = 0;\n  private droppedRejected = 0;\n  private droppedRetryExhausted = 0;\n  private committedBatches = 0;\n  private retryAttempts = 0;\n  private metadataTruncatedValues = 0;\n  private metadataRedactedValues = 0;\n  private metadataSerializationFailures = 0;\n\n  constructor(private readonly options: WoodTraceBatchTransportOptions) {\n    this.validateOptions();\n    this.metadataSnapshotter = new BoundedMetadataSnapshotter(\n      options.metadataSnapshotLimits ?? DEFAULT_METADATA_SNAPSHOT_LIMITS,\n    );\n  }\n\n  admit(event: WoodRendererTraceInput): WoodTraceBatchAdmissionResult {\n    const sequence = this.nextSequence;\n    this.nextSequence += 1;\n    if (this.state !== 'accepting') {\n      this.droppedClosed += 1;\n      return { kind: 'dropped', sequence, reason: 'closed' };\n    }\n\n    const retainedEvents = this.queue.length + (this.inFlight?.batch.events.length ?? 0);\n    if (retainedEvents >= this.options.maxQueuedEvents) {\n      this.droppedCapacity += 1;\n      return { kind: 'dropped', sequence, reason: 'capacity' };\n    }\n\n    this.queue.push(Object.freeze({ sequence, event: this.snapshotEvent(event, sequence) }));\n    this.scheduleDrain();\n    return { kind: 'admitted', sequence };\n  }\n\n  attachPort(port: WoodTraceBatchPort): void {\n    this.detachPort();\n    this.port = port;\n    this.unsubscribePort = port.subscribe((message) => this.handleAcknowledgement(message));\n    if (this.inFlight) {\n      this.inFlight.awaitingAcknowledgement = false;\n      this.inFlight.retryReady = true;\n      this.inFlight.retryGeneration += 1;\n    }\n    this.scheduleDrain();\n  }\n\n  status(): WoodTraceBatchTransportStatus {\n    return Object.freeze({\n      state: this.state,\n      producerId: this.options.producerId,\n      nextSequence: this.nextSequence,\n      queuedEvents: this.queue.length,\n      inFlightBatchId: this.inFlight?.batch.batchId ?? null,\n      droppedCapacity: this.droppedCapacity,\n      droppedClosed: this.droppedClosed,\n      droppedRejected: this.droppedRejected,\n      droppedRetryExhausted: this.droppedRetryExhausted,\n      metadataTruncatedValues: this.metadataTruncatedValues,\n      metadataRedactedValues: this.metadataRedactedValues,\n      metadataSerializationFailures: this.metadataSerializationFailures,\n      committedBatches: this.committedBatches,\n      retryAttempts: this.retryAttempts,\n    });\n  }\n\n  async flush(deadlineMs: number): Promise<void> {\n    this.scheduleDrain();\n    while (this.hasPendingEvents() && this.options.now() < deadlineMs) {\n      await this.options.delay(1);\n      this.scheduleDrain();\n    }\n  }\n\n  async close(deadlineMs: number): Promise<void> {\n    if (this.state === 'stopped') {\n      return;\n    }\n    this.state = 'draining';\n    await this.flush(deadlineMs);\n    const abandonedEvents = this.queue.length + (this.inFlight?.batch.events.length ?? 0);\n    this.droppedClosed += abandonedEvents;\n    this.queue.length = 0;\n    this.inFlight = null;\n    this.detachPort();\n    this.state = 'stopped';\n  }\n\n  private abandonRetryExhausted(): void {\n    if (!this.inFlight) {\n      return;\n    }\n    this.droppedRetryExhausted += this.inFlight.batch.events.length;\n    this.inFlight = null;\n    this.scheduleDrain();\n  }\n\n  private createInFlightBatch(): void {\n    if (this.inFlight || this.queue.length === 0 || !this.port) {\n      return;\n    }\n    const entries = this.queue.splice(0, this.options.maxBatchEvents);\n    const first = entries[0];\n    if (!first) {\n      return;\n    }\n    this.inFlight = {\n      batch: this.contract.create(\n        this.options.producerId,\n        first.sequence,\n        entries.map((entry) => entry.event),\n      ),\n      attempts: 0,\n      awaitingAcknowledgement: false,\n      retryReady: true,\n      retryGeneration: 0,\n    };\n  }\n\n  private detachPort(): void {\n    this.unsubscribePort?.();\n    this.unsubscribePort = null;\n    this.port?.close();\n    this.port = null;\n  }\n\n  private drain(): void {\n    this.createInFlightBatch();\n    this.sendInFlightBatch();\n  }\n\n  private handleAcknowledgement(message: unknown): void {\n    const parsed = this.contract.parseAcknowledgement(message);\n    if (!parsed.ok || !this.inFlight) {\n      return;\n    }\n    const acknowledgement = parsed.acknowledgement;\n    if (acknowledgement.batchId !== this.inFlight.batch.batchId) {\n      return;\n    }\n\n    this.inFlight.retryGeneration += 1;\n    this.inFlight.awaitingAcknowledgement = false;\n    if (acknowledgement.kind === 'committed') {\n      if (acknowledgement.acceptedEvents !== this.inFlight.batch.events.length) {\n        this.scheduleRetry(0);\n        return;\n      }\n      this.committedBatches += 1;\n      this.inFlight = null;\n      this.scheduleDrain();\n      return;\n    }\n    if (acknowledgement.kind === 'rejected') {\n      this.droppedRejected += this.inFlight.batch.events.length;\n      this.inFlight = null;\n      this.scheduleDrain();\n      return;\n    }\n    this.scheduleRetry(acknowledgement.retryAfterMs);\n  }\n\n  private handleAcknowledgementTimeout(batchId: string, attempt: number): void {\n    if (!this.inFlight\n      || this.inFlight.batch.batchId !== batchId\n      || this.inFlight.attempts !== attempt\n      || !this.inFlight.awaitingAcknowledgement) {\n      return;\n    }\n    this.inFlight.awaitingAcknowledgement = false;\n    this.scheduleRetry(this.retryDelay(attempt));\n  }\n\n  private hasPendingEvents(): boolean {\n    return this.queue.length > 0 || this.inFlight !== null;\n  }\n\n  private retryDelay(attempt: number): number {\n    return this.options.retryBaseDelayMs * (2 ** Math.max(0, attempt - 1));\n  }\n\n  private scheduleDrain(): void {\n    if (this.drainScheduled) {\n      return;\n    }\n    this.drainScheduled = true;\n    this.options.schedule(() => {\n      this.drainScheduled = false;\n      this.drain();\n    });\n  }\n\n  private scheduleRetry(requestedDelayMs: number): void {\n    if (!this.inFlight) {\n      return;\n    }\n    if (this.inFlight.attempts > this.options.retryLimit) {\n      this.abandonRetryExhausted();\n      return;\n    }\n\n    this.inFlight.retryReady = false;\n    const generation = this.inFlight.retryGeneration + 1;\n    this.inFlight.retryGeneration = generation;\n    const delayMs = Math.max(requestedDelayMs, this.retryDelay(this.inFlight.attempts));\n    void this.options.delay(delayMs).then(() => {\n      if (!this.inFlight || this.inFlight.retryGeneration !== generation) {\n        return;\n      }\n      this.inFlight.retryReady = true;\n      this.scheduleDrain();\n    });\n  }\n\n  private sendInFlightBatch(): void {\n    const current = this.inFlight;\n    const port = this.port;\n    if (!current || !port || current.awaitingAcknowledgement || !current.retryReady) {\n      return;\n    }\n    if (current.attempts > this.options.retryLimit) {\n      this.abandonRetryExhausted();\n      return;\n    }\n\n    current.attempts += 1;\n    if (current.attempts > 1) {\n      this.retryAttempts += 1;\n    }\n    current.awaitingAcknowledgement = true;\n    current.retryReady = false;\n    const attempt = current.attempts;\n    try {\n      port.postMessage(current.batch);\n    } catch {\n      current.awaitingAcknowledgement = false;\n      this.detachPort();\n      return;\n    }\n\n    void this.options.delay(this.options.acknowledgementTimeoutMs).then(() => {\n      this.handleAcknowledgementTimeout(current.batch.batchId, attempt);\n    });\n  }\n\n  private snapshotEvent(\n    event: WoodRendererTraceInput,\n    sequence: number,\n  ): WoodRendererTraceEvent {\n    const snapshot = this.metadataSnapshotter.snapshot(event);\n    this.metadataTruncatedValues += snapshot.stats.truncatedValues;\n    this.metadataRedactedValues += snapshot.stats.redactedValues;\n    this.metadataSerializationFailures += snapshot.stats.serializationFailures;\n    const input = snapshot.metadata;\n    const occurredAt = new Date(this.options.now());\n    const timestamp = Number.isNaN(occurredAt.getTime())\n      ? new Date(0).toISOString()\n      : occurredAt.toISOString();\n    return Object.freeze({\n      source: this.snapshotString(input.source, 'unknown'),\n      type: this.snapshotString(input.type, 'unknown'),\n      level: this.snapshotString(input.level, 'info'),\n      process: 'renderer',\n      timestamp,\n      traceSeq: sequence + 1,\n      ...this.snapshotOptionalString('message', input.message),\n      ...this.snapshotConversationId(input.conversationId),\n      ...this.snapshotPayload(input.payload),\n      ...this.snapshotOptionalString('windowId', input.windowId),\n      ...this.snapshotOptionalNumber('webContentsId', input.webContentsId),\n      ...this.snapshotOptionalString('routeKey', input.routeKey),\n      ...this.snapshotOptionalString('harnessId', input.harnessId),\n    });\n  }\n\n  private snapshotConversationId(\n    value: TelemetryJsonValue | undefined,\n  ): Pick<WoodRendererTraceEvent, 'conversationId'> | Record<string, never> {\n    return typeof value === 'string' || typeof value === 'number'\n      ? { conversationId: value }\n      : {};\n  }\n\n  private snapshotOptionalNumber<Key extends 'webContentsId'>(\n    key: Key,\n    value: TelemetryJsonValue | undefined,\n  ): Partial<Pick<WoodRendererTraceEvent, Key>> {\n    return typeof value === 'number' && Number.isFinite(value)\n      ? { [key]: value } as Pick<WoodRendererTraceEvent, Key>\n      : {};\n  }\n\n  private snapshotOptionalString<Key extends 'message' | 'windowId' | 'routeKey' | 'harnessId'>(\n    key: Key,\n    value: TelemetryJsonValue | undefined,\n  ): Partial<Pick<WoodRendererTraceEvent, Key>> {\n    return typeof value === 'string'\n      ? { [key]: value } as Pick<WoodRendererTraceEvent, Key>\n      : {};\n  }\n\n  private snapshotPayload(\n    value: TelemetryJsonValue | undefined,\n  ): Pick<WoodRendererTraceEvent, 'payload'> | Record<string, never> {\n    if (value === undefined) {\n      return {};\n    }\n    const payload: TelemetryJsonObject = this.isJsonObject(value)\n      ? value\n      : Object.freeze({ __telemetry: value });\n    return { payload };\n  }\n\n  private snapshotString(value: TelemetryJsonValue | undefined, fallback: string): string {\n    return typeof value === 'string' && value.trim().length > 0 ? value : fallback;\n  }\n\n  private isJsonObject(value: TelemetryJsonValue): value is TelemetryJsonObject {\n    return typeof value === 'object' && value !== null && !Array.isArray(value);\n  }\n\n  private validateOptions(): void {\n    const validCapacity = Number.isSafeInteger(this.options.maxQueuedEvents)\n      && this.options.maxQueuedEvents > 0\n      && Number.isSafeInteger(this.options.maxBatchEvents)\n      && this.options.maxBatchEvents > 0\n      && this.options.maxBatchEvents <= this.options.maxQueuedEvents;\n    const validRetry = Number.isSafeInteger(this.options.retryLimit)\n      && this.options.retryLimit >= 0\n      && Number.isFinite(this.options.retryBaseDelayMs)\n      && this.options.retryBaseDelayMs >= 0\n      && Number.isFinite(this.options.acknowledgementTimeoutMs)\n      && this.options.acknowledgementTimeoutMs > 0;\n    if (!this.options.producerId.trim() || !validCapacity || !validRetry) {\n      throw new Error('Renderer trace batch transport options are invalid');\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/tracing/trace_commit_writer.cjs

@@ -0,0 +1,159 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var trace_commit_writer_exports = {};
+__export(trace_commit_writer_exports, {
+  TraceCommitWriter: () => TraceCommitWriter
+});
+module.exports = __toCommonJS(trace_commit_writer_exports);
+class TraceCommitWriter {
+  constructor(port, options = {}) {
+    this.seen = /* @__PURE__ */ new Set();
+    this.inflight = [];
+    this.nextCommitSeq = 1;
+    this.committed = 0;
+    this.pendingError = null;
+    this.rendererFlush = null;
+    /** WoodTraceEventSink shape — register via `tracer.registerSink(writer.sink)`. */
+    this.sink = (event) => {
+      this.admit(event);
+    };
+    this.port = port;
+    this.mainProducerId = options.mainProducerId ?? "main";
+  }
+  /**
+   * Admit one trace event. Returns the committed row (with its assigned
+   * `commitSeq`), or `null` if it is a duplicate of an already-admitted
+   * (producerId, producerSeq) pair — this is the batch-retry idempotency guard.
+   */
+  admit(event) {
+    const producerId = this.resolveProducerId(event);
+    const producerSeq = event.traceSeq;
+    const identity = `${producerId}#${producerSeq}`;
+    if (this.seen.has(identity)) {
+      return null;
+    }
+    this.seen.add(identity);
+    const row = this.toRow(event, producerId, producerSeq);
+    this.enqueue(row);
+    return row;
+  }
+  highWaterMark() {
+    return this.committed;
+  }
+  /**
+   * Install the renderer-flush hook (Phase 4 browser mode). The browser harness
+   * supplies a function that drains the page's in-flight renderer `__trace`
+   * round-trips; `flush()` awaits it before the main-writer barrier so
+   * renderer-origin traces are persisted deterministically. Backend mode leaves
+   * this unset and `requestRendererFlush` resolves immediately.
+   */
+  setRendererFlush(fn) {
+    this.rendererFlush = fn;
+  }
+  /**
+   * Request that renderer producers flush their pending batches and await acks.
+   * In browser mode the installed hook (see {@link setRendererFlush}) round-trips
+   * the page to drain pending `__trace` deliveries. With no hook (backend mode,
+   * no renderer) this resolves immediately.
+   */
+  async requestRendererFlush() {
+    if (this.rendererFlush) {
+      await this.rendererFlush();
+    }
+  }
+  /**
+   * Drain the write queue and return the committed high-water mark. Awaits a
+   * barrier over all in-flight persists; with `timeoutMs` it rejects on a
+   * timer race rather than polling. Rejects if any persist failed.
+   */
+  async flush(options = {}) {
+    await this.requestRendererFlush();
+    const barrier = Promise.allSettled(this.inflight.slice());
+    await this.awaitBarrier(barrier, options.timeoutMs);
+    if (this.pendingError !== null) {
+      const error = this.pendingError;
+      this.pendingError = null;
+      throw error;
+    }
+    return { committedHighWaterMark: this.committed };
+  }
+  async awaitBarrier(barrier, timeoutMs) {
+    if (timeoutMs === void 0) {
+      await barrier;
+      return;
+    }
+    let timer = null;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`trace flush barrier exceeded ${timeoutMs}ms`)),
+        timeoutMs
+      );
+    });
+    try {
+      await Promise.race([barrier.then(() => void 0), timeout]);
+    } finally {
+      if (timer !== null) {
+        clearTimeout(timer);
+      }
+    }
+  }
+  enqueue(row) {
+    const op = Promise.resolve().then(() => this.port.persist(row)).then(
+      () => {
+        if (row.commitSeq > this.committed) {
+          this.committed = row.commitSeq;
+        }
+      },
+      (error) => {
+        this.pendingError = error;
+      }
+    );
+    this.inflight.push(op);
+  }
+  resolveProducerId(event) {
+    if (event.process === "renderer") {
+      const rendererId = event.payload?.woodRendererProducerId;
+      return typeof rendererId === "string" ? rendererId : "renderer";
+    }
+    if (event.process === "main") {
+      return this.mainProducerId;
+    }
+    return event.process;
+  }
+  toRow(event, producerId, producerSeq) {
+    return {
+      commitSeq: this.nextCommitSeq++,
+      producerId,
+      producerSeq,
+      process: event.process,
+      level: event.level,
+      type: event.type,
+      source: event.source,
+      ...event.message !== void 0 ? { message: event.message } : {},
+      ...event.conversationId !== void 0 ? { conversationId: event.conversationId } : {},
+      timestamp: event.timestamp,
+      ...event.payload ? { payload: { ...event.payload } } : {}
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TraceCommitWriter
+});
+//# sourceMappingURL=trace_commit_writer.cjs.map

package/dist/tracing/trace_commit_writer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tracing/trace_commit_writer.ts"],"sourcesContent":["import type { TraceLevel, TraceProcess } from './trace_hub.js';\nimport type { WoodTraceEventSnapshot } from './types/wood_trace_sink.types.js';\n\n/**\n * A committed trace row. Ordering is authoritative on `commitSeq` — the\n * writer-assigned monotonic sequence stamped at the single ingestion/commit\n * boundary. `producerId` + `producerSeq` identify the producer-side stream;\n * `timestamp` is retained for display but is NEVER used for cross-producer\n * ordering (clocks across main/renderer are not causal).\n */\nexport interface TraceCommitRow {\n  readonly commitSeq: number;\n  readonly producerId: string;\n  readonly producerSeq: number;\n  readonly process: TraceProcess;\n  readonly level: TraceLevel;\n  readonly type: string;\n  readonly source: string;\n  readonly message?: string;\n  readonly conversationId?: number | string;\n  readonly timestamp: string;\n  readonly payload?: Record<string, unknown>;\n}\n\n/**\n * Storage boundary for committed trace rows. Implemented per-runtime: the app's\n * test backend harness supplies a SQLite-backed adapter (better-sqlite3, which\n * wood does not depend on). `persist` may be sync or async; the writer barrier\n * awaits whatever it returns.\n */\nexport interface WoodTracePersistencePort {\n  persist(row: TraceCommitRow): void | Promise<void>;\n  close?(): void | Promise<void>;\n}\n\nexport interface TraceFlushOptions {\n  timeoutMs?: number;\n}\n\nexport interface TraceFlushResult {\n  /** Highest `commitSeq` durably persisted at flush completion. */\n  readonly committedHighWaterMark: number;\n}\n\nexport interface TraceCommitWriterOptions {\n  /** Stable id for the main-process producer stream (default `'main'`). */\n  readonly mainProducerId?: string;\n}\n\n/**\n * The single trace ingestion/commit boundary. Every trace event (main or, in\n * later phases, renderer batches) is admitted here, assigned a monotonic\n * `commitSeq`, and enqueued for persistence. `flush` drains the async write\n * queue and returns the committed high-water mark — no sleeps, no polling.\n */\nexport class TraceCommitWriter {\n  private readonly port: WoodTracePersistencePort;\n  private readonly mainProducerId: string;\n  private readonly seen = new Set<string>();\n  private inflight: Promise<void>[] = [];\n  private nextCommitSeq = 1;\n  private committed = 0;\n  private pendingError: unknown = null;\n  private rendererFlush: (() => Promise<void>) | null = null;\n\n  constructor(port: WoodTracePersistencePort, options: TraceCommitWriterOptions = {}) {\n    this.port = port;\n    this.mainProducerId = options.mainProducerId ?? 'main';\n  }\n\n  /**\n   * Admit one trace event. Returns the committed row (with its assigned\n   * `commitSeq`), or `null` if it is a duplicate of an already-admitted\n   * (producerId, producerSeq) pair — this is the batch-retry idempotency guard.\n   */\n  admit(event: WoodTraceEventSnapshot): TraceCommitRow | null {\n    const producerId = this.resolveProducerId(event);\n    const producerSeq = event.traceSeq;\n    const identity = `${producerId}#${producerSeq}`;\n    if (this.seen.has(identity)) {\n      return null;\n    }\n    this.seen.add(identity);\n    const row = this.toRow(event, producerId, producerSeq);\n    this.enqueue(row);\n    return row;\n  }\n\n  /** WoodTraceEventSink shape — register via `tracer.registerSink(writer.sink)`. */\n  readonly sink = (event: WoodTraceEventSnapshot): void => {\n    this.admit(event);\n  };\n\n  highWaterMark(): number {\n    return this.committed;\n  }\n\n  /**\n   * Install the renderer-flush hook (Phase 4 browser mode). The browser harness\n   * supplies a function that drains the page's in-flight renderer `__trace`\n   * round-trips; `flush()` awaits it before the main-writer barrier so\n   * renderer-origin traces are persisted deterministically. Backend mode leaves\n   * this unset and `requestRendererFlush` resolves immediately.\n   */\n  setRendererFlush(fn: (() => Promise<void>) | null): void {\n    this.rendererFlush = fn;\n  }\n\n  /**\n   * Request that renderer producers flush their pending batches and await acks.\n   * In browser mode the installed hook (see {@link setRendererFlush}) round-trips\n   * the page to drain pending `__trace` deliveries. With no hook (backend mode,\n   * no renderer) this resolves immediately.\n   */\n  async requestRendererFlush(): Promise<void> {\n    if (this.rendererFlush) {\n      await this.rendererFlush();\n    }\n  }\n\n  /**\n   * Drain the write queue and return the committed high-water mark. Awaits a\n   * barrier over all in-flight persists; with `timeoutMs` it rejects on a\n   * timer race rather than polling. Rejects if any persist failed.\n   */\n  async flush(options: TraceFlushOptions = {}): Promise<TraceFlushResult> {\n    await this.requestRendererFlush();\n    const barrier = Promise.allSettled(this.inflight.slice());\n    await this.awaitBarrier(barrier, options.timeoutMs);\n    if (this.pendingError !== null) {\n      const error = this.pendingError;\n      this.pendingError = null;\n      throw error;\n    }\n    return { committedHighWaterMark: this.committed };\n  }\n\n  private async awaitBarrier(\n    barrier: Promise<unknown>,\n    timeoutMs: number | undefined,\n  ): Promise<void> {\n    if (timeoutMs === undefined) {\n      await barrier;\n      return;\n    }\n    let timer: ReturnType<typeof setTimeout> | null = null;\n    const timeout = new Promise<never>((_, reject) => {\n      timer = setTimeout(\n        () => reject(new Error(`trace flush barrier exceeded ${timeoutMs}ms`)),\n        timeoutMs,\n      );\n    });\n    try {\n      await Promise.race([barrier.then(() => undefined), timeout]);\n    } finally {\n      if (timer !== null) {\n        clearTimeout(timer);\n      }\n    }\n  }\n\n  private enqueue(row: TraceCommitRow): void {\n    const op = Promise.resolve()\n      .then(() => this.port.persist(row))\n      .then(\n        () => {\n          if (row.commitSeq > this.committed) {\n            this.committed = row.commitSeq;\n          }\n        },\n        (error: unknown) => {\n          this.pendingError = error;\n        },\n      );\n    this.inflight.push(op);\n  }\n\n  private resolveProducerId(event: WoodTraceEventSnapshot): string {\n    if (event.process === 'renderer') {\n      const rendererId = event.payload?.woodRendererProducerId;\n      return typeof rendererId === 'string' ? rendererId : 'renderer';\n    }\n    if (event.process === 'main') {\n      return this.mainProducerId;\n    }\n    return event.process;\n  }\n\n  private toRow(\n    event: WoodTraceEventSnapshot,\n    producerId: string,\n    producerSeq: number,\n  ): TraceCommitRow {\n    return {\n      commitSeq: this.nextCommitSeq++,\n      producerId,\n      producerSeq,\n      process: event.process,\n      level: event.level,\n      type: event.type,\n      source: event.source,\n      ...(event.message !== undefined ? { message: event.message } : {}),\n      ...(event.conversationId !== undefined ? { conversationId: event.conversationId } : {}),\n      timestamp: event.timestamp,\n      ...(event.payload ? { payload: { ...event.payload } } : {}),\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuDO,MAAM,kBAAkB;AAAA,EAU7B,YAAY,MAAgC,UAAoC,CAAC,GAAG;AAPpF,SAAiB,OAAO,oBAAI,IAAY;AACxC,SAAQ,WAA4B,CAAC;AACrC,SAAQ,gBAAgB;AACxB,SAAQ,YAAY;AACpB,SAAQ,eAAwB;AAChC,SAAQ,gBAA8C;AA0BtD;AAAA,SAAS,OAAO,CAAC,UAAwC;AACvD,WAAK,MAAM,KAAK;AAAA,IAClB;AAzBE,SAAK,OAAO;AACZ,SAAK,iBAAiB,QAAQ,kBAAkB;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,OAAsD;AAC1D,UAAM,aAAa,KAAK,kBAAkB,KAAK;AAC/C,UAAM,cAAc,MAAM;AAC1B,UAAM,WAAW,GAAG,UAAU,IAAI,WAAW;AAC7C,QAAI,KAAK,KAAK,IAAI,QAAQ,GAAG;AAC3B,aAAO;AAAA,IACT;AACA,SAAK,KAAK,IAAI,QAAQ;AACtB,UAAM,MAAM,KAAK,MAAM,OAAO,YAAY,WAAW;AACrD,SAAK,QAAQ,GAAG;AAChB,WAAO;AAAA,EACT;AAAA,EAOA,gBAAwB;AACtB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,iBAAiB,IAAwC;AACvD,SAAK,gBAAgB;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,uBAAsC;AAC1C,QAAI,KAAK,eAAe;AACtB,YAAM,KAAK,cAAc;AAAA,IAC3B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,MAAM,UAA6B,CAAC,GAA8B;AACtE,UAAM,KAAK,qBAAqB;AAChC,UAAM,UAAU,QAAQ,WAAW,KAAK,SAAS,MAAM,CAAC;AACxD,UAAM,KAAK,aAAa,SAAS,QAAQ,SAAS;AAClD,QAAI,KAAK,iBAAiB,MAAM;AAC9B,YAAM,QAAQ,KAAK;AACnB,WAAK,eAAe;AACpB,YAAM;AAAA,IACR;AACA,WAAO,EAAE,wBAAwB,KAAK,UAAU;AAAA,EAClD;AAAA,EAEA,MAAc,aACZ,SACA,WACe;AACf,QAAI,cAAc,QAAW;AAC3B,YAAM;AACN;AAAA,IACF;AACA,QAAI,QAA8C;AAClD,UAAM,UAAU,IAAI,QAAe,CAAC,GAAG,WAAW;AAChD,cAAQ;AAAA,QACN,MAAM,OAAO,IAAI,MAAM,gCAAgC,SAAS,IAAI,CAAC;AAAA,QACrE;AAAA,MACF;AAAA,IACF,CAAC;AACD,QAAI;AACF,YAAM,QAAQ,KAAK,CAAC,QAAQ,KAAK,MAAM,MAAS,GAAG,OAAO,CAAC;AAAA,IAC7D,UAAE;AACA,UAAI,UAAU,MAAM;AAClB,qBAAa,KAAK;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AAAA,EAEQ,QAAQ,KAA2B;AACzC,UAAM,KAAK,QAAQ,QAAQ,EACxB,KAAK,MAAM,KAAK,KAAK,QAAQ,GAAG,CAAC,EACjC;AAAA,MACC,MAAM;AACJ,YAAI,IAAI,YAAY,KAAK,WAAW;AAClC,eAAK,YAAY,IAAI;AAAA,QACvB;AAAA,MACF;AAAA,MACA,CAAC,UAAmB;AAClB,aAAK,eAAe;AAAA,MACtB;AAAA,IACF;AACF,SAAK,SAAS,KAAK,EAAE;AAAA,EACvB;AAAA,EAEQ,kBAAkB,OAAuC;AAC/D,QAAI,MAAM,YAAY,YAAY;AAChC,YAAM,aAAa,MAAM,SAAS;AAClC,aAAO,OAAO,eAAe,WAAW,aAAa;AAAA,IACvD;AACA,QAAI,MAAM,YAAY,QAAQ;AAC5B,aAAO,KAAK;AAAA,IACd;AACA,WAAO,MAAM;AAAA,EACf;AAAA,EAEQ,MACN,OACA,YACA,aACgB;AAChB,WAAO;AAAA,MACL,WAAW,KAAK;AAAA,MAChB;AAAA,MACA;AAAA,MACA,SAAS,MAAM;AAAA,MACf,OAAO,MAAM;AAAA,MACb,MAAM,MAAM;AAAA,MACZ,QAAQ,MAAM;AAAA,MACd,GAAI,MAAM,YAAY,SAAY,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,MAChE,GAAI,MAAM,mBAAmB,SAAY,EAAE,gBAAgB,MAAM,eAAe,IAAI,CAAC;AAAA,MACrF,WAAW,MAAM;AAAA,MACjB,GAAI,MAAM,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,QAAQ,EAAE,IAAI,CAAC;AAAA,IAC3D;AAAA,EACF;AACF;","names":[]}

package/dist/tracing/trace_commit_writer.d.cts

@@ -0,0 +1,97 @@
+import { d as TraceProcess, c as TraceLevel, g as WoodTraceEventSnapshot } from '../trace_hub-Cob54qRx.cjs';
+import 'rxjs';
+
+/**
+ * A committed trace row. Ordering is authoritative on `commitSeq` — the
+ * writer-assigned monotonic sequence stamped at the single ingestion/commit
+ * boundary. `producerId` + `producerSeq` identify the producer-side stream;
+ * `timestamp` is retained for display but is NEVER used for cross-producer
+ * ordering (clocks across main/renderer are not causal).
+ */
+interface TraceCommitRow {
+    readonly commitSeq: number;
+    readonly producerId: string;
+    readonly producerSeq: number;
+    readonly process: TraceProcess;
+    readonly level: TraceLevel;
+    readonly type: string;
+    readonly source: string;
+    readonly message?: string;
+    readonly conversationId?: number | string;
+    readonly timestamp: string;
+    readonly payload?: Record<string, unknown>;
+}
+/**
+ * Storage boundary for committed trace rows. Implemented per-runtime: the app's
+ * test backend harness supplies a SQLite-backed adapter (better-sqlite3, which
+ * wood does not depend on). `persist` may be sync or async; the writer barrier
+ * awaits whatever it returns.
+ */
+interface WoodTracePersistencePort {
+    persist(row: TraceCommitRow): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+interface TraceFlushOptions {
+    timeoutMs?: number;
+}
+interface TraceFlushResult {
+    /** Highest `commitSeq` durably persisted at flush completion. */
+    readonly committedHighWaterMark: number;
+}
+interface TraceCommitWriterOptions {
+    /** Stable id for the main-process producer stream (default `'main'`). */
+    readonly mainProducerId?: string;
+}
+/**
+ * The single trace ingestion/commit boundary. Every trace event (main or, in
+ * later phases, renderer batches) is admitted here, assigned a monotonic
+ * `commitSeq`, and enqueued for persistence. `flush` drains the async write
+ * queue and returns the committed high-water mark — no sleeps, no polling.
+ */
+declare class TraceCommitWriter {
+    private readonly port;
+    private readonly mainProducerId;
+    private readonly seen;
+    private inflight;
+    private nextCommitSeq;
+    private committed;
+    private pendingError;
+    private rendererFlush;
+    constructor(port: WoodTracePersistencePort, options?: TraceCommitWriterOptions);
+    /**
+     * Admit one trace event. Returns the committed row (with its assigned
+     * `commitSeq`), or `null` if it is a duplicate of an already-admitted
+     * (producerId, producerSeq) pair — this is the batch-retry idempotency guard.
+     */
+    admit(event: WoodTraceEventSnapshot): TraceCommitRow | null;
+    /** WoodTraceEventSink shape — register via `tracer.registerSink(writer.sink)`. */
+    readonly sink: (event: WoodTraceEventSnapshot) => void;
+    highWaterMark(): number;
+    /**
+     * Install the renderer-flush hook (Phase 4 browser mode). The browser harness
+     * supplies a function that drains the page's in-flight renderer `__trace`
+     * round-trips; `flush()` awaits it before the main-writer barrier so
+     * renderer-origin traces are persisted deterministically. Backend mode leaves
+     * this unset and `requestRendererFlush` resolves immediately.
+     */
+    setRendererFlush(fn: (() => Promise<void>) | null): void;
+    /**
+     * Request that renderer producers flush their pending batches and await acks.
+     * In browser mode the installed hook (see {@link setRendererFlush}) round-trips
+     * the page to drain pending `__trace` deliveries. With no hook (backend mode,
+     * no renderer) this resolves immediately.
+     */
+    requestRendererFlush(): Promise<void>;
+    /**
+     * Drain the write queue and return the committed high-water mark. Awaits a
+     * barrier over all in-flight persists; with `timeoutMs` it rejects on a
+     * timer race rather than polling. Rejects if any persist failed.
+     */
+    flush(options?: TraceFlushOptions): Promise<TraceFlushResult>;
+    private awaitBarrier;
+    private enqueue;
+    private resolveProducerId;
+    private toRow;
+}
+
+export { type TraceCommitRow, TraceCommitWriter, type TraceCommitWriterOptions, type TraceFlushOptions, type TraceFlushResult, type WoodTracePersistencePort };