deepline 0.1.83 → 0.1.85

package/dist/repo/sdk/src/play.ts

@@ -81,6 +81,10 @@ import type {
   ToolExecuteResult,
   ToolResultMetadataInput,
 } from '../../shared_libs/play-runtime/tool-result-types.js';
+import type {
+  AuthoredStaleAfterSeconds,
+  PreviousCell,
+} from '../../shared_libs/play-runtime/cell-staleness.js';
 import type {
   DeeplineClientOptions,
   PlayDetail,
@@ -187,6 +191,22 @@ export type {
   ToolResultListAccessor,
   ToolResultTargetAccessor as ToolExtractedValue,
 } from '../../shared_libs/play-runtime/tool-result-types.js';
+export {
+  DEEPLINE_EXTRACTOR_TARGETS,
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
+  JOB_CHANGE_STATUS_VALUES,
+  PHONE_STATUS_VALUES,
+  isDeeplineExtractorTarget,
+} from '../../shared_libs/play-runtime/extractor-targets.js';
+export type {
+  DeeplineEmailStatusGetterValue,
+  DeeplineExtractorTarget,
+  DeeplineGetterValue,
+  DeeplineGetterValueMap,
+  JobChangeStatus,
+  PhoneStatus,
+} from '../../shared_libs/play-runtime/extractor-targets.js';
+export type { PreviousCell } from '../../shared_libs/play-runtime/cell-staleness.js';
 
 /**
  * Keyword-style request object for `ctx.tools.execute(...)`.
@@ -206,12 +226,35 @@ export type ToolExecutionRequest = {
   staleAfterSeconds?: number;
 };
 
+export type StaleAfterSeconds<Value = unknown> =
+  AuthoredStaleAfterSeconds<Value>;
+
 export type StepResolver<Row, Value> = (
   row: Row,
   ctx: DeeplinePlayRuntimeContext,
   index: number,
+  previousCell?: PreviousCell<Value>,
 ) => Value | Promise<Value>;
 
+export type DatasetColumnRunInput<Row, Value> = {
+  row: Row;
+  ctx: DeeplinePlayRuntimeContext;
+  index: number;
+  /**
+   * The prior stored value for this exact row+column when the runtime has
+   * decided the cell is due to run again. `previousCell.value` is the same type
+   * this column returns; metadata such as `completedAt` and `staleAt` lives
+   * beside it and is not mixed into the value.
+   */
+  previousCell?: PreviousCell<Value>;
+};
+
+export type DatasetColumnDefinition<Row, Value> = {
+  run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
+  readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+  readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
+};
+
 export type ConditionalStepResolver<Row, Value, Else = null> = {
   readonly kind: 'conditional';
   readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
@@ -222,9 +265,9 @@ export type ConditionalStepResolver<Row, Value, Else = null> = {
   ): ConditionalStepResolver<Row, Value, ValueElse>;
 };
 
