deepline 0.0.1 → 0.1.1

package/dist/repo/shared_libs/play-runtime/coordinator-headers.ts

@@ -0,0 +1,78 @@
+/**
+ * HTTP headers attached to every server-to-coordinator request.
+ *
+ * The coordinator is a Cloudflare Worker (`deepline-play-coordinator-*`) that
+ * we publish through Cloudflare's Versions + Deployments primitives. Whenever
+ * a deployment is split across two versions (e.g. 10% canary), Cloudflare
+ * uses the `Cloudflare-Workers-Version-Key` header to pick a stable version
+ * per request. Sending the runId as the key keeps every request for one play
+ * run pinned to whichever version started the run, so a partial rollout
+ * cannot strand a Workflow's `/submit` and `/result` calls on different
+ * code versions.
+ *
+ * The header is harmless when there is only one active version (the default).
+ */
+export const COORDINATOR_VERSION_KEY_HEADER = 'Cloudflare-Workers-Version-Key';
+/**
+ * Shared secret the coordinator uses to authenticate dispatcher (Vercel app)
+ * traffic. The coordinator also sanity-checks `x-deepline-run-scope` matches
+ * the run id encoded in the URL path on cancel/signal so a leaked token
+ * cannot be retargeted to arbitrary runs.
+ */
+export const COORDINATOR_INTERNAL_TOKEN_HEADER = 'x-deepline-internal-token';
+export const COORDINATOR_RUN_SCOPE_HEADER = 'x-deepline-run-scope';
+export const COORDINATOR_URL_OVERRIDE_HEADER = 'x-deepline-coordinator-url';
+export const WORKER_CALLBACK_URL_OVERRIDE_HEADER =
+  'x-deepline-worker-callback-url';
+
+let warnedAboutMissingInternalToken = false;
+
+function resolveInternalCoordinatorToken(): string | null {
+  // Read lazily so the helper is safe to import in environments without
+  // env access (e.g. workerd build-time bundling).
+  const fromEnv =
+    (typeof process !== 'undefined' && process?.env?.DEEPLINE_INTERNAL_TOKEN?.trim()) ||
+    null;
+  if (fromEnv) return fromEnv;
+  if (!warnedAboutMissingInternalToken) {
+    warnedAboutMissingInternalToken = true;
+    // Dev convenience: log once. The coordinator may be running without the
+    // token enforced too, so this is not fatal — let the call proceed and
+    // surface any 401/403 from the coordinator instead of failing closed.
+    if (typeof console !== 'undefined') {
+      console.warn(
+        '[plays] DEEPLINE_INTERNAL_TOKEN unset; coordinator calls will fail if the coordinator is enforcing it.',
+      );
+    }
+  }
+  return null;
+}
+
+export function coordinatorRequestHeaders(input: {
+  runId: string;
+  contentType?: string | null;
+  /**
+   * When set, the coordinator validates this matches the runId in the URL.
+   * Pass the runId on `/cancel` / `/signal` calls so a leaked dispatcher
+   * token cannot be retargeted to a different run.
+   */
+  runScope?: string | null;
+}): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (input.contentType) {
+    headers['content-type'] = input.contentType;
+  }
+  const trimmed = input.runId.trim();
+  if (trimmed) {
+    headers[COORDINATOR_VERSION_KEY_HEADER] = trimmed;
+  }
+  const internalToken = resolveInternalCoordinatorToken();
+  if (internalToken) {
+    headers[COORDINATOR_INTERNAL_TOKEN_HEADER] = internalToken;
+  }
+  const scope = input.runScope?.trim() || trimmed;
+  if (scope) {
+    headers[COORDINATOR_RUN_SCOPE_HEADER] = scope;
+  }
+  return headers;
+}

package/dist/repo/shared_libs/play-runtime/ctx-contract.ts

