deepline 0.3.87 → 0.3.89

package/dist/bundling-sources/shared_libs/play-runtime/async-play-invocation.ts

@@ -0,0 +1,78 @@
+import {
+  flattenStaticPipeline,
+  type PlayStaticPipeline,
+} from '../plays/static-pipeline';
+import { SHARED_EXECUTION_POLICY } from './governor/policy';
+
+export const CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED =
+  'CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED';
+export const CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED =
+  'CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED';
+export const CTX_RUN_PLAY_ASYNC_RECURSIVE = 'CTX_RUN_PLAY_ASYNC_RECURSIVE';
+export const CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED =
+  'CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED';
+export const MAX_ASYNC_PLAY_CALL_DEPTH =
+  SHARED_EXECUTION_POLICY.budgets.maxPlayCallDepth;
+
+/**
+ * Assert that one independently scheduled Play closure may be admitted.
+ *
+ * Async children may suspend for sleep/HITL, but never own a Dataset, CSV, or
+ * Runtime Sheet. The checker and runtime both call this function so the same
+ * authored target cannot pass publish and fail differently at execution.
+ */
+export function assertAsyncPlayInvocation(input: {
+  pipeline: PlayStaticPipeline | null | undefined;
+  childPlayName?: string | null;
+}): void {
+  const childPlayName = input.childPlayName?.trim() || 'child';
+  if (!input.pipeline) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_TARGET_UNRESOLVED}: ctx.runPlayAsync("${childPlayName}") requires a statically resolved published Play contract. Publish the target with the current Deepline CLI before launching it.`,
+    );
+  }
+
+  const steps = flattenStaticPipeline(input.pipeline);
+  if (
+    input.pipeline.tableNamespace ||
+    input.pipeline.sheetContract ||
+    steps.some((step) => step.type === 'dataset' || step.type === 'csv')
+  ) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_DATASET_UNSUPPORTED}: ctx.runPlayAsync("${childPlayName}") launches one independent scalar or HITL Play Run, but the target owns ctx.dataset(), ctx.csv(), or a Runtime Sheet. Keep batch work in its top-level Play or extract a scalar per-record child.`,
+    );
+  }
+
+}
+
+/** Admit a child against the persisted root-to-parent Play lineage. */
+export function admitAsyncPlayLineage(input: {
+  ancestryPlayIds: readonly string[];
+  childPlayName: string;
+}): Readonly<{ ancestryPlayIds: readonly string[]; callDepth: number }> {
+  const childPlayName = input.childPlayName.trim();
+  const ancestryPlayIds = input.ancestryPlayIds
+    .map((playId) => playId.trim())
+    .filter(Boolean);
+  if (ancestryPlayIds.includes(childPlayName)) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_RECURSIVE}: Recursive play graph detected: ${[
+        ...ancestryPlayIds,
+        childPlayName,
+      ].join(' -> ')}`,
+    );
+  }
+  // The lineage includes the root Play, while call depth counts child edges.
+  // Appending this child therefore makes its depth equal to the current
+  // lineage length: [root] -> child is depth 1, not depth 2.
+  const callDepth = ancestryPlayIds.length;
+  if (callDepth > MAX_ASYNC_PLAY_CALL_DEPTH) {
+    throw new Error(
+      `${CTX_RUN_PLAY_ASYNC_DEPTH_EXCEEDED}: Play-call depth exceeded (${callDepth}/${MAX_ASYNC_PLAY_CALL_DEPTH}).`,
+    );
+  }
+  return {
+    ancestryPlayIds: [...ancestryPlayIds, childPlayName],
+    callDepth,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/checkpoint-boundaries.ts

@@ -0,0 +1,70 @@
+/**
+ * Durable checkpoint boundary kinds — the one list every checkpoint reader
+ * narrows against.
+ *
+ * Compatibility contract (`docs/runtime-compatibility-contract.md`): a parked
+ * run's checkpoint is written by one build and read by a newer-or-same build.
+ * Adding a boundary KIND is therefore not an additive change: a build that does
+ * not know the kind falls through every `existing?.kind === '...'` narrow and
+ * silently re-arms the wait or re-executes the side effect the boundary already
+ * resolved. That is a duplicate durable wait or a duplicate external effect,
+ * with no trace of what happened.
+ *
+ * So an unknown kind FAILS LOUD here instead. Recovery is roll-forward: deploy a
+ * build that understands the kind, and the parked run resumes.
+ */
+import type { PlayCheckpoint } from './ctx-types';
+
+/** One entry of `PlayCheckpoint.resolvedBoundaries`. */
+export type PlayResolvedBoundary = NonNullable<
+  PlayCheckpoint['resolvedBoundaries']
+>[string];
+
+/** Every boundary kind this build can replay. */
+export const PLAY_RESOLVED_BOUNDARY_KINDS = [
+  'sleep',
+  'integration_event',
+  'fetch',
+  'step',
+] as const satisfies readonly PlayResolvedBoundary['kind'][];
+
+/**
+ * Compile fence in the other direction: adding a kind to `PlayCheckpoint`
+ * without listing it above resolves to `never` and fails the build, rather than
+ * shipping a kind that every reader would then reject at runtime.
+ */
+type UnlistedBoundaryKind = Exclude<
+  PlayResolvedBoundary['kind'],
+  (typeof PLAY_RESOLVED_BOUNDARY_KINDS)[number]
+>;
+const ALL_BOUNDARY_KINDS_LISTED: UnlistedBoundaryKind extends never
+  ? true
+  : never = true;
+void ALL_BOUNDARY_KINDS_LISTED;
+
+/**
+ * Return the checkpoint entry for `boundaryId`, or throw when it carries a kind
+ * this build cannot replay. Absent (`undefined`/`null`) stays absent — an
+ * unresolved boundary is normal and simply re-arms.
+ */
+export function assertKnownResolvedBoundary(
+  boundaryId: string,
+  entry: PlayResolvedBoundary | null | undefined,
+): PlayResolvedBoundary | undefined {
+  if (entry === null || entry === undefined) return undefined;
+  const kind = (entry as { kind?: unknown }).kind;
+  if (
+    typeof kind !== 'string' ||
+    !(PLAY_RESOLVED_BOUNDARY_KINDS as readonly string[]).includes(kind)
+  ) {
+    throw new Error(
+      `Play checkpoint boundary "${boundaryId}" is resolved with unknown kind ` +
+        `"${String(kind)}". This build only replays ` +
+        `${PLAY_RESOLVED_BOUNDARY_KINDS.join(', ')}. The checkpoint was written ` +
+        `by a newer runtime build; continuing would re-arm the wait or re-run ` +
+        `the effect this boundary already resolved. Roll forward to a build ` +
+        `that understands "${String(kind)}".`,
+    );
+  }
+  return entry;
+}