deepline 0.1.207 → 0.1.209

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

@@ -51,11 +51,6 @@ import {
   PLAY_RUNTIME_API_COMPAT_PATH,
   PLAY_RUNTIME_CHILD_EXECUTOR_TOKEN_COMPAT_PATH,
 } from './runtime-api-paths';
-import {
-  settleInlineChildRunViaAppRuntime,
-  startRunViaAppRuntime,
-} from './app-runtime-api';
-import { executeChildRunLifecycle } from './child-run-lifecycle';
 import {
   createRootRunExecutionScope,
   deriveChildRunExecutionScope,
@@ -79,6 +74,7 @@ import {
   type RuntimeResourceGovernor,
 } from './resource-governor';
 import { CTX_FETCH_EGRESS_TOOL_ID } from './builtin-pacing';
+import { ProviderExhaustedError } from './run-failure';
 import { InMemoryRateStateBackend } from './governor/in-memory-rate-state-backend';
 import { pacingPolicyForTool } from './pacing';
 import {
@@ -136,7 +132,7 @@ import {
   isQueryResultDatasetReadRequest,
   isQueryResultDatasetTool,
 } from './query-result-dataset';
-import { isAbortLikeError, isRowIsolationExemptError } from './row-isolation';
+import { isRowIsolationExemptError } from './row-isolation';
 import {
   createRuntimePersistenceLatch,
   RuntimePersistenceCircuitOpenError,
@@ -241,7 +237,10 @@ import {
   type StepProgramDatasetOptions,
 } from './step-program-dataset-builder';
 import { readRuntimeSheetDatasetRows } from './runtime-api';
-import { resolveChildExecutionStrategy } from './child-execution-strategy';
+import {
+  resolveChildExecutionStrategy,
+  inlineChildScheduledInRowMessage,
+} from './child-execution-strategy';
 
 type ResolvedPlayExecutor = (
   ctx: PlayContextImpl,
@@ -292,6 +291,14 @@ const CHILD_PLAY_LAUNCH_ADMISSION_RETRY_DELAYS_MS = [
 ] as const;
 const NODE_RUNTIME_MAP_VISIBILITY_MAX_ATTEMPTS = 100;
 const NODE_RUNTIME_MAP_VISIBILITY_RETRY_MS = 25;
+// Per-row sanity cap on distinct inline child invocations. `maxPlayCallDepth`
+// (governor) already bounds nesting; this bounds fan-WIDTH from a single row so
+// a resolver that loops `ctx.runPlay` unbounded fails loudly instead of leaking
+// composition namespaces. Well above any legitimate authored per-row fan-out.
+const MAX_INLINE_CHILD_INVOCATIONS_PER_ROW = 512;
+// Bound the retained failure detail carried in parent aggregates so a fully
+// failing large map cannot grow the progress event without limit.
+const MAX_INLINE_CHILD_FAILURE_DETAIL = 25;
 // A single batched runtime-step-receipt request (get/claim/complete/fail/seed)
 // carries at most this many keys. At map scale a run can hold 5k-10k receipt
 // keys; sending them all in one request made the server claim/complete them
@@ -1088,6 +1095,30 @@ export class PlayContextImpl {
     createSecretRedactionContext();
   private mapInvocationIndex = 0;
   private readonly stepCallIndexByKey = new Map<string, number>();
+  /**
+   * Registry of distinct inline child invocation namespaces seen by this
+   * context. Inline child composition is a function call, not a run; each
+   * invocation's namespace (`child:<playName>#<callKey>[@<rowScope>]`) scopes
+   * its receipts under the parent run. See ADR 0013.
+   */
+  private readonly inlineChildInvocationOrdinals = new Map<string, number>();
+  /**
+   * Distinct inline child invocations per row scope (top-level counts as one
+   * scope). Backs the per-row fan-width sanity cap so a resolver looping
+   * `ctx.runPlay` unbounded fails loudly instead of leaking namespaces.
+   */
+  private readonly inlineChildInvocationsPerRow = new Map<string, number>();
+  /**
+   * Parent-level inline-child aggregates. Maintained only by the single-writer
+   * progress path (never per child) so concurrent fan-out cannot contend. See
+   * `flushInlineChildAggregates` and ADR 0013.
+   */
+  private inlineChildAggregates: {
+    total: number;
+    ok: number;
+    failed: number;
+    failures: Array<{ childPlayName: string; error: string }>;
+  } = { total: 0, ok: 0, failed: 0, failures: [] };
   /**
    * Runtime persistence-failure circuit breaker (postgres_fast parity with the
    * Workers runtime). The first persistence failure — a receipt-completion
@@ -4906,6 +4937,9 @@ export class PlayContextImpl {
             completedRowKeys.size,
           failedRows,
           totalRows,
+          // Inline child aggregates ride the single-writer progress event so
+          // fan-out never contends on a per-child mutation. See ADR 0013.
+          ...this.inlineChildAggregateEventFields(),
           at: Date.now(),
         } as PlayExecutionEvent);
       }
@@ -5448,34 +5482,66 @@ export class PlayContextImpl {
     const produced: Record<string, unknown> = {};
     for (const step of program.steps) {
       const stepPath = [...path, step.name];
-      const value = options?.checkpointSteps
-        ? await this.step(
-            stepPath.join('.'),
-            async () =>
-              await this.executeStepProgramStep(
-                step,
-                currentRow,
-                index,
-                stepPath,
-                undefined,
-              ),
-            {
-              semanticKey: stableDigest(
-                stableStringify({
+      const runStep = async () =>
+        options?.checkpointSteps
+          ? await this.step(
+              stepPath.join('.'),
+              async () =>
+                await this.executeStepProgramStep(
+                  step,
+                  currentRow,
                   index,
-                  input: currentRow,
                   stepPath,
-                }),
-              ),
-            },
-          )
-        : await this.executeStepProgramStep(
-            step,
-            currentRow,
-            index,
-            stepPath,
-            undefined,
-          );
+                  undefined,
+                ),
+              {
+                semanticKey: stableDigest(
+                  stableStringify({
+                    index,
+                    input: currentRow,
+                    stepPath,
+                  }),
+                ),
+              },
+            )
+          : await this.executeStepProgramStep(
+              step,
+              currentRow,
+              index,
+              stepPath,
+              undefined,
+            );
+      let value: unknown;
+      try {
+        value = await runStep();
+      } catch (error) {
+        // PROVIDER_EXHAUSTED is a step MISS, not a program abort. The pacer
+        // skipped this provider (no spend, no dispatch); resolve the step as an
+        // empty result so the row falls through to the next step's `runIf` chain
+        // exactly as it would for a provider miss. Any OTHER error keeps its
+        // existing propagation (row-isolation / abort semantics unchanged).
+        if (!(error instanceof ProviderExhaustedError)) throw error;
+        value = null;
+        const rowStore = rowContext.getStore();
+        const fieldName = stepPath.join('.');
+        if (rowStore) {
+          this.emitScopedFieldMetaUpdate({
+            rowId: rowStore.rowId,
+            key: rowStore.rowKey ?? null,
+            tableNamespace: rowStore.tableNamespace ?? null,
+            fieldName,
+            status: 'failed',
+            rowStatus: 'running',
+            stage: 'failed',
+            provider: null,
+            error: this.formatRuntimeError(error),
+            dataPatch: {},
+          });
+        }
+        produced[step.name] = value;
+        currentRow = cloneCsvAliasedRow(currentRow, { [step.name]: value });
+        continue;
+      }
       produced[step.name] = value;
       const rowStore = rowContext.getStore();
       const fieldName = stepPath.join('.');
@@ -6319,6 +6385,34 @@ export class PlayContextImpl {
         `ctx.runPlay(${normalizedKey}): ${childExecutionDecision.strategy} (${childExecutionDecision.reason})`,
       );
       const runPlayRowScope = rowContext.getStore();
+      // Runtime enforcement of the row-scoped-scheduled-child rule for children
+      // whose name is only known at runtime (static preflight cannot see them).
+      // A scheduling-required child fanned out per row is the 100,000-run-doc
+      // failure mode the inline-child cutover removes. Fail on the FIRST row,
+      // loud, with the SAME message the static preflight emits. See ADR 0013.
+      //
+      // Mirrors the static check's proof standard: reject when the child's
+      // resolved contract PROVES it needs scheduling (dataset/csv, event-wait,
+      // explicit timeout), or when this call would actually launch a durable
+      // scheduled child run per row. A missing static contract alone is not
+      // proof — in-process fallback runtimes legitimately run contract-less
+      // scalar children inline.
+      const provablySchedulingRequired =
+        childExecutionDecision.strategy === 'scheduled' &&
+        childExecutionDecision.reason !== 'missing_static_contract';
+      if (
+        runPlayRowScope &&
+        (provablySchedulingRequired || launchThroughScheduler)
+      ) {
+        throw new Error(
+          inlineChildScheduledInRowMessage(
+            resolvedName,
+            runPlayRowScope.tableNamespace ??
+              runPlayRowScope.fieldName ??
+              'dataset',
+          ),
+        );
+      }
       const runPlaySemanticKey = buildDurableRunPlaySemanticKey({
         childPlayName: resolvedName,
         childRevisionFingerprint,
@@ -6339,33 +6433,35 @@ export class PlayContextImpl {
         // cycle guard, depth cap, per-parent cap, and play/descendant charges, so
         // a recovered receipt (which skips this body) never consumes budget.
         //
-        // The child run id is derived through the shared canonical builder so the
-        // in-process runtime and the workers_edge coordinator produce the same
-        // FORMAT (`play/<slug>/run/child-<digest>`) via the same code. The digest
-        // is deterministic across replay because every input (parent lineage,
-        // call key, input) is stable. Per-substrate difference: in-process has no
-        // coordinator idempotency key and no compiled child graphHash, so it uses
-        // the semantic fallback with graphHash omitted; workers_edge feeds the
-        // durable child idempotency key. See child-run-id.ts.
-        const childRunId = buildChildRunId({
-          childPlayName: resolvedName,
-          parentRunId: this.currentRunId,
-          parentPlayName: this.#options.playName,
-          key: normalizedKey,
-          runPlaySemanticKey,
-          input,
-          graphHash: null,
-        });
+        // The SCHEDULED substrate still allocates a durable child run id (through
+        // the shared canonical builder so in-process and the workers_edge
+        // coordinator produce the same FORMAT `play/<slug>/run/child-<digest>`).
+        // INLINE scalar children are pure function composition (ADR 0013): they
+        // carry NO durable run identity — no child run id, no playRuns doc, no
+        // settlement. Their only identity is a replay-stable, call-site scoped
+        // composition namespace (`child:<playName>#<ordinal>`) used to scope tool
+        // receipts under the PARENT run. See child-composition-namespace below.
         const inlineChildGovernor = launchThroughScheduler
           ? null
           : await this.governor.forkInlineChild({
               childPlayName: resolvedName,
-              childRunId,
+              childRunId: this.inlineChildCompositionNamespace(
+                resolvedName,
+                normalizedKey,
+              ),
             });
         const childGovernance = launchThroughScheduler
           ? await this.governor.forkChild({
               childPlayName: resolvedName,
-              childRunId,
+              childRunId: buildChildRunId({
+                childPlayName: resolvedName,
+                parentRunId: this.currentRunId,
+                parentPlayName: this.#options.playName,
+                key: normalizedKey,
+                runPlaySemanticKey,
+                input,
+                graphHash: null,
+              }),
             })
           : inlineChildGovernor!.snapshot();
         const childPlaySlot = launchThroughScheduler
@@ -6377,7 +6473,9 @@ export class PlayContextImpl {
           id: normalizedKey,
           playId: resolvedName,
           displayName: displayNameFromProducerId(resolvedName),
-          runId: childRunId,
+          // For scheduled children this is the durable child run id; for inline
+          // children it is the composition namespace (`child:<playName>#<ord>`).
+          runId: childGovernance.currentRunId,
         };
         try {
           if (rowStore) {
@@ -6490,112 +6588,93 @@ export class PlayContextImpl {
               this.consumePendingChildPlaySuspension() ?? suspension,
             );
           }
+          // Inline child = pure function composition (ADR 0013). No durable
+          // child run: no playRuns doc, no start/settle round-trip, no
+          // OptimisticConcurrencyControlFailure fan-out. The child's tool
+          // receipts still land durably under the PARENT run (the inline
+          // execution scope keeps the parent's receipt.ownerRunId) scoped by the
+          // replay-stable composition namespace (which also enforces the
+          // per-row inline-invocation sanity cap at creation).
+          const compositionNamespace = childGovernance.currentRunId;
           const childExecutionScope = deriveChildRunExecutionScope(
             this.executionScope,
             {
               placement: 'inline',
-              runId: childGovernance.currentRunId,
+              runId: compositionNamespace,
               playId: resolvedName,
-              receiptNamespace: `${resolvedName}:${childGovernance.currentRunId}`,
+              receiptNamespace: compositionNamespace,
             },
           );
-          return await executeChildRunLifecycle({
-            scope: childExecutionScope,
-            metadata: {
-              placement: 'inline',
-              childPlayName: resolvedName,
-              staticPipeline: resolvedPlay.staticPipeline ?? null,
-            },
-            adapter: {
-              open: async () => {
-                await this.registerInlineChildRun({
-                  scope: childExecutionScope,
-                  staticPipeline: resolvedPlay.staticPipeline ?? null,
-                });
-              },
-              // start_inline_child_run records run.started with the durable row.
-              started: () => undefined,
-              complete: async (_scope, _metadata, result) => {
-                await this.settleInlineChildRun({
-                  scope: childExecutionScope,
-                  status: 'completed',
-                  result,
-                });
-              },
-              fail: async (_scope, _metadata, error) => {
-                await this.settleInlineChildRun({
-                  scope: childExecutionScope,
-                  status: isAbortLikeError(error) ? 'cancelled' : 'failed',
-                  error: this.formatRuntimeError(error),
-                });
-              },
-            },
-            execute: async () => {
-              const inlineScalarChild =
-                childExecutionDecision.reason === 'scalar_child';
-              const childContext = createPlayContext({
-                ...this.#options,
-                executionScope: childExecutionScope,
-                playId: resolvedName,
-                playName: resolvedName,
-                runId: childGovernance.currentRunId,
-                executorToken: inlineScalarChild
-                  ? this.#options.executorToken
-                  : await this.mintChildExecutorToken({
-                      parentRunId: this.currentRunId,
-                      parentPlayName: this.#options.playName,
-                      childRunId: childGovernance.currentRunId,
-                      childPlayName: resolvedName,
-                    }),
-                staticPipeline: resolvedPlay.staticPipeline ?? null,
-                checkpoint: this.checkpoint,
-                governance: undefined,
-                executionGovernor: inlineChildGovernor!,
-                ...(inlineScalarChild
-                  ? {}
-                  : {
-                      getRuntimeStepReceipt: undefined,
-                      getRuntimeStepReceipts: undefined,
-                      claimRuntimeStepReceipt: undefined,
-                      claimRuntimeStepReceipts: undefined,
-                      completeRuntimeStepReceipt: undefined,
-                      completeRuntimeStepReceipts: undefined,
-                      failRuntimeStepReceipt: undefined,
-                      failRuntimeStepReceipts: undefined,
-                      heartbeatRuntimeStepReceipts: undefined,
-                      skipRuntimeStepReceipt: undefined,
-                    }),
-              });
-              const childExecution = this.executeResolvedPlay(
-                resolvedPlay,
-                childContext,
-                input,
-              );
-              await childContext.drainQueuedWork([childExecution]);
-              const result = await childExecution;
-              if (rowStore) {
-                this.emitScopedFieldMetaUpdate({
-                  rowId: rowStore.rowId,
-                  key: rowStore.rowKey ?? null,
-                  tableNamespace: rowStore.tableNamespace ?? null,
-                  fieldName: rowStore.fieldName,
-                  status: 'completed',
-                  rowStatus: 'running',
-                  stage: resolvedName,
-                  provider: 'deepline_native',
-                  error: null,
-                  producer,
-                  dataPatch: {},
-                });
-              }
-              this.recordPlayCallStep({
-                playId: resolvedName,
-                description: options?.description,
-                nestedSteps: childContext.getSteps(),
-              });
-              return result as TOutput;
-            },
+          this.inlineChildAggregates.total += 1;
+          const inlineScalarChild =
+            childExecutionDecision.reason === 'scalar_child';
+          const childContext = createPlayContext({
+            ...this.#options,
+            executionScope: childExecutionScope,
+            playId: resolvedName,
+            playName: resolvedName,
+            runId: compositionNamespace,
+            executorToken: inlineScalarChild
+              ? this.#options.executorToken
+              : await this.mintChildExecutorToken({
+                  parentRunId: this.currentRunId,
+                  parentPlayName: this.#options.playName,
+                  childRunId: compositionNamespace,
+                  childPlayName: resolvedName,
+                }),
+            staticPipeline: resolvedPlay.staticPipeline ?? null,
+            checkpoint: this.checkpoint,
+            governance: undefined,
+            executionGovernor: inlineChildGovernor!,
+            ...(inlineScalarChild
+              ? {}
+              : {
+                  getRuntimeStepReceipt: undefined,
+                  getRuntimeStepReceipts: undefined,
+                  claimRuntimeStepReceipt: undefined,
+                  claimRuntimeStepReceipts: undefined,
+                  completeRuntimeStepReceipt: undefined,
+                  completeRuntimeStepReceipts: undefined,
+                  failRuntimeStepReceipt: undefined,
+                  failRuntimeStepReceipts: undefined,
+                  heartbeatRuntimeStepReceipts: undefined,
+                  skipRuntimeStepReceipt: undefined,
+                }),
           });
+          try {
+            const childExecution = this.executeResolvedPlay(
+              resolvedPlay,
+              childContext,
+              input,
+            );
+            await childContext.drainQueuedWork([childExecution]);
+            const result = await childExecution;
+            this.inlineChildAggregates.ok += 1;
+            if (rowStore) {
+              this.emitScopedFieldMetaUpdate({
+                rowId: rowStore.rowId,
+                key: rowStore.rowKey ?? null,
+                tableNamespace: rowStore.tableNamespace ?? null,
+                fieldName: rowStore.fieldName,
+                status: 'completed',
+                rowStatus: 'running',
+                stage: resolvedName,
+                provider: 'deepline_native',
+                error: null,
+                producer,
+                dataPatch: {},
+              });
+            }
+            this.recordPlayCallStep({
+              playId: resolvedName,
+              description: options?.description,
+              nestedSteps: childContext.getSteps(),
+            });
+            return result as TOutput;
+          } catch (childError) {
+            this.recordInlineChildFailure(resolvedName, childError);
+            throw childError;
+          }
         } catch (error) {
           if (isPlayExecutionSuspendedError(error)) {
             throw error;
@@ -6695,65 +6774,91 @@ export class PlayContextImpl {
     return body.executorToken.trim();
   }
 
-  private async registerInlineChildRun(input: {
-    scope: RunExecutionScope;
-    staticPipeline: unknown;
-  }): Promise<void> {
-    const baseUrl = this.#options.baseUrl?.trim();
-    const executorToken = this.#options.executorToken?.trim();
-    if (!baseUrl || !executorToken) return;
-
-    await startRunViaAppRuntime(
-      {
-        baseUrl,
-        executorToken,
-        integrationMode: this.#options.integrationMode ?? null,
-        vercelProtectionBypassToken:
-          this.#options.vercelProtectionBypassToken ?? null,
-      },
-      {
-        playName: input.scope.logical.playId,
-        runId: input.scope.logical.runId,
-        parentRunId: input.scope.logical.parentRunId,
-        rootRunId: input.scope.logical.rootRunId,
-        workflowFamilyKey: input.scope.logical.rootRunId,
-        artifactHash: this.#options.artifactHash ?? null,
-        graphHash: this.#options.graphHash ?? null,
-        schedulerSchema: this.#options.runtimeSchedulerSchema ?? null,
-        executionProfile: this.#options.childRunProfile ?? 'absurd',
-        staticPipeline: input.staticPipeline,
-        source: 'published',
-      },
-    );
+  /**
+   * Replay-stable composition namespace for one inline `ctx.runPlay`
+   * invocation. Format `child:<playName>#<callKey>[@<rowScope>]`:
+   *
+   *   - `callKey` is the author's normalized `ctx.runPlay(key, ...)` call key,
+   *     so distinct call sites never collide.
+   *   - `rowScope` (table namespace + row key) is appended when the invocation
+   *     runs inside a map/dataset row resolver, so the SAME call site invoked
+   *     across rows scopes each row's child step receipts separately.
+   *
+   * The namespace is derived purely from authored, content-stable inputs —
+   * never from arrival order — so a retried run attempt reproduces the same
+   * namespace under any row-completion interleaving and the child's tool
+   * receipts (owned by the PARENT run) recover instead of re-billing. Inline
+   * children carry NO durable run id — this namespace is their only identity.
+   * See ADR 0013.
+   */
+  private inlineChildCompositionNamespace(
+    childPlayName: string,
+    normalizedKey: string,
+  ): string {
+    const rowScope = rowContext.getStore();
+    const rowScopeKey = rowScope
+      ? `${rowScope.tableNamespace ?? rowScope.fieldName ?? 'rows'}:${
+          rowScope.rowKey ?? String(rowScope.rowId)
+        }`
+      : '';
+    const namespace = `child:${childPlayName}#${normalizedKey}${
+      rowScopeKey ? `@${rowScopeKey}` : ''
+    }`;
+    if (!this.inlineChildInvocationOrdinals.has(namespace)) {
+      // Per-row fan-width guard. `maxPlayCallDepth` (governor) bounds nesting;
+      // this bounds distinct inline invocations from ONE row scope so a
+      // resolver looping runPlay unbounded fails loudly on that row instead of
+      // leaking namespaces.
+      const rowInvocationCount =
+        (this.inlineChildInvocationsPerRow.get(rowScopeKey) ?? 0) + 1;
+      if (rowInvocationCount > MAX_INLINE_CHILD_INVOCATIONS_PER_ROW) {
+        throw new Error(
+          `ctx.runPlay("${childPlayName}") exceeded the inline child invocation cap ` +
+            `(${MAX_INLINE_CHILD_INVOCATIONS_PER_ROW} per row). A resolver is calling ` +
+            'runPlay in an unbounded loop; give the batch ONE dataset child at play level instead.',
+        );
+      }
+      this.inlineChildInvocationsPerRow.set(rowScopeKey, rowInvocationCount);
+      this.inlineChildInvocationOrdinals.set(
+        namespace,
+        this.inlineChildInvocationOrdinals.size,
+      );
+    }
+    return namespace;
   }
 
-  private async settleInlineChildRun(input: {
-    scope: RunExecutionScope;
-    status: 'completed' | 'failed' | 'cancelled';
-    result?: unknown;
-    error?: string | null;
-  }): Promise<void> {
-    const baseUrl = this.#options.baseUrl?.trim();
-    const executorToken = this.#options.executorToken?.trim();
-    if (!baseUrl || !executorToken) return;
+  private recordInlineChildFailure(
+    childPlayName: string,
+    error: unknown,
+  ): void {
+    this.inlineChildAggregates.failed += 1;
+    if (
+      this.inlineChildAggregates.failures.length <
+      MAX_INLINE_CHILD_FAILURE_DETAIL
+    ) {
+      this.inlineChildAggregates.failures.push({
+        childPlayName,
+        error: this.formatRuntimeError(error),
+      });
+    }
+  }
 
-    await settleInlineChildRunViaAppRuntime(
-      {
-        baseUrl,
-        executorToken,
-        integrationMode: this.#options.integrationMode ?? null,
-        vercelProtectionBypassToken:
-          this.#options.vercelProtectionBypassToken ?? null,
-      },
-      {
-        parentRunId: input.scope.logical.parentRunId ?? this.currentRunId,
-        childRunId: input.scope.logical.runId,
-        childPlayName: input.scope.logical.playId,
-        status: input.status,
-        ...(input.result !== undefined ? { result: input.result } : {}),
-        ...(input.error !== undefined ? { error: input.error } : {}),
-      },
-    );
+  /**
+   * Snapshot of inline child aggregates for the single-writer progress event.
+   * Read-only; never mutates. Omitted entirely when no inline child has run so
+   * plays without child composition keep byte-identical progress events.
+   */
+  private inlineChildAggregateEventFields(): {
+    childrenTotal?: number;
+    childrenOk?: number;
+    childrenFailed?: number;
+  } {
+    if (this.inlineChildAggregates.total === 0) return {};
+    return {
+      childrenTotal: this.inlineChildAggregates.total,
+      childrenOk: this.inlineChildAggregates.ok,
+      childrenFailed: this.inlineChildAggregates.failed,
+    };
   }
 
   /**

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -412,6 +412,14 @@ export type PlayExecutionEvent =
       completedRows: number;
       failedRows: number;
       totalRows?: number;
+      /**
+       * Inline child-play composition aggregates for this run. Maintained by the
+       * single-writer progress path (never per child), so fan-out cannot contend.
+       * See ADR 0013.
+       */
+      childrenTotal?: number;
+      childrenOk?: number;
+      childrenFailed?: number;
       at: number;
     }
   | {
@@ -436,6 +444,13 @@ export type PlayExecutionEvent =
       completedRows: number;
       failedRows: number;
       totalRows?: number;
+      /**
+       * Inline child-play composition aggregates for this run. Maintained by the
+       * single-writer progress path (never per child). See ADR 0013.
+       */
+      childrenTotal?: number;
+      childrenOk?: number;
+      childrenFailed?: number;
       at: number;
     };