@@ -0,0 +1,250 @@
+export interface BatchResult {
+  rowId: number;
+  rowKey?: string | null;
+  result: unknown | null;
+}
+
+export interface MapExecutionFrame {
+  mapInvocationId: string;
+  mapNodeId?: string | null;
+  logicalNamespace: string;
+  artifactTableNamespace: string;
+  status: 'running' | 'suspended' | 'completed' | 'failed';
+  totalRows: number;
+  completedRowKeys: string[];
+  pendingRowKeys: string[];
+  activeBoundaryId?: string | null;
+  startedAt: number;
+  updatedAt: number;
+}
+
+export interface PlayRowUpdate {
+  key: string;
+  rowId: number;
+  tableNamespace?: string | null;
+  status?: 'running' | 'completed' | 'failed';
+  stage?: string | null;
+  provider?: string | null;
+  error?: string | null;
+  dataPatch?: Record<string, unknown>;
+  cellMetaPatch?: Record<
+    string,
+    {
+      status:
+        | 'queued'
+        | 'running'
+        | 'completed'
+        | 'failed'
+        | 'cached'
+        | 'missed'
+        | 'skipped';
+      stage?: string | null;
+      provider?: string | null;
+      error?: string | null;
+      reused?: boolean;
+    }
+  >;
+}
+
+export type PlayExecutionEvent =
+  | {
+      type: 'map.preparing';
+      mapInvocationId: string;
+      mapNodeId?: string | null;
+      logicalNamespace: string;
+      artifactTableNamespace: string;
+      totalRows: number;
+      completedRows: number;
+      pendingRows: number;
+      at: number;
+    }
+  | {
+      type: 'map.started';
+      mapInvocationId: string;
+      mapNodeId?: string | null;
+      logicalNamespace: string;
+      artifactTableNamespace: string;
+      totalRows: number;
+      completedRows: number;
+      pendingRows: number;
+      at: number;
+    }
+  | {
+      type: 'map.progress';
+      mapInvocationId: string;
+      mapNodeId?: string | null;
+      logicalNamespace: string;
+      artifactTableNamespace: string;
+      completedRows: number;
+      failedRows: number;
+      totalRows?: number;
+      at: number;
+    }
+  | {
+      type: 'map.row.updated';
+      mapInvocationId: string;
+      mapNodeId?: string | null;
+      logicalNamespace: string;
+      artifactTableNamespace: string;
+      rowKey: string;
+      rowStatus?: PlayRowUpdate['status'];
+      fieldName?: string | null;
+      stage?: string | null;
+      provider?: string | null;
+      at: number;
+    }
+  | {
+      type: 'map.completed' | 'map.suspended' | 'map.resumed' | 'map.failed';
+      mapInvocationId: string;
+      mapNodeId?: string | null;
+      logicalNamespace: string;
+      artifactTableNamespace: string;
+      completedRows: number;
+      failedRows: number;
+      totalRows?: number;
+      at: number;
+    };
+
+export interface PlayCheckpoint {
+  completedBatches: Record<string, BatchResult[]>;
+  completedToolBatches: Record<
+    string,
+    Record<string, { done: true; result: unknown | null }>
+  >;
+  resolvedWaterfalls: Record<string, Record<string, unknown>>;
+  resolvedBoundaries?: Record<
+    string,
+    | {
+        kind: 'sleep';
+        delayMs: number;
+        completedAt?: number;
+        scope?: {
+          type: 'workflow' | 'map_row';
+          tableNamespace?: string;
+          rowKey?: string;
+          rowIndex?: number;
+          fieldName?: string;
+        };
+      }
+    | {
+        kind: 'integration_event';
+        eventKey: string;
+        timeoutMs: number;
+        provider?: string;
+        toolId?: string;
+        messageRef?: {
+          channel: string;
+          ts: string;
+        };
+        output?: unknown;
+        completedAt?: number;
+      }
+    | {
+        kind: 'fetch';
+        url: string;
+        method: string;
+        output?: unknown;
+        completedAt?: number;
+      }
+    | {
+        kind: 'step';
+        stepId: string;
+        output?: unknown;
+        completedAt?: number;
+      }
+  >;
+  mapFrames?: Record<string, MapExecutionFrame>;
+}
+
+export interface PlayStepRowResult {
+  rowId: number;
+  status: 'completed' | 'failed' | 'missed' | 'skipped';
+  success: boolean;
+  provider?: string;
+  value?: unknown;
+  error?: string | null;
+}
+
+export type PlayStep =
+  | { type: 'start'; trigger?: string; description?: string }
+  | { type: 'csv_load'; arg?: string; rows?: number; description?: string }
+  | {
+      type: 'map';
+      items: number;
+      fields?: string[];
+      substeps: PlayMapSubstep[];
+      description?: string;
+    }
+  | {
+      type: 'waterfall';
+      tool?: string;
+      providers?: string[];
+      id?: string;
+      output?: string;
+      minResults?: number;
+      steps?: Array<{
+        id: string;
+        kind?: 'tool' | 'code';
+        toolId?: string;
+        results: PlayStepRowResult[];
+      }>;
+      results: PlayStepRowResult[];
+      description?: string;
+    }
+  | {
+      type: 'tool';
+      toolId: string;
+      results: PlayStepRowResult[];
+      description?: string;
+    }
+  | {
+      type: 'play_call';
+      playId: string;
+      results?: PlayStepRowResult[];
+      nestedSteps: PlayStep[];
+      description?: string;
+    }
+  | {
+      type: 'run_javascript';
+      alias: string;
+      results: PlayStepRowResult[];
+      description?: string;
+    }
+  | { type: 'return'; outputRows: number; description?: string };
+
+export type PlayMapSubstep =
+  | {
+      type: 'waterfall';
+      tool?: string;
+      providers?: string[];
+      id?: string;
+      output?: string;
+      minResults?: number;
+      steps?: Array<{
+        id: string;
+        kind?: 'tool' | 'code';
+        toolId?: string;
+        results: PlayStepRowResult[];
+      }>;
+      results: PlayStepRowResult[];
+      description?: string;
+    }
+  | {
+      type: 'tool';
+      toolId: string;
+      results: PlayStepRowResult[];
+      description?: string;
+    }
+  | {
+      type: 'play_call';
+      playId: string;
+      results?: PlayStepRowResult[];
+      nestedSteps: PlayStep[];
+      description?: string;
+    }
+  | {
+      type: 'run_javascript';
+      alias: string;
+      results: PlayStepRowResult[];
+      description?: string;
+    };