deepline 0.1.227 → 0.1.229

package/dist/bundling-sources/shared_libs/play-runtime/child-execution-strategy.ts

@@ -3,101 +3,106 @@ import {
   type PlayStaticPipeline,
 } from '../plays/static-pipeline';
 import type { PlayCallExecution } from './play-call-execution';
-import { resolveChildExecutionPlacement } from './child-execution-placement';
 
-export type ChildExecutionStrategy = 'inline' | 'scheduled';
+/**
+ * `ctx.runPlay` is function composition.  It has exactly one execution
+ * placement: inline in the caller's run.  Do not add a scheduler fallback
+ * here: children that need their own run lifecycle must be top-level plays.
+ */
+export type ChildExecutionStrategy = 'inline';
 
 export type ChildExecutionDecision = {
   strategy: ChildExecutionStrategy;
-  reason:
-    | 'scalar_child'
-    | 'missing_static_contract'
-    | 'dataset_child'
-    | 'event_wait_child'
-    | 'explicit_timeout'
-    | 'explicit_inline'
-    | 'explicit_child_workflow';
+  reason: 'scalar_child' | 'explicit_inline';
 };
 
+export type CtxRunPlayInlineOnlyReason =
+  | 'missing_static_contract'
+  | 'dataset_child'
+  | 'event_wait_child'
+  | 'suspending_child'
+  | 'explicit_timeout'
+  | 'explicit_child_workflow';
+
+/** Stable machine-readable prefix for every rejected ctx.runPlay shape. */
+export const CTX_RUN_PLAY_INLINE_ONLY = 'CTX_RUN_PLAY_INLINE_ONLY';
+
+/**
+ * One public error for every unsupported child contract. The checker and
+ * runtime deliberately call this same helper so a dynamic child fails with
+ * the same actionable error as a statically known child.
+ */
+export function ctxRunPlayInlineOnlyMessage(
+  childPlayName: string,
+  reason: CtxRunPlayInlineOnlyReason,
+): string {
+  const detail: Record<CtxRunPlayInlineOnlyReason, string> = {
+    missing_static_contract: 'its static contract could not be resolved',
+    dataset_child: 'it uses ctx.dataset(), ctx.csv(), or a Runtime Sheet',
+    event_wait_child: 'it waits for an event',
+    suspending_child: 'it attempted to suspend the parent execution',
+    explicit_timeout: 'it sets an explicit timeout',
+    explicit_child_workflow: 'it requests execution: "child-workflow"',
+  };
+  return (
+    `${CTX_RUN_PLAY_INLINE_ONLY}: ctx.runPlay("${childPlayName}") only composes a resolved scalar child; ` +
+    `${detail[reason]}. Move that work to a top-level play and compose only the scalar result.`
+  );
+}
+
 /**
- * Choose execution placement from the child's authored contract. Scalar child
- * plays are ordinary function composition. Dataset and event-wait children own
- * independent durable state, so they remain scheduler jobs.
+ * Resolve an authored child contract. Any shape that would need a second run,
+ * durable scheduler state, or a suspension is rejected before invocation.
  */
 export function resolveChildExecutionStrategy(input: {
   pipeline: PlayStaticPipeline | null | undefined;
   timeoutMs?: number | null;
-  execution?: PlayCallExecution | null;
+  hasExplicitTimeout?: boolean;
+  /** `child-workflow` remains accepted as parsed legacy source solely to emit
+   * the canonical migration error rather than silently scheduling it. */
+  execution?: PlayCallExecution | 'child-workflow' | null;
   childPlayName?: string | null;
 }): ChildExecutionDecision {
+  const childPlayName = input.childPlayName?.trim() || 'child';
   if (input.execution === 'child-workflow') {
-    return { strategy: 'scheduled', reason: 'explicit_child_workflow' };
+    throw new Error(
+      ctxRunPlayInlineOnlyMessage(childPlayName, 'explicit_child_workflow'),
+    );
   }
-  const steps = input.pipeline ? flattenStaticPipeline(input.pipeline) : [];
-  const authoredDecision: ChildExecutionDecision =
-    input.timeoutMs != null
-      ? { strategy: 'scheduled', reason: 'explicit_timeout' }
-      : !input.pipeline
-        ? { strategy: 'scheduled', reason: 'missing_static_contract' }
-        : input.pipeline.tableNamespace ||
-            input.pipeline.sheetContract ||
-            steps.some((step) => step.type === 'dataset' || step.type === 'csv')
-          ? { strategy: 'scheduled', reason: 'dataset_child' }
-          : steps.some(
-                (step) =>
-                  step.type === 'tool' &&
-                  (step.isEventWait || step.toolId === 'test_wait_for_event'),
-              )
-            ? { strategy: 'scheduled', reason: 'event_wait_child' }
-            : { strategy: 'inline', reason: 'scalar_child' };
-  if (input.execution === 'inline') {
-    if (
-      authoredDecision.strategy === 'scheduled' &&
-      authoredDecision.reason !== 'missing_static_contract'
-    ) {
-      throw new Error(
-        inlineExecutionRequiresScalarChildMessage(
-          input.childPlayName?.trim() || 'child',
-          authoredDecision.reason,
-        ),
-      );
-    }
-    return { strategy: 'inline', reason: 'explicit_inline' };
+  if (!input.pipeline) {
+    throw new Error(
+      ctxRunPlayInlineOnlyMessage(childPlayName, 'missing_static_contract'),
+    );
   }
-  const placement = resolveChildExecutionPlacement({
-    requiresWorkflow: authoredDecision.strategy === 'scheduled',
-    execution: input.execution,
-  });
-  if (placement.strategy === 'inline') {
-    return { strategy: 'inline', reason: 'scalar_child' };
+  if (input.hasExplicitTimeout === true || input.timeoutMs != null) {
+    throw new Error(
+      ctxRunPlayInlineOnlyMessage(childPlayName, 'explicit_timeout'),
+    );
   }
-  return authoredDecision;
-}
 
-export function inlineExecutionRequiresScalarChildMessage(
-  childPlayName: string,
-  reason: ChildExecutionDecision['reason'],
-): string {
-  return (
-    `ctx.runPlay("${childPlayName}") requested execution: "inline", but the child requires a child workflow ` +
-    `(${reason}). Remove the explicit execution option or use execution: "child-workflow".`
-  );
-}
-
-/**
- * Verbatim rejection message for a scheduling-required child invoked per row.
- * Shared by the static preflight (`plays check`/publish gate) and the runtime
- * launch guard so a dynamically-named child fails with the EXACT same text as a
- * statically-provable one. See ADR 0013.
- */
-export function inlineChildScheduledInRowMessage(
-  childPlayName: string,
-  rowContextField: string,
-): string {
-  return (
-    `ctx.runPlay("${childPlayName}") runs per row in the "${rowContextField}" batch, ` +
-    'but it is a scheduling-required child (it uses ctx.dataset()/ctx.csv(), waits on an ' +
-    'event, sets an explicit timeout, or explicitly requests a child workflow). Row-scoped children must be scalar. ' +
-    'Give the batch ONE dataset child at play level instead of fanning a scheduled run out per row.'
-  );
+  const steps = flattenStaticPipeline(input.pipeline);
+  if (
+    input.pipeline.tableNamespace ||
+    input.pipeline.sheetContract ||
+    steps.some((step) => step.type === 'dataset' || step.type === 'csv')
+  ) {
+    throw new Error(
+      ctxRunPlayInlineOnlyMessage(childPlayName, 'dataset_child'),
+    );
+  }
+  if (
+    steps.some(
+      (step) =>
+        step.type === 'tool' &&
+        (step.isEventWait || step.toolId === 'test_wait_for_event'),
+    )
+  ) {
+    throw new Error(
+      ctxRunPlayInlineOnlyMessage(childPlayName, 'event_wait_child'),
+    );
+  }
+  return {
+    strategy: 'inline',
+    reason: input.execution === 'inline' ? 'explicit_inline' : 'scalar_child',
+  };
 }