deepline 0.1.300 → 0.1.301

package/dist/bundling-sources/sdk/src/release.ts

@@ -155,7 +155,7 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.300',
+  version: '0.1.301',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-store-adapter.ts

@@ -124,6 +124,7 @@ export class RuntimeReceiptStoreAdapter {
     maxBatchBytes?: number;
     maxFlushMs?: number;
     maxBufferedBytes?: number;
+    onRetryTelemetry?: (line: string) => void;
   }) {
     const context: WorkerRuntimeApiContext = {
       ...options.context,
@@ -137,6 +138,14 @@ export class RuntimeReceiptStoreAdapter {
       maxFlushMs: options.maxFlushMs,
       maxBufferedBytes: options.maxBufferedBytes,
       classifyRetryableError: classifyReceiptRetry,
+      onRetryEvent: (event) =>
+        emitReceiptWriterRetryTelemetry({
+          event,
+          playName: options.playName,
+          runId: options.runId,
+          gatewayHost: runtimeGatewayHost(context.baseUrl),
+          onTelemetry: options.onRetryTelemetry,
+        }),
       send: async (commands, { signal }) =>
         await sendReceiptCommands({
           context: { ...context, signal },
@@ -260,6 +269,100 @@ export class RuntimeReceiptStoreAdapter {
   }
 }
 
+const RECEIPT_WRITER_RETRY_TELEMETRY_TAG =
+  '[perf][worker.receipt_writer.retry]';
+
+function isPowerOfTwo(value: number): boolean {
+  return value > 0 && (value & (value - 1)) === 0;
+}
+
+function runtimeGatewayHost(baseUrl: string): string | null {
+  try {
+    return new URL(baseUrl).host || null;
+  } catch {
+    return null;
+  }
+}
+
+function receiptCommandTelemetryAction(command: ReceiptCommand): string {
+  return command.kind === 'settle'
+    ? `${command.kind}_${command.outcome}`
+    : command.kind;
+}
+
+function receiptRetryErrorTelemetry(error: unknown): Record<string, unknown> {
+  if (isAppRuntimeApiCapacityError(error)) {
+    return {
+      failureKind: 'capacity',
+      errorName: error.name,
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+    };
+  }
+  if (error instanceof AppRuntimeApiTransportError) {
+    return {
+      failureKind: 'transport',
+      errorName: error.name,
+      transportAttempts: error.attempts,
+      transportAction: error.action,
+    };
+  }
+  if (error instanceof AppRuntimeApiResponseError) {
+    return {
+      failureKind: 'http',
+      errorName: error.name,
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+    };
+  }
+  return {
+    failureKind: 'unknown',
+    errorName: error instanceof Error ? error.name : typeof error,
+  };
+}
+
+function emitReceiptWriterRetryTelemetry(input: {
+  event: import('./runtime-receipt-writer').RuntimeReceiptWriterRetryEvent<ReceiptCommand>;
+  playName: string;
+  runId: string;
+  gatewayHost: string | null;
+  onTelemetry?: (line: string) => void;
+}): void {
+  const { event } = input;
+  if (event.phase === 'retry' && !isPowerOfTwo(event.attempt)) return;
+  const payload = {
+    phase: event.phase,
+    playName: input.playName,
+    runId: input.runId,
+    gatewayHost: input.gatewayHost,
+    action: receiptCommandTelemetryAction(event.firstInput),
+    batchId: event.batchId,
+    batchSize: event.batchSize,
+    attempt: event.attempt,
+    elapsedMs: event.elapsedMs,
+    retryAfterMs: event.retryAfterMs,
+    queued: event.queued,
+    blocked: event.blocked,
+    bufferedBytes: event.bufferedBytes,
+    ...(event.error === undefined
+      ? { failureKind: null }
+      : receiptRetryErrorTelemetry(event.error)),
+  };
+  try {
+    const serialized = JSON.stringify(payload);
+    input.onTelemetry?.(`${RECEIPT_WRITER_RETRY_TELEMETRY_TAG} ${serialized}`);
+    if (event.phase === 'retry') {
+      console.warn(RECEIPT_WRITER_RETRY_TELEMETRY_TAG, serialized);
+    } else {
+      console.info(RECEIPT_WRITER_RETRY_TELEMETRY_TAG, serialized);
+    }
+  } catch {
+    // Receipt telemetry must never affect durable delivery.
+  }
+}
+
 function receiptCommandBatchKey(command: ReceiptCommand): string {
   switch (command.kind) {
     case 'get':

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-writer.ts

@@ -22,6 +22,20 @@ export type RuntimeReceiptWriterStats = {
   bufferedBytes: number;
 };
 
+export type RuntimeReceiptWriterRetryEvent<Input> = {
+  phase: 'retry' | 'recovered';
+  attempt: number;
+  batchId: number;
+  batchSize: number;
+  firstInput: Input;
+  elapsedMs: number;
+  retryAfterMs: number;
+  queued: number;
+  blocked: number;
+  bufferedBytes: number;
+  error?: unknown;
+};
+
 export class RuntimeReceiptWriterBufferLimitError extends Error {
   constructor(
     readonly inputBytes: number,
@@ -76,11 +90,15 @@ export class RuntimeReceiptWriter<Input, Output> {
   readonly #maxBatchBytes: number;
   readonly #maxBufferedBytes: number;
   readonly #maxFlushMs: number;
+  readonly #onRetryEvent:
+    | ((event: RuntimeReceiptWriterRetryEvent<Input>) => void)
+    | null;
   readonly #queued: Array<PendingWrite<Input, Output>> = [];
   readonly #blocked: Array<PendingWrite<Input, Output>> = [];
   readonly #closeController = new AbortController();
 
   #bufferedBytes = 0;
+  #nextBatchId = 0;
   #activeBatch: Array<PendingWrite<Input, Output>> | null = null;
   #pump: Promise<void> | null = null;
   #flushTimer: ReturnType<typeof setTimeout> | null = null;
@@ -103,6 +121,7 @@ export class RuntimeReceiptWriter<Input, Output> {
     maxBatchBytes?: number;
     maxBufferedBytes?: number;
     maxFlushMs?: number;
+    onRetryEvent?: (event: RuntimeReceiptWriterRetryEvent<Input>) => void;
   }) {
     this.#batchKey = options.batchKey;
     this.#send = options.send;
@@ -119,6 +138,7 @@ export class RuntimeReceiptWriter<Input, Output> {
       this.#maxBufferedBytes,
     );
     this.#maxFlushMs = Math.max(0, Math.floor(options.maxFlushMs ?? 5));
+    this.#onRetryEvent = options.onRetryEvent ?? null;
   }
 
   write(input: Input, options: { signal?: AbortSignal } = {}): Promise<Output> {
@@ -243,9 +263,10 @@ export class RuntimeReceiptWriter<Input, Output> {
     while (this.#queued.length > 0) {
       const batch = this.#takeBatch();
       if (batch.length === 0) continue;
+      const batchId = ++this.#nextBatchId;
       this.#activeBatch = batch;
       try {
-        const outputs = await this.#sendWithRetry(batch);
+        const outputs = await this.#sendWithRetry(batch, batchId);
         if (outputs.length !== batch.length) {
           throw new RuntimeReceiptWriterResultCountError(
             batch.length,
@@ -305,9 +326,13 @@ export class RuntimeReceiptWriter<Input, Output> {
 
   async #sendWithRetry(
     batch: readonly PendingWrite<Input, Output>[],
+    batchId: number,
   ): Promise<readonly Output[]> {
     const inputs = batch.map((pending) => pending.input);
+    const startedAt = Date.now();
+    let attempt = 0;
     while (true) {
+      attempt += 1;
       if (this.#closeController.signal.aborted) {
         throw this.#closeReason;
       }
@@ -315,20 +340,68 @@ export class RuntimeReceiptWriter<Input, Output> {
         throw batch[0]?.aborted;
       }
       try {
-        return await this.#send(inputs, {
+        const outputs = await this.#send(inputs, {
           signal: this.#closeController.signal,
         });
+        if (attempt > 1) {
+          this.#emitRetryEvent({
+            phase: 'recovered',
+            attempt,
+            batchId,
+            batch,
+            startedAt,
+            retryAfterMs: 0,
+          });
+        }
+        return outputs;
       } catch (error) {
         const retry = this.#classifyRetryableError(error);
         if (!retry) throw error;
-        await this.#waitForRetry(
-          jitteredRetryDelayMs(retry.retryAfterMs),
+        const retryAfterMs = jitteredRetryDelayMs(retry.retryAfterMs);
+        this.#emitRetryEvent({
+          phase: 'retry',
+          attempt,
+          batchId,
           batch,
-        );
+          startedAt,
+          retryAfterMs,
+          error,
+        });
+        await this.#waitForRetry(retryAfterMs, batch);
       }
     }
   }
 
+  #emitRetryEvent(input: {
+    phase: 'retry' | 'recovered';
+    attempt: number;
+    batchId: number;
+    batch: readonly PendingWrite<Input, Output>[];
+    startedAt: number;
+    retryAfterMs: number;
+    error?: unknown;
+  }): void {
+    const firstInput = input.batch[0]?.input;
+    if (!this.#onRetryEvent || firstInput === undefined) return;
+    try {
+      this.#onRetryEvent({
+        phase: input.phase,
+        attempt: input.attempt,
+        batchId: input.batchId,
+        batchSize: input.batch.length,
+        firstInput,
+        elapsedMs: Date.now() - input.startedAt,
+        retryAfterMs: input.retryAfterMs,
+        queued: this.#queued.length,
+        blocked: this.#blocked.length,
+        bufferedBytes: this.#bufferedBytes,
+        ...(input.error === undefined ? {} : { error: input.error }),
+      });
+    } catch {
+      // Receipt telemetry must never affect durable delivery.
+    }
+  }
+
   async #waitForRetry(
     delayMs: number,
     batch: readonly PendingWrite<Input, Output>[],

package/dist/cli/index.js

@@ -718,7 +718,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.300",
+  version: "0.1.301",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/cli/index.mjs

@@ -703,7 +703,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.300",
+  version: "0.1.301",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/index.js

@@ -438,7 +438,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.300",
+  version: "0.1.301",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/index.mjs

@@ -367,7 +367,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.300",
+  version: "0.1.301",
   contracts: {
     api: {
       name: "sdk-http-api",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.300",
+  "version": "0.1.301",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {