deepline 0.1.73 → 0.1.76

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

@@ -68,6 +68,7 @@ import type {
 } from './types.js';
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
+import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
@@ -1019,6 +1020,13 @@ export class DeeplineClient {
     return this.http.post('/api/v2/plays/check', input);
   }
 
+  async compileEnrichPlan(input: {
+    plan_args?: string[];
+    config?: unknown;
+  }): Promise<{ config: EnrichCompiledConfig }> {
+    return this.http.post('/api/v2/enrich/compile', input);
+  }
+
   async startPlayRunFromBundle(input: {
     name: string;
     sourceCode: string;

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

@@ -222,6 +222,11 @@ export type ConditionalStepResolver<Row, Value, Else = null> = {
   ): ConditionalStepResolver<Row, Value, ValueElse>;
 };
 
+export type StepOptions<Row> = {
+  readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+  readonly staleAfterSeconds?: number;
+};
+
 export type StepProgram<Input, Output, Return = Output> = {
   readonly kind: 'steps';
   readonly steps: readonly PlayStepProgramStep[];
@@ -234,6 +239,11 @@ export type StepProgram<Input, Output, Return = Output> = {
       | ConditionalStepResolver<Output, Value>
       | StepProgramResolver<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value>, Return>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
+    options: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
   return<Value>(
     resolver: StepResolver<Output, Value>,
   ): StepProgram<Input, Output, Value>;
@@ -248,6 +258,7 @@ export type StepProgramResolver<Input, Return> = {
 
 export type PlayStepProgramStep = {
   readonly name: string;
+  readonly staleAfterSeconds?: number;
   readonly resolver:
     | StepResolver<Record<string, unknown>, unknown>
     | ConditionalStepResolver<Record<string, unknown>, unknown>
@@ -259,6 +270,9 @@ export type ColumnResolver<Row, Value> =
   | ConditionalStepResolver<Row, Value>
   | StepProgramResolver<Row, Value>;
 
+export type StepProgramOutput<TProgram> =
+  TProgram extends StepProgram<any, infer Output, any> ? Output : never;
+
 export type DatasetBuilder<
   InputRow extends object,
   OutputRow extends object,
@@ -280,6 +294,16 @@ export type DatasetBuilder<
     name: Name,
     resolver: ColumnResolver<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>,
+  ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+  withColumns<Program extends StepProgram<OutputRow, object, unknown>>(
+    program: Program,
+  ): DatasetBuilder<InputRow, StepProgramOutput<Program>>;
   /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
   step<Name extends string, Value>(
     name: Name,
@@ -296,7 +320,6 @@ export type DatasetBuilder<
    */
   run(options?: {
     description?: string;
-    staleAfterSeconds?: number;
     key?:
       | (keyof InputRow & string)
       | readonly (keyof InputRow & string)[]
@@ -307,7 +330,6 @@ export type DatasetBuilder<
   }): Promise<PlayDataset<OutputRow>>;
 };
 
-
 export type CsvRenameMap = Record<string, string | readonly string[]>;
 
 /**
@@ -478,10 +500,7 @@ export interface DeeplinePlayRuntimeContext {
   /**
    * @deprecated `ctx.map(...)` was replaced by `ctx.dataset(...)`.
    */
-  map<TItem extends object>(
-    key: string,
-    items: PlayDatasetInput<TItem>,
-  ): never;
+  map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): never;
 
   /** Tool execution namespace. */
   tools: {
@@ -863,22 +882,43 @@ class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
       | StepResolver<Output, Value>
       | ConditionalStepResolver<Output, Value>
       | StepProgramResolver<Output, Value>,
-  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue> {
+  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
+    options: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+    options?: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue> {
     if (!name.trim()) {
       throw new Error(
         'steps().step(name, ...) requires a non-empty step name.',
       );
     }
+    const stepResolver =
+      options?.runIf && !isConditionalStepResolver(resolver)
+        ? new DeeplineConditionalStepResolver(
+            options.runIf,
+            resolver as StepResolver<Output, Value>,
+            null,
+          )
+        : resolver;
     return new DeeplineStepProgram(
       [
         ...this.steps,
         {
           name,
-          resolver: resolver as PlayStepProgramStep['resolver'],
+          resolver: stepResolver as PlayStepProgramStep['resolver'],
         },
       ],
       this.returnResolver as StepResolver<
-        Output & Record<Name, Value>,
+        Output & Record<Name, Value | null>,
         ReturnValue
       >,
     );
@@ -891,6 +931,16 @@ class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
   }
 }
 
+function isConditionalStepResolver(
+  value: unknown,
+): value is ConditionalStepResolver<unknown, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'conditional'
+  );
+}
+
 export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
   return new DeeplineStepProgram<TInput, TInput, TInput>([]);
 }

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

@@ -191,6 +191,7 @@ export async function harnessStartSheetDataset(input: {
   runId: string;
   inputOffset?: number;
   userEmail?: string | null;
+  cellPolicies?: Record<string, { staleAfterSeconds?: number }>;
 }): 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.73',
-  apiContract: '2026-06-dataset-column-syntax-cutover',
+  version: '0.1.76',
+  apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.73',
+    latest: '0.1.76',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

package/dist/repo/sdk/src/worker-play-entry.ts

@@ -19,6 +19,7 @@ import type {
   PlayStepProgramStep,
   StepProgram,
   StepProgramResolver,
+  StepOptions,
   StepResolver,
 } from './play.js';
 
@@ -43,6 +44,7 @@ export type {
   PrebuiltPlayRef,
   StepProgram,
   StepProgramResolver,
+  StepOptions,
   StepResolver,
   ToolExecuteResult,
 } from './play.js';
@@ -95,20 +97,44 @@ class WorkerStepProgram<Input, Output, ReturnValue> implements StepProgram<
       | StepResolver<Output, Value>
       | ConditionalStepResolver<Output, Value>
       | StepProgramResolver<Output, Value>,
-  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue> {
+  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
+    options: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+    options?: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue> {
     if (!name.trim()) {
       throw new Error('Step name required.');
     }
+    const stepResolver =
+      options?.runIf && !isConditionalStepResolver(resolver)
+        ? new WorkerConditionalStepResolver(
+            options.runIf,
+            resolver as StepResolver<Output, Value>,
+            null,
+          )
+        : resolver;
     return new WorkerStepProgram(
       [
         ...this.steps,
         {
           name,
-          resolver: resolver as PlayStepProgramStep['resolver'],
+          resolver: stepResolver as PlayStepProgramStep['resolver'],
+          ...(options?.staleAfterSeconds !== undefined
+            ? { staleAfterSeconds: options.staleAfterSeconds }
+            : {}),
         },
       ],
       this.returnResolver as StepResolver<
-        Output & Record<Name, Value>,
+        Output & Record<Name, Value | null>,
         ReturnValue
       >,
     );
@@ -121,6 +147,16 @@ class WorkerStepProgram<Input, Output, ReturnValue> implements StepProgram<
   }
 }
 
+function isConditionalStepResolver(
+  value: unknown,
+): value is ConditionalStepResolver<unknown, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'conditional'
+  );
+}
+
 export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
   return new WorkerStepProgram<TInput, TInput, TInput>([]);
 }

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

@@ -0,0 +1,88 @@
+export type CellStalenessPolicy = {
+  staleAfterSeconds?: number;
+};
+
+export type CellStalenessMeta = {
+  status?: string | null;
+  completedAt?: number | null;
+};
+
+export type CellStalenessDecision =
+  | { action: 'recompute'; reason: 'missing' | 'failed' | 'stale' }
+  | { action: 'reuse'; reason: 'fresh' | 'no_policy' };
+
+export type CellStalenessPolicyByField = Record<string, CellStalenessPolicy>;
+
+export const DEEPLINE_CELL_META_FIELD = '__deeplineCellMeta';
+
+export function validateStaleAfterSeconds(
+  staleAfterSeconds: number | undefined,
+  label = 'staleAfterSeconds',
+): void {
+  if (staleAfterSeconds === undefined) {
+    return;
+  }
+  if (
+    !Number.isFinite(staleAfterSeconds) ||
+    !Number.isInteger(staleAfterSeconds) ||
+    staleAfterSeconds <= 0
+  ) {
+    throw new Error(`${label} must be a positive whole number of seconds.`);
+  }
+}
+
+export function normalizeCellStalenessPolicy(
+  policy: CellStalenessPolicy | undefined,
+): CellStalenessPolicy {
+  validateStaleAfterSeconds(policy?.staleAfterSeconds);
+  return policy?.staleAfterSeconds === undefined
+    ? {}
+    : { staleAfterSeconds: policy.staleAfterSeconds };
+}
+
+export function shouldRecomputeCell(input: {
+  hasValue: boolean;
+  meta?: CellStalenessMeta | null;
+  policy?: CellStalenessPolicy;
+  nowMs?: number;
+}): CellStalenessDecision {
+  if (!input.hasValue) {
+    return { action: 'recompute', reason: 'missing' };
+  }
+
+  const status = String(input.meta?.status ?? '').trim();
+  if (status === 'failed') {
+    return { action: 'recompute', reason: 'failed' };
+  }
+
+  const staleAfterSeconds = input.policy?.staleAfterSeconds;
+  validateStaleAfterSeconds(staleAfterSeconds);
+  if (staleAfterSeconds === undefined) {
+    return { action: 'reuse', reason: 'no_policy' };
+  }
+
+  const completedAt =
+    typeof input.meta?.completedAt === 'number' &&
+    Number.isFinite(input.meta.completedAt)
+      ? input.meta.completedAt
+      : null;
+  if (completedAt === null) {
+    return { action: 'recompute', reason: 'missing' };
+  }
+
+  const ageMs = Math.max(0, (input.nowMs ?? Date.now()) - completedAt);
+  return ageMs > staleAfterSeconds * 1000
+    ? { action: 'recompute', reason: 'stale' }
+    : { action: 'reuse', reason: 'fresh' };
+}
+
+export function cellPolicyFields(
+  policies: CellStalenessPolicyByField | undefined,
+): string[] {
+  if (!policies) {
+    return [];
+  }
+  return Object.entries(policies)
+    .filter(([, policy]) => policy.staleAfterSeconds !== undefined)
+    .map(([field]) => field);
+}

