deepline 0.3.88 → 0.3.90

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

@@ -95,11 +95,26 @@ export type AsyncOperationContractWire = {
    * status. This rule applies only to that launch response; unknown poll
    * responses still use terminal.defaultOutcome.
    */
-  launch?: { unclassifiedJobOutcome: 'running' };
+  launch?: {
+    unclassifiedJobOutcome: 'running';
+    /** Ask this start action for its handle instead of its legacy sync result. */
+    preferAsync?: boolean;
+  };
   job: { idPaths: readonly string[] };
   polling: {
     initialDelayMs: number;
     intervalMs: number;
+    /**
+     * The longest one provider status/result read may wait when the caller
+     * owns the lifecycle. This is deliberately separate from the complete
+     * job timeout: a Play fan-out must release its transport slot promptly
+     * and let the next invocation perform the next check.
+     *
+     * Provider adapters translate this generic budget into their native
+     * long-poll parameter when they have one. Omit it when a poll endpoint
+     * already returns immediately.
+     */
+    checkTimeoutMs?: number;
     /** Optional public start-input field that overrides intervalMs for this call. */
     intervalInputField?: string;
     backoffMultiplier?: number;
@@ -128,6 +143,14 @@ export type AsyncOperationContractWire = {
 };
 
 export type AsyncOperationContract = AsyncOperationContractWire;
+/**
+ * Runtime projection for one lifecycle companion action. This is the single
+ * cadence fact a provider adapter receives; it does not expose a provider
+ * handle or make a result receipt into provider-job state.
+ */
+export type AsyncOperationPollExecution = {
+  checkTimeoutMs: number;
+};
 export type AsyncActionFlowCompatibilityProjection = {
   pollActions: readonly string[];
   finishAction?: string;
@@ -261,6 +284,12 @@ export function defineAsyncOperation(
   nonNegativeInteger(contract.polling.initialDelayMs, 'polling.initialDelayMs');
   positiveInteger(contract.polling.intervalMs, 'polling.intervalMs');
   positiveInteger(contract.polling.timeoutMs, 'polling.timeoutMs');
+  if (contract.polling.checkTimeoutMs !== undefined) {
+    positiveInteger(
+      contract.polling.checkTimeoutMs,
+      'polling.checkTimeoutMs',
+    );
+  }
   if (contract.polling.intervalInputField !== undefined) {
     required(contract.polling.intervalInputField, 'polling.intervalInputField');
   }
@@ -406,6 +435,17 @@ export function defineCallerManagedAsyncOperation(input: {
   pollActions: readonly string[];
   finishAction?: string;
   jobIdPaths?: readonly string[];
+  /**
+   * The provider has an explicit asynchronous launch path. A Play will receive
+   * its job handle immediately and own subsequent polling.
+   */
+  preferAsyncStart?: boolean;
+  /**
+   * Bound one provider-side status/result check for Plays. The default keeps
+   * large fan-outs nonblocking while direct SDK and CLI calls retain their
+   * provider-specific behavior.
+   */
+  checkTimeoutMs?: number;
   /**
    * Preserve an existing public asyncGetAction, or pass null when the legacy
    * action exposed only asyncFlow metadata.
@@ -431,6 +471,14 @@ export function defineCallerManagedAsyncOperation(input: {
         ? { finishAction: companion(input.finishAction) }
         : {}),
     },
+    ...(input.preferAsyncStart
+      ? {
+          launch: {
+            unclassifiedJobOutcome: 'running' as const,
+            preferAsync: true,
+          },
+        }
+      : {}),
     job: {
       idPaths: input.jobIdPaths ?? [
         'job_id',
@@ -446,6 +494,7 @@ export function defineCallerManagedAsyncOperation(input: {
     polling: {
       initialDelayMs: 0,
       intervalMs: 1_000,
+      checkTimeoutMs: input.checkTimeoutMs ?? 1_000,
       timeoutMs: 15 * 60_000,
     },
     terminal: {
@@ -462,6 +511,22 @@ export function defineCallerManagedAsyncOperation(input: {
   });
 }
 
+/**
+ * Project the generic caller-managed cadence onto each polling companion.
+ * `always` and `input_flag` operations execute their complete lifecycle at
+ * the API boundary, so exposing a bounded companion policy for them would be
+ * misleading.
+ */
+export function projectAsyncOperationPollExecution(
+  contract: AsyncOperationContractWire,
+): AsyncOperationPollExecution | null {
+  if (contract.wait.kind !== 'caller_managed') return null;
+  return {
+    checkTimeoutMs:
+      contract.polling.checkTimeoutMs ?? contract.polling.intervalMs,
+  };
+}
+
 export function asyncOperationCompanionActions(
   contract: AsyncOperationContract,
 ): string[] {

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

@@ -0,0 +1,77 @@
+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/bounceban-batching.ts

@@ -0,0 +1,137 @@
+import {
+  defineBatchStrategyMap,
+  type BatchOperationStrategy,
+} from './batching-types';
+
+type Single = {
+  email: string;
+  mode?: 'regular' | 'deepverify';
+  disable_catchall_verify?: '0' | '1';
+  url?: string;
+};
+type Bulk = Omit<Single, 'email'> & { emails: string[] };
+type Verdict = Record<string, unknown> & { email: string; status?: string };
+type Results = { items?: Verdict[]; data?: { items?: Verdict[] } };
+
+function options(payload: Single) {
+  return {
+    mode: payload.mode ?? 'regular',
+    disable_catchall_verify: payload.disable_catchall_verify ?? '0',
+  };
+}
+function bucket(payload: Single) {
+  // Single and bulk webhook payloads differ. Do not batch webhook callers.
+  return JSON.stringify([options(payload), payload.url ?? null]);
+}
+function emailKey(email: string) {
+  return email.trim().toLowerCase();
+}
+
+export const bouncebanVerifyBatchStrategy: BatchOperationStrategy<
+  Single,
+  Bulk | Single,
+  Results,
+  { data: Verdict }
+> = {
+  sourceOperation: 'bounceban_verify_single',
+  batchOperation: 'bounceban_verify_bulk',
+  kind: 'async_dataset_job',
+  // The async finish action retrieves at most 100 emails per request.
+  maxBatchSize: 100,
+  bucketKeyPayloadFields: ['mode', 'disable_catchall_verify', 'url'],
+  canBatchWith(left, right) {
+    return !left.url && !right.url && bucket(left) === bucket(right);
+  },
+  toBucketKey: bucket,
+  toItemKey: (payload) => emailKey(payload.email),
+  compile(payloads) {
+    const first = payloads[0];
+    if (payloads.length === 1 && first) {
+      return {
+        batchOperation: 'bounceban_verify_single',
+        batchPayload: first,
+        items: [{ itemKey: emailKey(first.email), payload: first }],
+      };
+    }
+    if (
+      !first ||
+      payloads.length > 100 ||
+      payloads.some((p) => p.url || bucket(p) !== bucket(first))
+    ) {
+      throw new Error(
+        'BounceBan batch requires 1–100 emails with matching verification options and no webhooks.',
+      );
+    }
+    return {
+      batchOperation: 'bounceban_verify_bulk',
+      batchPayload: {
+        emails: [...new Set(payloads.map((p) => emailKey(p.email)))],
+        ...options(first),
+      },
+      items: payloads.map((payload) => ({
+        itemKey: emailKey(payload.email),
+        payload,
+      })),
+    };
+  },
+  splitResult(fullResult, compiled) {
+    if (compiled.batchOperation === 'bounceban_verify_single') {
+      const row = (fullResult.data ?? fullResult) as Verdict;
+      if (
+        row.status !== 'success' ||
+        typeof row.email !== 'string' ||
+        emailKey(row.email) !== compiled.items[0]?.itemKey ||
+        !['deliverable', 'undeliverable', 'risky', 'unknown'].includes(
+          String(row.result),
+        )
+      ) {
+        throw new Error(
+          'BounceBan single verification returned an unfinished or malformed verdict.',
+        );
+      }
+      return [
+        {
+          itemKey: compiled.items[0]!.itemKey,
+          result: { data: row },
+          rawResult: row,
+        },
+      ];
+    }
+    const rows = fullResult.items ?? fullResult.data?.items;
+    if (!Array.isArray(rows))
+      throw new Error('BounceBan bulk verification returned no result list.');
+    const byEmail = new Map<string, Verdict>();
+    for (const row of rows) {
+      if (
+        !row ||
+        typeof row.email !== 'string' ||
+        (row.status !== undefined && row.status !== 'success') ||
+        !['deliverable', 'undeliverable', 'risky', 'unknown'].includes(
+          String(row.result),
+        )
+      ) {
+        throw new Error(
+          'BounceBan bulk verification returned an unfinished or malformed verdict.',
+        );
+      }
+      const key = emailKey(row.email);
+      if (byEmail.has(key))
+        throw new Error(
+          'BounceBan bulk verification returned duplicate verdicts.',
+        );
+      byEmail.set(key, row);
+    }
+    return compiled.items.map((item) => {
+      const row = byEmail.get(item.itemKey);
+      if (!row)
+        throw new Error(
+          `BounceBan bulk verification omitted a requested email result.`,
+        );
+      return { itemKey: item.itemKey, result: { data: row }, rawResult: row };
+    });
+  },
+};
+
+export const bouncebanBatchStrategies = defineBatchStrategyMap({
+  bounceban_verify_single: bouncebanVerifyBatchStrategy,
+});

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;
+}