-export type StepOptions<Row> = {
+export type StepOptions<Row, Value = unknown> = {
   readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
-  readonly staleAfterSeconds?: number;
+  readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 
 export type StepProgram<Input, Output, Return = Output> = {
@@ -242,7 +285,7 @@ export type StepProgram<Input, Output, Return = Output> = {
   step<Name extends string, Value>(
     name: Name,
     resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
-    options: StepOptions<Output>,
+    options: StepOptions<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
   return<Value>(
     resolver: StepResolver<Output, Value>,
@@ -258,7 +301,7 @@ export type StepProgramResolver<Input, Return> = {
 
 export type PlayStepProgramStep = {
   readonly name: string;
-  readonly staleAfterSeconds?: number;
+  readonly staleAfterSeconds?: StaleAfterSeconds;
   readonly resolver:
     | StepResolver<Record<string, unknown>, unknown>
     | ConditionalStepResolver<Record<string, unknown>, unknown>
@@ -294,12 +337,25 @@ export type DatasetBuilder<
     name: Name,
     resolver: ColumnResolver<OutputRow, Value>,
   ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+  withColumn<Name extends string, Value>(
+    name: Name,
+    definition: DatasetColumnDefinition<OutputRow, Value> & {
+      readonly runIf: (
+        row: OutputRow,
+        index: number,
+      ) => boolean | Promise<boolean>;
+    },
+  ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+  withColumn<Name extends string, Value>(
+    name: Name,
+    definition: DatasetColumnDefinition<OutputRow, Value>,
+  ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
   withColumn<Name extends string, Value>(
     name: Name,
     resolver:
       | StepResolver<OutputRow, Value>
       | StepProgramResolver<OutputRow, Value>,
-    options: StepOptions<OutputRow>,
+    options: StepOptions<OutputRow, Value>,
   ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
   withColumns<Program extends StepProgram<OutputRow, object, unknown>>(
     program: Program,

package/dist/repo/sdk/src/plays/harness-stub.ts

@@ -46,6 +46,7 @@ import type {
   WorkReceipt,
   WorkReceiptClaim,
 } from '../../../shared_libs/play-runtime/work-receipts';
+import type { CellStalenessPolicy } from '../../../shared_libs/play-runtime/cell-staleness';
 
 /**
  * Service-binding RPC stub shape — what `env.HARNESS` looks like inside
@@ -191,7 +192,7 @@ export async function harnessStartSheetDataset(input: {
   runId: string;
   inputOffset?: number;
   userEmail?: string | null;
-  cellPolicies?: Record<string, { staleAfterSeconds?: number }>;
+  cellPolicies?: Record<string, CellStalenessPolicy>;
 }): Promise<{
   inserted: number;
   skipped: number;

package/dist/repo/sdk/src/release.ts

@@ -50,10 +50,10 @@ export type SdkRelease = {
 };
 
 export const SDK_RELEASE = {
-  version: '0.1.83',
+  version: '0.1.85',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.83',
+    latest: '0.1.85',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

package/dist/repo/sdk/src/types.ts

@@ -505,6 +505,10 @@ export interface PlayRunListItem {
   closeTime: string | null;
   /** Duration string (e.g. `'2.5s'`). */
   executionTime: string | null;
+  /** Total Deepline credits charged for the run, when available. */
+  billingTotalCredits?: number;
+  /** Configured per-run Deepline credit cap, when available. */
+  billingMaxCreditsPerRun?: number | null;
   /** Metadata attached to the workflow. */
   memo: {
     /** Organization that owns this run. */

package/dist/repo/shared_libs/play-runtime/cell-staleness.ts

@@ -1,17 +1,43 @@
+export type StaleAfterSecondsResolver<Value = unknown> = (
+  value: Value,
+) => number | null;
+
+export type AuthoredStaleAfterSeconds<Value = unknown> =
+  | number
+  | StaleAfterSecondsResolver<Value>;
+
+export type AuthoredCellStalenessPolicy<Value = unknown> = {
+  staleAfterSeconds?: AuthoredStaleAfterSeconds<Value>;
+};
+
 export type CellStalenessPolicy = {
   staleAfterSeconds?: number;
+  dynamicStaleAfterSeconds?: boolean;
 };
 
 export type CellStalenessMeta = {
   status?: string | null;
   completedAt?: number | null;
+  staleAt?: number | null;
+  staleAfterSeconds?: number | null;
+};
+
+export type PreviousCell<Value = unknown> = {
+  value: Value;
+  completedAt?: number;
+  staleAt?: number | null;
+  staleAfterSeconds?: number;
 };
 
 export type CellStalenessDecision =
   | { action: 'recompute'; reason: 'missing' | 'failed' | 'stale' }
-  | { action: 'reuse'; reason: 'fresh' | 'no_policy' };
+  | { action: 'reuse'; reason: 'fresh' | 'no_policy' | 'no_expiry' };
 
 export type CellStalenessPolicyByField = Record<string, CellStalenessPolicy>;
+export type AuthoredCellStalenessPolicyByField = Record<
+  string,
+  AuthoredCellStalenessPolicy
+>;
 
 export const DEEPLINE_CELL_META_FIELD = '__deeplineCellMeta';
 
@@ -32,12 +58,83 @@ export function validateStaleAfterSeconds(
 }
 
 export function normalizeCellStalenessPolicy(
-  policy: CellStalenessPolicy | undefined,
+  policy: AuthoredCellStalenessPolicy | undefined,
 ): CellStalenessPolicy {
-  validateStaleAfterSeconds(policy?.staleAfterSeconds);
-  return policy?.staleAfterSeconds === undefined
-    ? {}
-    : { staleAfterSeconds: policy.staleAfterSeconds };
+  const staleAfterSeconds = policy?.staleAfterSeconds;
+  if (staleAfterSeconds === undefined) {
+    return {};
+  }
+  if (typeof staleAfterSeconds === 'function') {
+    return { dynamicStaleAfterSeconds: true };
+  }
+  validateStaleAfterSeconds(staleAfterSeconds);
+  return { staleAfterSeconds };
+}
+
+export function resolveCompletedCellStalenessMeta<Value>(input: {
+  policy?: AuthoredCellStalenessPolicy<Value>;
+  value: Value;
+  completedAt: number;
+}): Pick<CellStalenessMeta, 'staleAfterSeconds' | 'staleAt'> {
+  const staleAfterSeconds = input.policy?.staleAfterSeconds;
+  if (staleAfterSeconds === undefined) {
+    return {};
+  }
+
+  const resolved =
+    typeof staleAfterSeconds === 'function'
+      ? staleAfterSeconds(input.value)
+      : staleAfterSeconds;
+  if (resolved === null) {
+    return { staleAt: null };
+  }
+  if (typeof resolved !== 'number') {
+    throw new Error(
+      'staleAfterSeconds(value) must return a positive whole number of seconds or null.',
+    );
+  }
+  validateStaleAfterSeconds(resolved, 'staleAfterSeconds(value)');
+  return {
+    staleAfterSeconds: resolved,
+    staleAt: input.completedAt + resolved * 1000,
+  };
+}
+
+export function previousCellFromValue<Value>(input: {
+  hasValue: boolean;
+  value: Value;
+  meta?: CellStalenessMeta | null;
+}): PreviousCell<Value> | undefined {
+  if (!input.hasValue) {
+    return undefined;
+  }
+
+  const previous: PreviousCell<Value> = {
+    value: input.value,
+  };
+  if (
+    typeof input.meta?.completedAt === 'number' &&
+    Number.isFinite(input.meta.completedAt)
+  ) {
+    previous.completedAt = input.meta.completedAt;
+  }
+  if (
+    input.meta &&
+    Object.prototype.hasOwnProperty.call(input.meta, 'staleAt')
+  ) {
+    previous.staleAt =
+      typeof input.meta.staleAt === 'number' &&
+      Number.isFinite(input.meta.staleAt)
+        ? input.meta.staleAt
+        : null;
+  }
+  if (
+    typeof input.meta?.staleAfterSeconds === 'number' &&
+    Number.isFinite(input.meta.staleAfterSeconds)
+  ) {
+    previous.staleAfterSeconds = input.meta.staleAfterSeconds;
+  }
+  return previous;
 }
 
 export function shouldRecomputeCell(input: {
@@ -55,6 +152,23 @@ export function shouldRecomputeCell(input: {
     return { action: 'recompute', reason: 'failed' };
   }
 
+  const staleAt =
+    input.meta && Object.prototype.hasOwnProperty.call(input.meta, 'staleAt')
+      ? input.meta.staleAt
+      : undefined;
+  if (staleAt === null) {
+    return { action: 'reuse', reason: 'no_expiry' };
+  }
+  if (typeof staleAt === 'number' && Number.isFinite(staleAt)) {
+    return (input.nowMs ?? Date.now()) > staleAt
+      ? { action: 'recompute', reason: 'stale' }
+      : { action: 'reuse', reason: 'fresh' };
+  }
+
+  if (input.policy?.dynamicStaleAfterSeconds) {
+    return { action: 'recompute', reason: 'stale' };
+  }
+
   const staleAfterSeconds = input.policy?.staleAfterSeconds;
   validateStaleAfterSeconds(staleAfterSeconds);
   if (staleAfterSeconds === undefined) {
@@ -76,6 +190,37 @@ export function shouldRecomputeCell(input: {
     : { action: 'reuse', reason: 'fresh' };
 }
 
+export function resolveReusableCellMetaForCurrentPolicy<Value>(input: {
+  hasValue: boolean;
+  value: Value;
+  meta?: CellStalenessMeta | null;
+  policy?: AuthoredCellStalenessPolicy<Value>;
+}): Pick<CellStalenessMeta, 'staleAfterSeconds' | 'staleAt'> {
+  if (
+    !input.hasValue ||
+    typeof input.policy?.staleAfterSeconds !== 'function'
+  ) {
+    return {};
+  }
+  const status = String(input.meta?.status ?? '').trim();
+  if (status === 'failed') {
+    return {};
+  }
+  const completedAt =
+    typeof input.meta?.completedAt === 'number' &&
+    Number.isFinite(input.meta.completedAt)
+      ? input.meta.completedAt
+      : null;
+  if (completedAt === null) {
+    return {};
+  }
+  return resolveCompletedCellStalenessMeta({
+    policy: input.policy,
+    value: input.value,
+    completedAt,
+  });
+}
+
 export function cellPolicyFields(
   policies: CellStalenessPolicyByField | undefined,
 ): string[] {
@@ -83,6 +228,10 @@ export function cellPolicyFields(
     return [];
   }
   return Object.entries(policies)
-    .filter(([, policy]) => policy.staleAfterSeconds !== undefined)
+    .filter(
+      ([, policy]) =>
+        policy.staleAfterSeconds !== undefined ||
+        policy.dynamicStaleAfterSeconds === true,
+    )
     .map(([field]) => field);
 }

package/dist/repo/shared_libs/play-runtime/execution-plan.ts

@@ -1,5 +1,5 @@
 import {
-  getCompiledPipelineSubsteps,
+  flattenStaticPipeline,
   type PlayStaticPipeline,
   type PlayStaticSubstep,
 } from '../plays/static-pipeline';
@@ -189,7 +189,7 @@ function extractPlanMaps(
   pipeline: PlayStaticPipeline | null,
 ): ExecutionPlanMap[] {
   if (!pipeline) return [];
-  const substeps = getCompiledPipelineSubsteps(pipeline);
+  const substeps = flattenStaticPipeline(pipeline);
   const fallbackWaterfalls = substeps.filter(
     (substep): substep is Extract<PlayStaticSubstep, { type: 'waterfall' }> =>
       substep.type === 'waterfall',
@@ -252,7 +252,7 @@ function extractToolDeclarations(
   if (!pipeline) return [];
   const seen = new Set<string>();
   const declarations: ExecutionPlan['toolDeclarations'] = [];
-  for (const substep of getCompiledPipelineSubsteps(pipeline)) {
+  for (const substep of flattenStaticPipeline(pipeline)) {
     if (substep.type === 'tool') {
       const key = `${substep.toolId}:${substep.field}`;
       if (!seen.has(key)) {

package/dist/repo/shared_libs/play-runtime/extractor-targets.ts

@@ -0,0 +1,106 @@
+import type { EmailStatus, EmailStatusValue } from './email-status';
+
+export const JOB_CHANGE_STATUS_VALUES = [
+  'moved',
+  'no_change',
+  'left_company',
+  'unknown',
+  'profile_unavailable',
+  'no_new_company',
+] as const;
+
+export type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
+
+export type JobChangeGetterValue = {
+  status: JobChangeStatus;
+  date: string | null;
+  new_company: string | null;
+  new_title: string | null;
+};
+
+export const PHONE_STATUS_VALUES = ['valid', 'invalid', 'unknown'] as const;
+
+export type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
+
+export const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS = {
+  id: { identity: true, valueKind: 'string' },
+  name: { identity: true, valueKind: 'string' },
+  email: { identity: true, valueKind: 'string' },
+  personal_email: { identity: true, valueKind: 'string' },
+  phone: { identity: true, valueKind: 'string' },
+  linkedin: { identity: true, valueKind: 'string' },
+  linkedin_url: { identity: true, valueKind: 'string' },
+  domain: { identity: true, valueKind: 'string' },
+  website: { identity: true, valueKind: 'string' },
+  first_name: { identity: true, valueKind: 'string' },
+  last_name: { identity: true, valueKind: 'string' },
+  full_name: { identity: true, valueKind: 'string' },
+  company: { identity: true, valueKind: 'string' },
+  company_name: { identity: true, valueKind: 'string' },
+  organization_name: { identity: true, valueKind: 'string' },
+  company_domain: { identity: true, valueKind: 'string' },
+  company_website: { identity: true, valueKind: 'string' },
+  company_linkedin_url: { identity: true, valueKind: 'string' },
+  title: { identity: false, valueKind: 'string' },
+  industry: { identity: false, valueKind: 'string' },
+  status: { identity: false, valueKind: 'string' },
+  job_change: { identity: false, valueKind: 'job_change' },
+  job_change_status: {
+    identity: false,
+    valueKind: 'job_change_status',
+    enum: JOB_CHANGE_STATUS_VALUES,
+  },
+  email_status: { identity: false, valueKind: 'email_status' },
+  phone_status: {
+    identity: false,
+    valueKind: 'phone_status',
+    enum: PHONE_STATUS_VALUES,
+  },
+} as const;
+
+export type DeeplineExtractorTarget =
+  keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+
+export const DEEPLINE_EXTRACTOR_TARGETS = Object.keys(
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
+) as DeeplineExtractorTarget[];
+
+export type DeeplineEmailStatusGetterValue = EmailStatus | EmailStatusValue;
+
+export type DeeplineGetterValueMap = {
+  id: string;
+  name: string;
+  email: string;
+  personal_email: string;
+  phone: string;
+  linkedin: string;
+  linkedin_url: string;
+  domain: string;
+  website: string;
+  first_name: string;
+  last_name: string;
+  full_name: string;
+  company: string;
+  company_name: string;
+  organization_name: string;
+  company_domain: string;
+  company_website: string;
+  company_linkedin_url: string;
+  title: string;
+  industry: string;
+  status: string;
+  job_change: JobChangeGetterValue;
+  job_change_status: JobChangeStatus;
+  email_status: DeeplineEmailStatusGetterValue;
+  phone_status: PhoneStatus;
+};
+
+export type DeeplineGetterValue<
+  TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget,
+> = DeeplineGetterValueMap[TTarget];
+
+export function isDeeplineExtractorTarget(
+  value: string,
+): value is DeeplineExtractorTarget {
+  return value in DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+}

package/dist/repo/shared_libs/play-runtime/providers.ts

@@ -12,6 +12,9 @@ import {
 
 export const PLAY_RUNTIME_PROVIDER_IDS = {
   workersEdge: 'workers_edge',
+  postgresFast: 'postgres_fast',
+  postgresFastSandbox: 'postgres_fast_sandbox',
+  postgresFastWorkers: 'postgres_fast_workers',
   local: 'local',
 } as const;
 
@@ -39,6 +42,31 @@ export const PLAY_RUNTIME_PROVIDERS: Record<
     artifactKind: PLAY_ARTIFACT_KINDS.esmWorkers,
     label: 'Cloudflare Dynamic Workflows + Dynamic Workers + DO dedup',
   },
+  postgres_fast: {
+    id: PLAY_RUNTIME_PROVIDER_IDS.postgresFast,
+    scheduler: PLAY_SCHEDULER_BACKENDS.postgres,
+    runner: PLAY_RUNTIME_BACKENDS.daytona,
+    dedup: PLAY_DEDUP_BACKENDS.durableObject,
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
+    label: 'Experimental Postgres Scheduler + warm sandbox runner + DO dedup',
+  },
+  postgres_fast_sandbox: {
+    id: PLAY_RUNTIME_PROVIDER_IDS.postgresFastSandbox,
+    scheduler: PLAY_SCHEDULER_BACKENDS.postgres,
+    runner: PLAY_RUNTIME_BACKENDS.daytona,
+    dedup: PLAY_DEDUP_BACKENDS.durableObject,
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
+    label: 'Experimental Postgres Scheduler + warm sandbox runner + DO dedup',
+  },
+  postgres_fast_workers: {
+    id: PLAY_RUNTIME_PROVIDER_IDS.postgresFastWorkers,
+    scheduler: PLAY_SCHEDULER_BACKENDS.postgres,
+    runner: PLAY_RUNTIME_BACKENDS.cloudflareWorkers,
+    dedup: PLAY_DEDUP_BACKENDS.durableObject,
+    artifactKind: PLAY_ARTIFACT_KINDS.esmWorkers,
+    label:
+      'Experimental Postgres Scheduler + Queue/DO-woken Workers + DO dedup',
+  },
   local: {
     id: PLAY_RUNTIME_PROVIDER_IDS.local,
     scheduler: PLAY_SCHEDULER_BACKENDS.temporal,

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

@@ -22,6 +22,7 @@ import type { PreloadedRuntimeDbSession } from './db-session';
 export const PLAY_SCHEDULER_BACKENDS = {
   temporal: 'temporal',
   cfWorkflows: 'cf-workflows',
+  postgres: 'postgres',
   inProcess: 'in-process',
 } as const;
 
@@ -65,6 +66,7 @@ export type PlaySchedulerSubmitInput = {
   runId: string;
   playId: string;
   playName: string;
+  workflowFamilyKey?: string | null;
   artifactStorageKey: string;
   /**
    * Optional inline artifact for schedulers that run the legacy Temporal
@@ -119,6 +121,8 @@ export type PlaySchedulerSubmitInput = {
   orgId: string;
   userEmail: string;
   userId?: string | null;
+  source?: 'published' | 'ad_hoc' | 'draft';
+  executionProfile?: string | null;
   /** runner backend to use for executing attempts */
   runtimeBackend: string;
   /** dedup backend for cross-attempt cross-process idempotency */
@@ -200,6 +204,13 @@ export function normalizePlaySchedulerBackend(
   if (normalized === 'cf-workflows' || normalized === 'cf_workflows') {
     return PLAY_SCHEDULER_BACKENDS.cfWorkflows;
   }
+  if (
+    normalized === 'postgres' ||
+    normalized === 'postgres-scheduler' ||
+    normalized === 'postgres_scheduler'
+  ) {
+    return PLAY_SCHEDULER_BACKENDS.postgres;
+  }
   if (normalized === 'in-process' || normalized === 'in_process') {
     return PLAY_SCHEDULER_BACKENDS.inProcess;
   }