deepline 0.3.71 → 0.3.72

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.71',
+  version: '0.3.72',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -195,8 +195,11 @@ import {
   type PlayAuthoringRuntimeContext,
 } from '../plays/authoring-contract';
 import {
+  LOG_LEVELS,
   formatCtxFetchHttpFailureDiagnostic,
-  tagLogProvenance,
+  tagLogEntry,
+  tagLogLevel,
+  type LogLevel,
 } from './log-provenance';
 import {
   DURABLE_RECEIPT_WAIT_DELAY_MS,
@@ -1432,6 +1435,22 @@ const IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT = 25;
  */
 const MAX_CELL_PRODUCER_ATTEMPTS = 12;
 const BATCH_SIZE_LOG_SAMPLE_LIMIT = 10;
+
+/**
+ * A 100k-row Play must not turn `ctx.log` into a second data plane. Keep an
+ * initial useful window, then deterministic samples and explicit durable
+ * warnings. Warn/error are never sampled: losing the actual failure is worse
+ * than spending additional log capacity.
+ */
+const LOG_RATE_LIMIT_POLICY: Readonly<
+  Record<Exclude<LogLevel, 'warn' | 'error'>, { first: number; every: number }>
+> = {
+  debug: { first: 200, every: 100 },
+  info: { first: 1_000, every: 100 },
+};
+const LOG_RATE_LIMIT_MARKER_EVERY = 1_000;
+
+type LogRateLimitState = { seen: number; sampled: number; suppressed: number };
 const STEP_PROGRAM_MAP_DEFINITION = Symbol('deepline.stepProgramMapDefinition');
 
 function shouldPersistMapCellField(fieldName: string): boolean {
@@ -2095,6 +2114,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   #options: ContextOptions;
   private readonly executionScope: RunExecutionScope;
   private logBuffer: string[] = [];
+  private readonly logRateLimitState = new Map<
+    Exclude<LogLevel, 'warn' | 'error'>,
+    LogRateLimitState
+  >();
   private readonly ctxFetchHttpFailureDiagnosticIdentities = new Set<string>();
   private checkpoint: PlayCheckpoint;
   private readonly durableCallCacheEpochMs: number;
@@ -3022,7 +3045,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             attempt,
             retryAfter: null,
           });