package/dist/repo/shared_libs/play-runtime/step-program-dataset-builder.ts

@@ -0,0 +1,130 @@
+export type StepProgramDatasetOptions = {
+  runIf?: (
+    row: Record<string, unknown>,
+    index: number,
+  ) => boolean | Promise<boolean>;
+  staleAfterSeconds?: number;
+};
+
+export type StepProgramDatasetStep<TResolver> = {
+  name: string;
+  resolver: TResolver;
+  staleAfterSeconds?: number;
+};
+
+export type StepProgramDatasetProgram<TStep> = {
+  kind: 'steps';
+  steps: readonly TStep[];
+};
+
+export type StepProgramDatasetConditionalResolver<TResolver> = {
+  kind: 'conditional';
+  when: (
+    row: Record<string, unknown>,
+    index: number,
+  ) => boolean | Promise<boolean>;
+  run: TResolver;
+  elseValue?: unknown;
+};
+
+export function isStepProgramDatasetProgram<TStep>(
+  value: unknown,
+): value is StepProgramDatasetProgram<TStep> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'steps' &&
+    Array.isArray((value as { steps?: unknown }).steps)
+  );
+}
+
+export function isStepProgramDatasetConditionalResolver<TResolver>(
+  value: unknown,
+): value is StepProgramDatasetConditionalResolver<TResolver> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'conditional' &&
+    typeof (value as { when?: unknown }).when === 'function' &&
+    typeof (value as { run?: unknown }).run === 'function'
+  );
+}
+
+export class StepProgramDatasetBuilder<
+  TStep extends StepProgramDatasetStep<TResolver>,
+  TResolver,
+  TRunOptions,
+  TResult,
+> {
+  private readonly program: StepProgramDatasetProgram<TStep> = {
+    kind: 'steps',
+    steps: [],
+  };
+
+  constructor(
+    private readonly runProgram: (
+      program: StepProgramDatasetProgram<TStep>,
+      options?: TRunOptions,
+    ) => TResult,
+    private readonly messages: {
+      emptyColumnName: string;
+      invalidColumnsProgram: string;
+      legacyStep: string;
+    },
+  ) {}
+
+  withColumn(
+    name: string,
+    resolver: TResolver,
+    options?: StepProgramDatasetOptions,
+  ): this {
+    if (!name.trim()) {
+      throw new Error(this.messages.emptyColumnName);
+    }
+    this.program.steps = [
+      ...this.program.steps,
+      {
+        name,
+        resolver: this.applyDerivationOptions(resolver, options),
+        ...(options?.staleAfterSeconds !== undefined
+          ? { staleAfterSeconds: options.staleAfterSeconds }
+          : {}),
+      } as TStep,
+    ];
+    return this;
+  }
+
+  withColumns(program: StepProgramDatasetProgram<TStep>): this {
+    if (!isStepProgramDatasetProgram<TStep>(program)) {
+      throw new Error(this.messages.invalidColumnsProgram);
+    }
+    this.program.steps = [...this.program.steps, ...program.steps];
+    return this;
+  }
+
+  step(): never {
+    throw new Error(this.messages.legacyStep);
+  }
+
+  run(options?: TRunOptions): TResult {
+    return this.runProgram(this.program, options);
+  }
+
+  private applyDerivationOptions(
+    resolver: TResolver,
+    options?: StepProgramDatasetOptions,
+  ): TResolver {
+    if (
+      !options?.runIf ||
+      isStepProgramDatasetConditionalResolver<TResolver>(resolver)
+    ) {
+      return resolver;
+    }
+    return {
+      kind: 'conditional',
+      when: options.runIf,
+      run: resolver,
+      elseValue: null,
+    } as TResolver;
+  }
+}

