deepline 0.1.79 → 0.1.80

package/dist/repo/shared_libs/play-runtime/governor/policy.ts

@@ -0,0 +1,179 @@
+/**
+ * Play Execution Governor — the single policy table.
+ *
+ * This is the ONE source of truth for every concurrency, budget, and pacing
+ * number in the play runtime. Both runner Adapters (`cjs_node20` in-process and
+ * `esm_workers` cloud) resolve their limits from here, so the two substrates
+ * cannot drift. See ADR 0007 and the "Play Execution Governor" entry in
+ * CONTEXT.md.
+ *
+ * Tuning philosophy (product decision):
+ *  - Caps are GENEROUS and tuned for fast execution. They are runaway /
+ *    anti-starvation guards, NOT per-workload throttles. A legitimate large run
+ *    should never hit them.
+ *  - The real-time bounds on a run are (a) the wall-clock runtime cap and
+ *    (b) per-provider rate pacing. The counters below only stop pathological
+ *    recursion / fan-out.
+ *  - Every value is an EXPLICIT, finite cap. Nothing here is unbounded — there
+ *    is no `null`, no "off", no implicit infinity. Unaccounted resource use
+ *    must be impossible.
+ *
+ * The docs catalog (`src/lib/plays/limits-catalog.ts`) and its generated public
+ * + internal pages source their numbers from this table.
+ */
+
+/** Concurrency ceilings — how much may run at once. */
+export interface ExecutionConcurrencyPolicy {
+  /** Map rows resolving their fields concurrently when no `concurrency` is given. */
+  readonly rowDefault: number;
+  /** Hard ceiling for an explicit map `concurrency` value; larger is clamped. */
+  readonly rowMax: number;
+  /** Concurrently in-flight child plays (`ctx.runPlay`). Excess launches block. */
+  readonly childPlay: number;
+  /** Global backstop on concurrently in-flight tool calls across all providers. */
+  readonly toolCalls: number;
+}
+
+/**
+ * Per-run budgets — total attempts allowed before a run is treated as runaway.
+ * Accumulated down the dispatch lineage (a child seeds from the parent), so the
+ * budget is global across the nested-play tree, not per-worker.
+ */
+export interface ExecutionBudgetPolicy {
+  /** Max nesting depth of `ctx.runPlay` chains. Deeper is almost certainly a cycle. */
+  readonly maxPlayCallDepth: number;
+  /** Max total `ctx.runPlay` calls along a lineage. */
+  readonly maxPlayCallCount: number;
+  /** Max direct child plays one play may launch. */
+  readonly maxChildPlayCallsPerParent: number;
+  /** Max nested-play descendants created during a run. */
+  readonly maxDescendants: number;
+  /** Max total tool calls in a run. */
+  readonly maxToolCallCount: number;
+  /** Max total retries across all steps/tools. */
+  readonly maxRetryCount: number;
+  /** Max total waterfall-step executions in a run. */
+  readonly maxWaterfallStepExecutions: number;
+}
+
+/**
+ * Per-provider rate pacing — the real outbound throughput governor.
+ *
+ * SUBSTRATE NOTE: the per-provider request RATE (`requestsPerWindow`/`windowMs`
+ * from a provider's `PacingRule`s) is enforced on BOTH substrates. A rule's
+ * optional `maxConcurrency` (simultaneous-in-flight cap) is enforced only on
+ * `cjs_node20`; on `esm_workers` it is intentionally excluded from the pacing
+ * contract because a fanned-out run cannot guarantee the per-isolate release
+ * signal an in-flight count needs, so only the org-wide tool-concurrency
+ * backstop applies there. See PacingRule.maxConcurrency in rate-state-backend.ts.
+ */
+export interface ExecutionPacingPolicy {
+  /** RPS applied to a provider that declares no explicit rate limit. */
+  readonly defaultProviderRequestsPerSecond: number;
+  /** Parallelism the scheduler suggests before a provider's own hints tighten it. */
+  readonly suggestedMaxParallelism: number;
+}
+
+export interface ResolvedExecutionPolicy {
+  readonly concurrency: ExecutionConcurrencyPolicy;
+  readonly budgets: ExecutionBudgetPolicy;
+  readonly pacing: ExecutionPacingPolicy;
+}
+
+/**
+ * The shared default policy. Both substrates use this verbatim unless an entry
+ * in {@link ADAPTER_POLICY_OVERRIDES} forces a documented difference.
+ */
+export const SHARED_EXECUTION_POLICY: ResolvedExecutionPolicy = {
+  concurrency: {
+    // Map row concurrency is platform-controlled — customers cannot set it — so
+    // every map runs at the ceiling: high enough that per-provider pacing (not
+    // the row pool) is the bottleneck even for multi-step waterfall rows. Pure-JS
+    // maps use a separate fast path and are not bound by this. Kept == rowMax so
+    // the default and the cap are the same single platform value.
+    rowDefault: 2_000,
+    // Hard cap. Above this, more in-flight rows only park memory — outbound is
+    // already bounded by tool concurrency + per-provider pacing.
+    rowMax: 2_000,
+    // Concurrent child-play launches. Generous; each child is a real launch, so
+    // this is the one value most likely to need a documented esm_workers
+    // override if isolate pressure shows up in E2E.
+    childPlay: 32,
+    // Global all-provider backstop. Per-provider pacing is the real limit; this
+    // just stops a single run from opening an absurd number of sockets at once.
+    toolCalls: 256,
+  },
+  budgets: {
+    // Runaway guards, not workload limits. A 5,000-row map calling several tools
+    // per row is normal and must fit comfortably under these.
+    maxPlayCallDepth: 8,
+    maxPlayCallCount: 100_000,
+    maxChildPlayCallsPerParent: 100_000,
+    maxDescendants: 100_000,
+    maxToolCallCount: 5_000_000,
+    maxRetryCount: 100_000,
+    maxWaterfallStepExecutions: 5_000_000,
+  },
+  pacing: {
+    // Undeclared providers; declared providers (rate-limit-definitions.ts) win.
+    defaultProviderRequestsPerSecond: 30,
+    suggestedMaxParallelism: 50,
+  },
+};
+
+export type AdapterId = 'cjs_node20' | 'esm_workers';
+
+/**
+ * One level deep on purpose: each policy section is a flat record of numbers, so
+ * an override is `{ section: { key: value } }`. The merge in
+ * {@link resolveExecutionPolicy} is one level; this type matches it exactly so
+ * it can never advertise nested-override support the merge doesn't implement.
+ */
+type PolicyOverride = {
+  [S in keyof ResolvedExecutionPolicy]?: Partial<ResolvedExecutionPolicy[S]>;
+};
+
+/**
+ * The ONLY sanctioned per-substrate divergence. Empty by design — both
+ * substrates run the shared policy. Every entry added here MUST carry a
+ * one-line comment citing the substrate constraint that forces it (e.g. isolate
+ * CPU/memory). CI may assert this map stays small. This is the anti-drift seam:
+ * differences are explicit and justified, never accidental.
+ */
+export const ADAPTER_POLICY_OVERRIDES: Record<AdapterId, PolicyOverride> = {
+  cjs_node20: {},
+  esm_workers: {},
+};
+
+/** Merge the shared policy with any documented Adapter override. */
+export function resolveExecutionPolicy(
+  adapter: AdapterId,
+): ResolvedExecutionPolicy {
+  const override = ADAPTER_POLICY_OVERRIDES[adapter];
+  return {
+    concurrency: {
+      ...SHARED_EXECUTION_POLICY.concurrency,
+      ...override.concurrency,
+    },
+    budgets: { ...SHARED_EXECUTION_POLICY.budgets, ...override.budgets },
+    pacing: { ...SHARED_EXECUTION_POLICY.pacing, ...override.pacing },
+  };
+}
+
+/**
+ * Effective row concurrency for a map: an explicit positive request clamped to
+ * `[1, rowMax]`, otherwise the default. Single helper, used by both substrates.
+ */
+export function resolveRowConcurrency(
+  policy: ResolvedExecutionPolicy,
+  requested?: number,
+): number {
+  if (
+    typeof requested === 'number' &&
+    Number.isFinite(requested) &&
+    requested > 0
+  ) {
+    return Math.min(Math.floor(requested), policy.concurrency.rowMax);
+  }
+  return policy.concurrency.rowDefault;
+}