-          this.log(
+          this.runtimeLog(
             `[runtime.secret_resolution_failure] ${JSON.stringify({
               stage: 'transport',
               secret_name: secret.name,
@@ -3077,7 +3100,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           retry_after_exceeds_cap: retry.retryAfterExceedsCap,
         };
         if (!response.ok) {
-          this.log(
+          this.runtimeLog(
             `[runtime.secret_resolution_failure] ${JSON.stringify(responseDiagnostic)}`,
           );
           cancelRuntimeResponseBody(response);
@@ -3094,7 +3117,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         try {
           payload = await response.json();
         } catch (error) {
-          this.log(
+          this.runtimeLog(
             `[runtime.secret_resolution_failure] ${JSON.stringify({
               ...responseDiagnostic,
               response_kind: 'invalid_json',
@@ -3115,7 +3138,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             ? (payload as { value: string }).value
             : null;
         if (!value) {
-          this.log(
+          this.runtimeLog(
             `[runtime.secret_resolution_failure] ${JSON.stringify({
               ...responseDiagnostic,
               response_kind:
@@ -3131,7 +3154,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           );
         }
         if (attempt > 1) {
-          this.log(
+          this.runtimeLog(
             `[runtime.secret_resolution_recovered] ${JSON.stringify({
               secret_name: secret.name,
               gateway_origin: transportGatewayOriginForDiagnostic(url),
@@ -3739,7 +3762,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       if (normalized) byKey.set(normalized.key, normalized);
     }
     if (runtimeReceiptReadTraceEnabled) {
-      this.log(
+      this.runtimeLog(
         `[runtime-receipt-normalize] ${runtimeReceiptReadSummary({
           requested: uniqueKeys,
           receipts,
@@ -3751,7 +3774,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         receipts,
         byKey,
       });
-      if (trace) this.log(trace);
+      if (trace) this.runtimeLog(trace);
     }
     return byKey;
   }
@@ -3806,7 +3829,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       if (normalized) byKey.set(normalized.key, normalized);
     }
     if (runtimeReceiptReadTraceEnabled) {
-      this.log(
+      this.runtimeLog(
         `[runtime-receipt-claim-normalize] reclaim_running=${reclaimRunning} force_refresh=${forceRefresh} force_failed_refresh=${forceFailedRefresh} ` +
           runtimeReceiptReadSummary({
             requested: uniqueKeys,
@@ -4039,7 +4062,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       completedByKey.has(key),
     ).length;
     if (recoveredCount > 0) {
-      this.log(
+      this.runtimeLog(
         `Runtime tool receipt completion response reconciled ${recoveredCount}/${missingKeys.length} missing receipt(s) from durable store read-back.`,
       );
     }
@@ -4326,7 +4349,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       receiptKeys: keys,
       store: this.durableReceiptExecutionStore(),
       maxAttempts,
-      log: (message) => this.log(message),
+      log: (message) => this.runtimeLog(message),
       toolErrorSchemaVersion: this.currentToolErrorSchemaVersion,
     });
   }
@@ -4430,7 +4453,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         executionLockTtlMs: opts.executionLockTtlMs,
         toolErrorSchemaVersion: this.currentToolErrorSchemaVersion,
         formatError: (error) => this.formatRuntimeError(error),
-        log: (message) => this.log(message),
+        log: (message) => this.runtimeLog(message),
         execute: ({ leaseId }) => execute(leaseId),
       });
     } finally {
@@ -5781,7 +5804,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       completed?.status !== 'completed' &&
       completed?.status !== 'skipped'
     ) {
-      this.log(
+      this.runtimeLog(
         `Durable tool call ${receiptKey} completed live after its receipt lease moved; using live result without overwriting the receipt.`,
       );
     }
@@ -6018,7 +6041,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         'ctx.runSteps.options.description',
         options.description,
       );
-      this.log(options.description);
+      this.runtimeLog(options.description);
     }
     return (await this.executeStepProgram(program, input, 0, [], {
       checkpointSteps: true,
@@ -6249,7 +6272,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         immediateMaterializedRows.length = 0;
         immediateMaterializedResidentBytes = 0;
         immediateMaterializedCacheEnabled = false;
-        this.log(
+        this.runtimeLog(
           `Dataset ${normalizedMapNamespace} result cache disabled (${reason}); using the durable runtime sheet.`,
         );
       };
@@ -6862,7 +6885,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       : { rows: rawMaterializedItems, droppedCount: 0, duplicateKeys: [] };
     if (dedupedMaterialized.droppedCount > 0) {
       const keySample = dedupedMaterialized.duplicateKeys.join(', ');
-      this.log(
+      this.runtimeLog(
         `deduped ${dedupedMaterialized.droppedCount} duplicate dataset key(s) for ctx.dataset("${normalizedMapNamespace}"); keeping first occurrence` +
           (keySample ? ` (e.g. ${keySample})` : ''),
       );
@@ -7159,7 +7182,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         const persistStartedAt = Date.now();
         await persistMapRows(unpersistedRows);
         if (unpersistedRows.length > 0) {
-          this.log(
+          this.runtimeLog(
             `Persisted ${unpersistedRows.length} fail-fast rows to sheet ${resolvedTableNamespace} in ${Date.now() - persistStartedAt}ms`,
           );
         }
@@ -7227,7 +7250,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       const persistStartedAt = Date.now();
       await persistMapRows(persistRows);
       if (persistRows.length > 0) {
-        this.log(
+        this.runtimeLog(
           `Persisted ${persistRows.length} executed rows to sheet ${resolvedTableNamespace} in ${Date.now() - persistStartedAt}ms`,
         );
       }
@@ -7285,7 +7308,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         expectedRows: totalInputCount,
         currentRows: results,
         failedRowCount: mapResult.failedRows.length,
-        log: (line) => this.log(line),
+        log: (line) => this.runtimeLog(line),
         readPersistedRows: async (readInput) => {
           if (
             !this.#options.baseUrl ||
@@ -7548,7 +7571,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         completedRowsToPersist.length = 0;
         failedRowsToPersist.length = 0;
         retainedRowsComplete = false;
-        this.log(
+        this.runtimeLog(
           `Dataset ${normalizedTableNamespace} released its in-memory result cache after ${completedRowCount + failedRowCount} row(s); using the durable Runtime Sheet.`,
         );
       }
@@ -7583,11 +7606,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     };
 
     if (completedRows > 0 || pendingRows !== totalRows) {
-      this.log(
+      this.runtimeLog(
         `Starting map over ${totalRows} items with ${visibleFields.length} fields (key: ${normalizedTableNamespace}; ${completedRows} duplicate keys skipped; ${pendingRows} pending)`,
       );
     } else {
-      this.log(
+      this.runtimeLog(
         `Starting map over ${items.length} items with ${visibleFields.length} fields (key: ${normalizedTableNamespace})`,
       );
     }
@@ -7764,7 +7787,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }
       this.lastDatasetStep = datasetStep;
       this.activeDatasetStep = null;
-      this.log(
+      this.runtimeLog(
         `Map completed: ${results.length + completedRows} results (${results.length} succeeded, 0 failed, ${completedRows} duplicate keys skipped)`,
       );
       return {
@@ -7829,7 +7852,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     });
     mapStallObserver = new RuntimeMapStallObserver({
       getWriterDiagnostics: () => incrementalPersistence?.diagnostics() ?? null,
-      log: (line) => this.log(line),
+      log: (line) => this.runtimeLog(line),
       mapName: normalizedTableNamespace,
       pageOffset:
         runtimeOptions?.executionRowIndexes?.[0] ??
@@ -8281,17 +8304,20 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
     }
     for (const failedRow of failedRowsToPersist.slice(0, 3)) {
-      this.log(
+      this.runtimeLog(
         `row ${failedMapRowLogLabel(failedRow)} failed: ${failedRow.error ?? 'unknown error'}`,
+        { level: 'error' },
       );
     }
     if (failedRowsToPersist.length > 3) {
-      this.log(
+      this.runtimeLog(
         `${failedRowsToPersist.length - 3} additional row failure(s) omitted from map log`,
+        { level: 'warn' },
       );
     }
-    this.log(
+    this.runtimeLog(
       `Map completed: ${succeededRows + completedRows} results (${succeededRows} succeeded, ${failedRowCount} failed, ${completedRows} duplicate keys skipped)`,
+      failedRowCount > 0 ? { level: 'warn' } : undefined,
     );
     return {
       completedRows: [...completedRowsToPersist].sort(
@@ -9055,8 +9081,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               );
         if (dispatchable.requests.length > 0) {
           pass += 1;
-          this.log(`  Batch pass ${pass}`);
-          this.log(
+          this.runtimeLog(`  Batch pass ${pass}`);
+          this.runtimeLog(
             `  Dispatcher launch: ready=${dispatchable.requests.length} ` +
               `queued=${this.toolCallQueue.length} ` +
               `in_flight_groups=${inFlightToolExecutions.size}`,
@@ -9294,7 +9320,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 'direct',
               );
         if (cached) {
-          this.log(`Calling tool: ${toolId} recovered from checkpoint`);
+          this.runtimeLog(`Calling tool: ${toolId} recovered from checkpoint`);
           // Started and settled are paired in a finally: an uncovered throw
           // between them strands the tool node `running` forever in the
           // snapshot, which is exactly the lossy state ADR 0018 removed.
@@ -9355,7 +9381,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             );
           }
         }
-        this.log(
+        this.runtimeLog(
           toolCachePolicy.force
             ? `Calling tool: ${toolId} (force)`
             : `Calling tool: ${toolId}`,
@@ -9610,7 +9636,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           ? null
           : this.getCachedToolResultCandidate(toolId, checkpointCacheKeys);
       if (cached) {
-        this.log(`  Row ${rowId} ${toolId}: recovered from checkpoint`);
+        this.runtimeLog(`  Row ${rowId} ${toolId}: recovered from checkpoint`);
         return await this.wrapToolExecutionResult({
           toolId,
           status: cached.result.result == null ? 'no_result' : 'completed',
@@ -9730,7 +9756,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         // of a silent continuation: the credential identity changed after the
         // receipt key was prepared, so we evict the cached digest, re-resolve,
         // and re-claim a fresh receipt under the new scope before retrying once.
-        this.log(
+        this.runtimeLog(
           `ctx.tools.execute(${toolId}): auth_scope_changed_reclaim ` +
             `(label: ${normalizedKey}); credential identity changed mid-run, ` +
             `re-resolving auth scope and re-claiming a fresh receipt under the ` +
@@ -9801,7 +9827,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const existing =
       this.checkpoint.resolvedBoundaries?.[preparedBoundary.boundaryId];
     if (existing?.kind === 'integration_event' && 'output' in existing) {
-      this.log(
+      this.runtimeLog(
         `Integration event ${preparedBoundary.boundaryId}: recovered response from checkpoint`,
       );
       // Wrapped like every other tool result (toolOutput.raw, getters) — the
@@ -9824,7 +9850,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       boundary: preparedBoundary,
     });
 
-    this.log(
+    this.runtimeLog(
       `Armed ${handler.provider} integration event wait: ${boundary.eventKey}`,
     );
     this.checkpoint.resolvedBoundaries = {
@@ -9936,7 +9962,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       execution: options?.execution,
       childPlayName: resolvedName,
     });
-    this.log(
+    this.runtimeLog(
       `ctx.runPlay(${normalizedKey}): ${childExecutionDecision.strategy} (${childExecutionDecision.reason})`,
     );
 
@@ -10182,22 +10208,89 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
   }
 
-  log(msg: string): void {
+  log(msg: string, options?: { level?: LogLevel }): void {
     assertNoSecretTaint(msg, 'ctx.log');
-    const line = `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(msg)}`;
+    const requestedLevel = options?.level;
+    if (requestedLevel !== undefined && !LOG_LEVELS.includes(requestedLevel)) {
+      throw new Error(
+        `ctx.log level must be one of: ${LOG_LEVELS.join(', ')}.`,
+      );
+    }
+    const level = requestedLevel ?? 'info';
+    const timestamped = `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(msg)}`;
+    // Stamp the default too: a customer message that happens to begin with
+    // "[error]" is still info unless the author selected a higher severity.
+    const line = tagLogEntry('user', level, timestamped);
+    if (!this.shouldKeepRateLimitedLog(level)) return;
+    this.logBuffer.push(line);
+    this.#options.onLog?.(line);
+    if (this.#options.verbose) console.log(line);
+  }
+
+  /**
+   * Runtime-owned progress and failure narration must stay durable even when
+   * authored per-row logs are being sampled. Preserve the untagged historical
+   * wire shape by default: several runtime diagnostics contain trailing JSON
+   * consumed by older readers. Callers may opt into an explicit severity.
+   */
+  private runtimeLog(msg: string, options?: { level?: LogLevel }): void {
+    assertNoSecretTaint(msg, 'runtime log');
+    const timestamped = `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(msg)}`;
+    const line = options?.level
+      ? tagLogLevel(timestamped, options.level)
+      : timestamped;
     this.logBuffer.push(line);
     this.#options.onLog?.(line);
     if (this.#options.verbose) console.log(line);
   }
 
+  /** Rate-limit chatty authored logs before they consume the live stream or durable retention. */
+  private shouldKeepRateLimitedLog(level: LogLevel): boolean {
+    if (level === 'warn' || level === 'error') return true;
+    const policy = LOG_RATE_LIMIT_POLICY[level];
+    const state = this.logRateLimitState.get(level) ?? {
+      seen: 0,
+      sampled: 0,
+      suppressed: 0,
+    };
+    state.seen += 1;
+    const keep = state.seen <= policy.first || state.seen % policy.every === 0;
+    if (keep) {
+      if (state.seen > policy.first) state.sampled += 1;
+      this.logRateLimitState.set(level, state);
+      return true;
+    }
+    state.suppressed += 1;
+    this.logRateLimitState.set(level, state);
+    if (
+      state.suppressed === 1 ||
+      state.suppressed % LOG_RATE_LIMIT_MARKER_EVERY === 0
+    ) {
+      const marker = `[log rate limited: level=${level} retained=${policy.first + state.sampled} sampled=${state.sampled} suppressed=${state.suppressed}; showing first ${policy.first}, then 1 every ${policy.every}]`;
+      const line = tagLogEntry(
+        'diagnostic',
+        'warn',
+        `[${new Date().toISOString()}] ${marker}`,
+      );
+      this.logBuffer.push(line);
+      this.#options.onLog?.(line);
+      if (this.#options.verbose) console.log(line);
+    }
+    return false;
+  }
+
   /**
    * Emit a runtime-authored diagnostic through the same durable log path as
    * ctx.log without changing the customer-authored log wire format.
    */
-  private runtimeDiagnosticLog(message: string): void {
+  private runtimeDiagnosticLog(
+    message: string,
+    level: LogLevel = 'warn',
+  ): void {
     assertNoSecretTaint(message, 'runtime diagnostic log');
-    const line = tagLogProvenance(
+    const line = tagLogEntry(
       'diagnostic',
+      level,
       `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(message)}`,
     );
     this.logBuffer.push(line);
@@ -10438,7 +10531,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             existing?.kind === 'fetch' &&
             'output' in existing
           ) {
-            this.log(`ctx.fetch(${url}): recovered response from checkpoint`);
+            this.runtimeLog(
+              `ctx.fetch(${url}): recovered response from checkpoint`,
+            );
             const checkpointOutput = existing.output as PlayFetchResponse;
             if (!checkpointOutput.ok) {
               this.logCtxFetchHttpFailure({
@@ -10556,7 +10651,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   canRetryTransport &&
                   attempt < FETCH_TRANSPORT_MAX_ATTEMPTS
                 ) {
-                  this.log(
+                  this.runtimeLog(
                     `ctx.fetch(${method} ${url}) transport failed on attempt ${attempt}/${FETCH_TRANSPORT_MAX_ATTEMPTS}; retrying: ${message}`,
                   );
                   await sleepWithinCtxFetchDeadline({
@@ -10665,7 +10760,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const executeStep = async (): Promise<T> => {
       const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
       if (existing?.kind === 'step' && 'output' in existing) {
-        this.log(
+        this.runtimeLog(
           `ctx.step(${normalizedKey}): recovered result from checkpoint`,
         );
         return existing.output as T;
@@ -10869,7 +10964,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         leaseLost ??= error;
       },
       onTransientFailure: (error) => {
-        this.log(
+        this.runtimeLog(
           `Pending tool receipt heartbeat transport failed; retrying: ${error instanceof Error ? error.message : String(error)}`,
         );
       },
@@ -11211,7 +11306,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         cohortLeaseLost ??= error;
       },
       onTransientFailure: (error) => {
-        this.log(
+        this.runtimeLog(
           `Tool Call Receipt Cohort heartbeat transport failed; retrying: ${
             error instanceof Error ? error.message : String(error)
           }`,
@@ -11829,7 +11924,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 ),
               ),
             onTransientFailure: (error) => {
-              this.log(
+              this.runtimeLog(
                 `Native Tool Call Receipt Cohort heartbeat transport failed; retrying: ${
                   error instanceof Error ? error.message : String(error)
                 }`,
@@ -11918,7 +12013,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const toolSettlements = await Promise.allSettled(
       [...byTool.entries()].map(async ([toolId, requests]) => {
-        this.log(`Executing tool batch ${toolId}: ${requests.length} calls`);
+        this.runtimeLog(
+          `Executing tool batch ${toolId}: ${requests.length} calls`,
+        );
         const successfulLiveStepCallIds = new Set<string>();
 
         const recordToolStep = (stepRequests: ToolCallRequest[]): void => {
@@ -11973,7 +12070,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 ? undefined
                 : this.getCachedToolResult(toolId, req.cacheKey);
           if (cached?.done) {
-            this.log(`  Row ${req.rowId} ${toolId}: recovered from checkpoint`);
+            this.runtimeLog(
+              `  Row ${req.rowId} ${toolId}: recovered from checkpoint`,
+            );
             const resolver = this.toolCallResolvers.get(req.callId);
             if (resolver) {
               resolver.resolve(cached.result);
@@ -12553,7 +12652,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     ),
                   ) || DURABLE_RECEIPT_WAIT_MAX_ATTEMPTS;
                 if (runtimeReceiptReadTraceEnabled) {
-                  this.log(
+                  this.runtimeLog(
                     `[runtime-receipt-wait] phase=start requested=${pendingWaits.size} ` +
                       `request_digests=${[...pendingWaits.keys()]
                         .map(runtimeReceiptKeyDigest)
@@ -12650,7 +12749,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                             : ['unknown'];
                         },
                       );
-                      this.log(
+                      this.runtimeLog(
                         `[runtime-receipt-wait] phase=delivery settled=${deliverySettlements.length} ` +
                           `rejected=${rejected.length} rejected_digests=${rejected.join(',')}`,
                       );
@@ -13540,7 +13639,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       );
     }
     if (runtimeReceiptReadTraceEnabled) {
-      this.log(
+      this.runtimeLog(
         `[perf] tool call id=${toolId} phase=governor_admission elapsed_ms=${Date.now() - admissionStartedAt}`,
       );
     }
@@ -13693,7 +13792,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           }): Promise<void> => {
             transportAttempt += 1;
             const diagnostic = describeTransportError(input.error);
-            this.log(
+            this.runtimeLog(
               `[runtime.transport_failure] ${JSON.stringify({
                 tool_id: toolId,
                 gateway_origin: transportGatewayOriginForDiagnostic(url),
@@ -13713,7 +13812,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 'plays.transport_retry_attempt',
                 transportAttempt,
               );
-              this.log(
+              this.runtimeLog(
                 `Tool ${toolId} transport failed calling ${url} on attempt ${transportAttempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS}; retrying after ${retryAfterMs}ms: ${diagnostic.message ?? 'unknown transport error'}`,
               );
               await options?.parkProviderCall?.();
@@ -13770,7 +13869,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               const ownershipStartedAt = Date.now();
               await options?.beforeProviderCall?.();
               if (runtimeReceiptReadTraceEnabled) {
-                this.log(
+                this.runtimeLog(
                   `[perf] tool call id=${toolId} phase=before_provider_ownership elapsed_ms=${Date.now() - ownershipStartedAt}`,
                 );
               }
@@ -13795,7 +13894,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         abortController?.abort(error);
                       },
                       onTransientFailure: (error) => {
-                        this.log(
+                        this.runtimeLog(
                           `Tool ${toolId} receipt heartbeat transport failed; retrying: ${error instanceof Error ? error.message : String(error)}`,
                         );
                       },
@@ -13874,7 +13973,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           signal: abortController?.signal,
                           onSelected: (value) => {
                             selected = value;
-                            this.log(
+                            this.runtimeLog(
                               `[fixture.response_delay] ${JSON.stringify({
                                 outcome: 'scheduled',
                                 provider: canonicalProvider,
@@ -13889,7 +13988,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           },
                         });
                       } catch (error) {
-                        this.log(
+                        this.runtimeLog(
                           `[fixture.response_delay] ${JSON.stringify({
                             outcome: 'aborted',
                             provider: canonicalProvider,
@@ -13904,7 +14003,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         );
                         throw error;
                       }
-                      this.log(
+                      this.runtimeLog(
                         `[fixture.response_delay] ${JSON.stringify({
                           outcome: 'completed',
                           provider: canonicalProvider,
@@ -13994,7 +14093,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   runtimeReceiptReadTraceEnabled &&
                   integrationFetchStartedAt !== null
                 ) {
-                  this.log(
+                  this.runtimeLog(
                     `[perf] tool call id=${toolId} phase=integration_fetch_body elapsed_ms=${Date.now() - integrationFetchStartedAt} status=${response.status}`,
                   );
                 }
@@ -14083,7 +14182,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 fixtureReplaySafe;
               if (!transportReplaySafe) {
                 const diagnostic = describeTransportError(transportError);
-                this.log(
+                this.runtimeLog(
                   `[runtime.transport_failure] ${JSON.stringify({
                     tool_id: toolId,
                     gateway_origin: transportGatewayOriginForDiagnostic(url),
@@ -14230,8 +14329,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   `plays.${retryAttributePrefix}_attempt`,
                   httpFailureAttempt,
                 );
-                this.log(
+                this.runtimeLog(
                   `Tool ${toolId} returned ${response.status}; retrying after ${failure.retryDelayMs}ms`,
+                  { level: 'warn' },
                 );
                 retryActivityEmitted = true;
                 this.emitExecutionEvent({
@@ -14275,7 +14375,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 });
                 continue;
               }
-              this.log(failure.error.message);
+              this.runtimeLog(failure.error.message, { level: 'error' });
               throw failure.error;
             }