package/dist/repo/shared_libs/plays/row-identity.ts

@@ -192,46 +192,6 @@ export function normalizeTableNamespace(value: string): string {
   );
 }
 
-export function resolveStaleMapTableNamespace(
-  mapKey: string,
-  staleAfterSeconds?: number | null,
-  nowMs: number = Date.now(),
-): string {
-  const normalizedMapKey = normalizeTableNamespace(mapKey);
-  if (staleAfterSeconds === undefined || staleAfterSeconds === null) {
-    return normalizedMapKey;
-  }
-
-  if (
-    !Number.isFinite(staleAfterSeconds) ||
-    !Number.isInteger(staleAfterSeconds) ||
-    staleAfterSeconds <= 0
-  ) {
-    throw new Error(
-      'ctx.dataset() staleAfterSeconds must be a positive whole number of seconds.',
-    );
-  }
-
-  const bucket = Math.floor(nowMs / (staleAfterSeconds * 1000));
-  const stalePartitionKey = `stale_${staleAfterSeconds}_${bucket}`;
-  const candidate = `${normalizedMapKey}_${stalePartitionKey}`;
-  if (candidate.length <= MAP_KEY_NAMESPACE_MAX_LENGTH) {
-    return candidate;
-  }
-
-  const digest = sha256Hex(`${normalizedMapKey}\n${stalePartitionKey}`).slice(
-    0,
-    12,
-  );
-  const prefixLength = Math.max(
-    1,
-    MAP_KEY_NAMESPACE_MAX_LENGTH - digest.length - 1,
-  );
-  const prefix =
-    normalizedMapKey.slice(0, prefixLength).replace(/_+$/g, '') || 'map';
-  return `${prefix}_${digest}`;
-}
-
 export function validatePlaySheetTableName(
   playName: string,
   tableNamespace: string,

package/package.json

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