package/dist/repo/shared_libs/play-runtime/governor/rate-state-backend.ts

@@ -0,0 +1,87 @@
+/**
+ * Rate State Backend — the one swappable seam of the Play Execution Governor.
+ *
+ * Per-`(org, provider)` rate windows are the only execution state that cannot be
+ * process-local: on `esm_workers` a run fans child plays across isolates, so the
+ * window must be shared. Everything else the Governor owns (budgets, concurrency
+ * slots) stays Governor-local and threads down the lineage via the snapshot.
+ *
+ * Adapters: an in-memory backend for the single-process `cjs_node20` runner, and
+ * a shared backend (Run Coordination Cache Durable Object, or server-side Redis)
+ * for `esm_workers`. See ADR 0007 and CONTEXT.md (Rate State Backend).
+ */
+
+/** A single resolved rate rule for a bucket (from rate-limit-definitions). */
+export interface PacingRule {
+  readonly ruleId: string;
+  readonly requestsPerWindow: number;
+  readonly windowMs: number;
+  /**
+   * Optional simultaneous-in-flight cap for this rule.
+   *
+   * SUBSTRATE NOTE: `maxConcurrency` is enforced ONLY on `cjs_node20` (the
+   * single-process {@link RateStateBackend} can hold a reliable in-flight count
+   * and release it on permit.release). On `esm_workers` it is intentionally NOT
+   * enforced: a run fans across V8 isolates and a dying isolate cannot guarantee
+   * the release signal a leased in-flight count would require, so the
+   * coordinator DO debits `requestsPerWindow` only. The Governor's global
+   * tool-concurrency semaphore is the cross-isolate in-flight backstop there.
+   * `requestsPerWindow`/`windowMs` (the request-RATE governor) ARE enforced on
+   * both substrates. See coordinator-rate-state-backend.ts and dedup-do.ts
+   * (computeRateAcquire) for the workers side.
+   */
+  readonly maxConcurrency: number | null;
+}
+
+/**
+ * Per-tool queue-hint metadata produced by the runtime tool catalog
+ * (`src/lib/plays/runtime-tool-metadata.ts`) and surfaced to the runtime via
+ * `ContextOptions.getToolQueueHints`. It is the raw provider rate-limit metadata
+ * that the runtime maps into one {@link PacingRule} per hint before handing it
+ * to the Governor's pacing resolver. The `provider` field identifies the pacing
+ * bucket; `bucketId`/`operation` are descriptive and used for logging/grouping.
+ */
+export interface PlayQueueHint {
+  bucketId: string;
+  provider: string;
+  operation: string;
+  ruleId: string;
+  requestsPerWindow: number;
+  windowMs: number;
+  maxConcurrency: number | null;
+}
+
+/** Handle returned by acquire(); release frees any concurrency held by the rules. */
+export interface PacingPermit {
+  release(): void;
+}
+
+export interface RateStateBackend {
+  /**
+   * Block until one outbound call is permitted for `bucketId` under all `rules`
+   * (request windows always; per-rule `maxConcurrency` only on the in-memory
+   * `cjs_node20` backend — see {@link PacingRule.maxConcurrency}), then debit and
+   * return a permit. `bucketId` is `${orgId}:${provider}` so the window is global
+   * per (org, provider). Resolves immediately when `rules` is empty (provider has
+   * no configured limit — pacing is a no-op, the global tool-concurrency backstop
+   * still applies).
+   */
+  acquire(input: {
+    bucketId: string;
+    rules: readonly PacingRule[];
+    signal?: AbortSignal;
+  }): Promise<PacingPermit>;
+
+  /**
+   * Feed a server-observed Retry-After back so future acquires for this bucket
+   * back off. Advisory and idempotent; never un-charges an in-flight call.
+   */
+  penalize(input: { bucketId: string; cooldownMs: number }): void;
+}
+
+const NOOP_PERMIT: PacingPermit = { release() {} };
+
+/** Permit used when a bucket has no rules — nothing to debit or release. */
+export function noopPacingPermit(): PacingPermit {
+  return NOOP_PERMIT;
+}

package/dist/repo/shared_libs/play-runtime/run-failure.ts

@@ -38,6 +38,18 @@ export function normalizePlayRunFailure(error: unknown): PlayRunFailureDetails {
       cause: CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR,
     };
   }
+  const playDepthBudgetMatch = cause.match(
+    /Play execution playDepth budget exceeded \((\d+)\/(\d+)\)\./,
+  );
+  if (playDepthBudgetMatch) {
+    return {
+      code: 'PLAY_CALL_DEPTH_EXCEEDED',
+      phase: 'runtime',
+      message: `Play-call depth exceeded (${playDepthBudgetMatch[1]}/${playDepthBudgetMatch[2]}).`,
+      retryable: false,
+      cause,
+    };
+  }
   return {
     code: 'RUN_FAILED',
     phase: 'runtime',

package/dist/repo/shared_libs/play-runtime/scheduler-backend.ts

@@ -35,6 +35,30 @@ export type PlayCallGovernanceSnapshot = {
   key: string;
   ancestryPlayIds: string[];
   callDepth: number;
+  /**
+   * Cumulative lineage-global budget counters consumed by ancestors at the
+   * moment this child was launched. The child seeds its own counters from these
+   * so the corresponding budgets (`maxPlayCallCount`, `maxToolCallCount`,
+   * `maxRetryCount`, `maxDescendants`, `maxWaterfallStepExecutions`) accumulate
+   * down the dispatch lineage instead of resetting to 0 in each worker isolate —
+   * matching the cjs forkChild path, which threads all of them. The Governor
+   * documents these budgets as global across the nested-play tree, not
+   * per-worker (see policy.ts / rate-state-backend.ts); threading them here is
+   * what makes that true on `esm_workers`.
+   *
+   * `descendantCount` is load-bearing for fan-out: forkChild charges
+   * `descendant` on every child launch, so without threading it a deep/wide tree
+   * would reset descendant accounting at each isolate and never converge on the
+   * lineage-global cap.
+   *
+   * All optional and fail-safe: if absent (older callers / dropped in transit)
+   * the child falls back to 0, i.e. prior behavior.
+   */
+  playCallCount?: number;
+  toolCallCount?: number;
+  retryCount?: number;
+  descendantCount?: number;
+  waterfallStepExecutions?: number;
 };
 
 export type PlaySchedulerSubmitInput = {

package/dist/repo/shared_libs/play-runtime/submit-limits.ts

@@ -0,0 +1,35 @@
+/**
+ * Single source of truth for play submit-path size/wait limits.
+ *
+ * Dependency-free leaf shared by the Next.js run route
+ * (`POST /api/v2/plays/run`), the Cloudflare coordinator's workflow retry-state
+ * codec, and the limits documentation generator. These bound what a single
+ * submission may carry inline, the hard ceiling on submitted input, and how
+ * long the API will block for a synchronous result.
+ */
+
+/**
+ * Max size of a CSV/file input that may be inlined into the submit payload
+ * (and the workflow event history). Larger inputs must be staged via
+ * `POST /api/v2/plays/files/stage` and referenced by handle.
+ */
+export const MAX_TEMPORAL_INLINE_INPUT_FILE_BYTES = 64 * 1024;
+
+/**
+ * Max time the run route will block waiting for a play to finish before
+ * returning a pending handle the caller can poll/stream.
+ */
+export const MAX_WAIT_FOR_COMPLETION_MS = 15_000;
+
+/**
+ * Submitted input/retry-state at or below this size stays inline in the
+ * coordinator Durable Object. Above it, the params are externalized to a
+ * short-lived play artifact (up to {@link PLAY_SUBMIT_INPUT_MAX_BYTES}).
+ */
+export const PLAY_SUBMIT_INPUT_INLINE_MAX_BYTES = 100_000;
+
+/**
+ * Absolute ceiling for submitted input/retry-state. A submission larger than
+ * this is rejected with guidance to use staged files or `ctx.csv` inputs.
+ */
+export const PLAY_SUBMIT_INPUT_MAX_BYTES = 1024 * 1024;

package/dist/repo/shared_libs/plays/bundling/index.ts

@@ -26,20 +26,12 @@ import type {
 } from '../artifact-types';
 import { buildPlayContractCompatibility } from '../contracts';
 import { validatePlaySourceFilesHaveNoInlineSecrets } from '../secret-guardrails';
+import {
+  MAX_ESM_WORKERS_BUNDLE_BYTES,
+  MAX_PLAY_BUNDLE_BYTES,
+} from './limits';
 
 const PLAY_BUNDLE_CACHE_VERSION = 24;
-const MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
-// workerd local-mode (`wrangler dev` Worker Loader) silently fails to
-// instantiate per-graphHash play Workers when the bundled code passes a
-// threshold somewhere between 1.04 MiB (44-package-imports — works) and
-// 1.18 MiB (the same play with date-fns added — hangs forever). The
-// workflow body never runs, no error is logged anywhere, and the run
-// hangs indefinitely. We surface this as a hard bundle failure so the
-// user gets an actionable message at submit time instead of a 5-minute
-// silent timeout. Real CF (workers.dev) accepts much larger bundles, but
-// `dev:v2 cloudflare` is the regression entrypoint so the local limit is
-// the binding one.
-const MAX_ESM_WORKERS_BUNDLE_BYTES = 1_150_000;
 const PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,

package/dist/repo/shared_libs/plays/bundling/limits.ts

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for play bundle/compile size limits.
+ *
+ * Kept in a dependency-free leaf module (no esbuild, no Node-only imports) so
+ * both the bundler (`./index.ts`) and the limits documentation generator
+ * (`scripts/generate-limits-docs.ts`) can import the numbers without pulling in
+ * the compile toolchain. Do not restate these values in docs — the public page
+ * is generated from here.
+ */
+
+/**
+ * Absolute hard ceiling for a compiled play bundle, across every artifact kind.
+ * A bundle larger than this is rejected at submit time.
+ */
+export const MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
+
+/**
+ * Tighter ceiling for the `esm_workers` artifact kind. workerd local-mode
+ * (`wrangler dev` Worker Loader) silently fails to instantiate per-graphHash
+ * play Workers when the bundled code passes a threshold somewhere between
+ * 1.04 MiB (44-package-imports — works) and 1.18 MiB (the same play with
+ * date-fns added — hangs forever). The workflow body never runs, no error is
+ * logged anywhere, and the run hangs indefinitely. We surface this as a hard
+ * bundle failure so the user gets an actionable message at submit time instead
+ * of a 5-minute silent timeout. Real CF (workers.dev) accepts much larger
+ * bundles, but `dev:v2 cloudflare` is the regression entrypoint so the local
+ * limit is the binding one.
+ */
+export const MAX_ESM_WORKERS_BUNDLE_BYTES = 1_150_000;

package/dist/repo/shared_libs/plays/static-pipeline.ts

@@ -1,5 +1,16 @@
 import { normalizeTableNamespace } from './row-identity';
 
+/**
+ * A top-level key the play's function literally `return`s. Derived from the
+ * `return { ... }` object literal — NOT from dataset `.withColumn(...)` names —
+ * so the "Returns" graph node mirrors the function's real output shape.
+ * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
+ */
+export interface PlayStaticReturnField {
+  name: string;
+  isDataset: boolean;
+}
+
 export interface PlayStaticPipeline {
   tableNamespace?: string;
   inputFields?: string[];
@@ -9,6 +20,12 @@ export interface PlayStaticPipeline {
   csvDescription?: string;
   datasetDescription?: string;
   fields: string[];
+  /**
+   * Top-level keys of the play's `return { ... }` object literal, in source
+   * order. Undefined when the terminal return isn't a statically-known object
+   * literal (bare value, dataset handle, conditional returns, etc.).
+   */
+  returnFields?: PlayStaticReturnField[];
   stages?: PlayStaticSubstep[];
   substeps: PlayStaticSubstep[];
   sheetContract?: PlaySheetContract | null;
@@ -54,6 +71,7 @@ export interface PlayStaticColumnProducer {
   field: string;
   toolId?: string;
   playId?: string;
+  staleAfterSeconds?: number;
   conditional?: boolean;
   sourceRange?: PlayStaticSourceRange;
   steps?: PlayStaticColumnProducer[];
@@ -64,6 +82,7 @@ export interface PlayStaticDatasetColumn {
   id: string;
   source: PlaySheetColumnSource;
   sqlName?: string;
+  staleAfterSeconds?: number;
   producers: PlayStaticColumnProducer[];
 }
 
@@ -212,6 +231,9 @@ export function truncateStaticPipelineForStorage(
       ? [...pipeline.rowKeyFields]
       : undefined,
     fields: [...(pipeline.fields ?? [])],
+    returnFields: pipeline.returnFields
+      ? pipeline.returnFields.map((field) => ({ ...field }))
+      : undefined,
     stages: truncateStaticSubstepsForStorage(pipeline.stages, {
       embeddedPlayCallPipelineDepth,
       maxEmbeddedPlayCallPipelineDepth,
@@ -237,6 +259,7 @@ export interface PlayStaticSourceRange {
 
 type PlayStaticSubstepMetadata = {
   conditional?: boolean;
+  staleAfterSeconds?: number;
 };
 
 export type PlayStaticSubstep = PlayStaticSubstepMetadata &
@@ -433,7 +456,7 @@ export function compileStaticGraph(
     if (substep.type !== 'dataset') {
       return substep;
     }
-    const columns = compileDatasetColumns(substep);
+    const columns = compileDatasetColumns(substep, pipeline?.substeps ?? []);
     const tableNamespace = (substep.tableNamespace ?? substep.field).trim();
     if (tableNamespace) {
       datasets.push({ tableNamespace, columns });
@@ -448,6 +471,7 @@ export function compileStaticGraph(
 
 function compileDatasetColumns(
   dataset: Extract<PlayStaticSubstep, { type: 'dataset' }>,
+  pipelineSubsteps: PlayStaticSubstep[] = [],
 ): PlayStaticDatasetColumn[] {
   const columnsById = new Map<string, PlayStaticDatasetColumn>();
   const ensureColumn = (
@@ -482,7 +506,15 @@ function compileDatasetColumns(
     ensureColumn(field, 'datasetColumn', sqlSafePlayColumnName(field));
   }
 
-  for (const substep of dataset.steps ?? []) {
+  const datasetProducerSteps =
+    dataset.steps && dataset.steps.length > 0
+      ? dataset.steps
+      : pipelineSubsteps.filter((substep) => {
+          const field = fieldForColumnProducer(substep);
+          return field ? (dataset.outputFields ?? []).includes(field) : false;
+        });
+
+  for (const substep of datasetProducerSteps) {
     const field = fieldForColumnProducer(substep);
     if (!field) continue;
     const column = ensureColumn(
@@ -491,7 +523,25 @@ function compileDatasetColumns(
       sqlSafePlayColumnName(field),
     );
     if (!column) continue;
-    column.producers.push(columnProducerFromSubstep(substep, field));
+    const pipelineSubstep =
+      substep.staleAfterSeconds === undefined
+        ? pipelineSubsteps.find(
+            (candidate) => fieldForColumnProducer(candidate) === field,
+          )
+        : undefined;
+    const producer = columnProducerFromSubstep(
+      pipelineSubstep && pipelineSubstep.staleAfterSeconds !== undefined
+        ? pipelineSubstep
+        : substep,
+      field,
+    );
+    column.producers.push(producer);
+    if (
+      column.staleAfterSeconds === undefined &&
+      producer.staleAfterSeconds !== undefined
+    ) {
+      column.staleAfterSeconds = producer.staleAfterSeconds;
+    }
   }
 
   return [...columnsById.values()];
@@ -536,6 +586,9 @@ function columnProducerFromSubstep(
     field,
     ...(substep.type === 'tool' ? { toolId: substep.toolId } : {}),
     ...(substep.type === 'play_call' ? { playId: substep.playId } : {}),
+    ...(substep.staleAfterSeconds !== undefined
+      ? { staleAfterSeconds: substep.staleAfterSeconds }
+      : {}),
     ...(substep.conditional ? { conditional: true } : {}),
     ...(substep.sourceRange ? { sourceRange: substep.sourceRange } : {}),
     ...(steps && steps.length > 0 ? { steps } : {}),

package/dist/repo/shared_libs/temporal/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared Temporal execution constants.
+ *
+ * Keep values that both the API/auth surface and the worker need here so the
+ * API never imports from worker-only modules.
+ */
+
+/**
+ * Local Temporal dev defaults.
+ *
+ * These match the host ports exposed by docker-compose.yml and the env files
+ * used by the local dev flows (`.env.local`, `.env.worktree`).
+ */
+export const LOCAL_TEMPORAL_FRONTEND_PORT = 17233;
+export const LOCAL_TEMPORAL_UI_PORT = 18233;
+export const LOCAL_TEMPORAL_NAMESPACE = 'default';
+export const LOCAL_TEMPORAL_ADDRESS = `127.0.0.1:${LOCAL_TEMPORAL_FRONTEND_PORT}`;
+export const LOCAL_TEMPORAL_UI_URL = `http://127.0.0.1:${LOCAL_TEMPORAL_UI_PORT}`;
+
+/** Maximum active user-code runtime for a standard play, in seconds. */
+export const STANDARD_PLAY_RUNTIME_LIMIT_SECONDS = 10 * 60; // 10 minutes
+
+/**
+ * Activity timeout includes cleanup/billing headroom after the 10 minute
+ * user-code runtime cap. Keep this higher than STANDARD_PLAY_RUNTIME_LIMIT_SECONDS.
+ */
+export const PLAY_ACTIVITY_TIMEOUT_SECONDS = 12 * 60; // 12 minutes
+
+/** Heartbeat cadence for the long-running play execution activity. */
+export const PLAY_EXECUTE_ACTIVITY_HEARTBEAT_INTERVAL_SECONDS = 15;
+
+/**
+ * TTL for workflow executor tokens, in seconds.
+ * Matches the activity timeout so tokens expire when the activity would
+ * time out anyway.
+ */
+export const WORKFLOW_EXECUTOR_TOKEN_TTL_SECONDS =
+  PLAY_ACTIVITY_TIMEOUT_SECONDS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.79",
+  "version": "0.1.80",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {