deepline 0.1.74 → 0.1.76

package/dist/index.d.mts

@@ -1051,6 +1051,43 @@ interface PlayStagedFileRef {
     bytes: number;
 }
 
+type EnrichStepCommand = {
+    alias: string;
+    tool: string;
+    operation?: string;
+    payload: Record<string, unknown>;
+    extract_js?: string;
+    run_if_js?: string;
+    description?: string;
+    disabled?: boolean;
+};
+type EnrichWaterfallCommand = {
+    with_waterfall: string;
+    min_results?: number;
+    commands: EnrichCommand[];
+    description?: string;
+};
+type EnrichCommand = EnrichStepCommand | EnrichWaterfallCommand;
+type EnrichCompiledConfig = {
+    version: 1;
+    commands: EnrichCommand[];
+    cost_cap_usd_per_run?: number;
+    _comments?: Array<{
+        path: string;
+        lines: string[];
+    }>;
+    _expansion_preview?: {
+        plays: Array<{
+            alias: string;
+            tool_id: string;
+            template_group: string;
+            runtime_group: string;
+            estimated_credits_range: string;
+            steps: Array<Record<string, unknown>>;
+        }>;
+    };
+};
+
 type ExecuteToolRawOptions = {
     includeToolMetadata?: boolean;
 };
@@ -1350,6 +1387,12 @@ declare class DeeplineClient {
         sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
+    compileEnrichPlan(input: {
+        plan_args?: string[];
+        config?: unknown;
+    }): Promise<{
+        config: EnrichCompiledConfig;
+    }>;
     startPlayRunFromBundle(input: {
         name: string;
         sourceCode: string;
@@ -2145,6 +2188,7 @@ type ConditionalStepResolver<Row, Value, Else = null> = {
 };
 type StepOptions<Row> = {
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    readonly staleAfterSeconds?: number;
 };
 type StepProgram<Input, Output, Return = Output> = {
     readonly kind: 'steps';
@@ -2163,6 +2207,7 @@ type StepProgramResolver<Input, Return> = {
 };
 type PlayStepProgramStep = {
     readonly name: string;
+    readonly staleAfterSeconds?: number;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
 type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
@@ -2197,7 +2242,6 @@ type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
      */
     run(options?: {
         description?: string;
-        staleAfterSeconds?: number;
         key?: (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
     }): Promise<PlayDataset<OutputRow>>;
 };

package/dist/index.d.ts

@@ -1051,6 +1051,43 @@ interface PlayStagedFileRef {
     bytes: number;
 }
 
+type EnrichStepCommand = {
+    alias: string;
+    tool: string;
+    operation?: string;
+    payload: Record<string, unknown>;
+    extract_js?: string;
+    run_if_js?: string;
+    description?: string;
+    disabled?: boolean;
+};
+type EnrichWaterfallCommand = {
+    with_waterfall: string;
+    min_results?: number;
+    commands: EnrichCommand[];
+    description?: string;
+};
+type EnrichCommand = EnrichStepCommand | EnrichWaterfallCommand;
+type EnrichCompiledConfig = {
+    version: 1;
+    commands: EnrichCommand[];
+    cost_cap_usd_per_run?: number;
+    _comments?: Array<{
+        path: string;
+        lines: string[];
+    }>;
+    _expansion_preview?: {
+        plays: Array<{
+            alias: string;
+            tool_id: string;
+            template_group: string;
+            runtime_group: string;
+            estimated_credits_range: string;
+            steps: Array<Record<string, unknown>>;
+        }>;
+    };
+};
+
 type ExecuteToolRawOptions = {
     includeToolMetadata?: boolean;
 };
@@ -1350,6 +1387,12 @@ declare class DeeplineClient {
         sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
+    compileEnrichPlan(input: {
+        plan_args?: string[];
+        config?: unknown;
+    }): Promise<{
+        config: EnrichCompiledConfig;
+    }>;
     startPlayRunFromBundle(input: {
         name: string;
         sourceCode: string;
@@ -2145,6 +2188,7 @@ type ConditionalStepResolver<Row, Value, Else = null> = {
 };
 type StepOptions<Row> = {
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    readonly staleAfterSeconds?: number;
 };
 type StepProgram<Input, Output, Return = Output> = {
     readonly kind: 'steps';
@@ -2163,6 +2207,7 @@ type StepProgramResolver<Input, Return> = {
 };
 type PlayStepProgramStep = {
     readonly name: string;
+    readonly staleAfterSeconds?: number;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
 type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
@@ -2197,7 +2242,6 @@ type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
      */
     run(options?: {
         description?: string;
-        staleAfterSeconds?: number;
         key?: (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
     }): Promise<PlayDataset<OutputRow>>;
 };

package/dist/index.js

@@ -241,10 +241,10 @@ var import_node_path2 = require("path");
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.74",
-  apiContract: "2026-06-dataset-column-syntax-cutover",
+  version: "0.1.76",
+  apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.74",
+    latest: "0.1.76",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -1127,6 +1127,9 @@ var DeeplineClient = class {
   async checkPlayArtifact(input) {
     return this.http.post("/api/v2/plays/check", input);
   }
+  async compileEnrichPlan(input) {
+    return this.http.post("/api/v2/enrich/compile", input);
+  }
   async startPlayRunFromBundle(input) {
     const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
       name: input.name,

package/dist/index.mjs

@@ -179,10 +179,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.74",
-  apiContract: "2026-06-dataset-column-syntax-cutover",
+  version: "0.1.76",
+  apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.74",
+    latest: "0.1.76",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -1065,6 +1065,9 @@ var DeeplineClient = class {
   async checkPlayArtifact(input) {
     return this.http.post("/api/v2/plays/check", input);
   }
+  async compileEnrichPlan(input) {
+    return this.http.post("/api/v2/enrich/compile", input);
+  }
   async startPlayRunFromBundle(input) {
     const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
       name: input.name,

package/dist/repo/apps/play-runner-workers/src/entry.ts

@@ -155,6 +155,10 @@ import {
   StepProgramDatasetBuilder,
   type StepProgramDatasetOptions,
 } from '../../../shared_libs/play-runtime/step-program-dataset-builder';
+import {
+  DEEPLINE_CELL_META_FIELD,
+  shouldRecomputeCell,
+} from '../../../shared_libs/play-runtime/cell-staleness';
 
 // The play's default export. The bundler injects this — see bundle-play-file.ts.
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
@@ -2032,6 +2036,7 @@ type WorkerConditionalStepResolver = {
 
 type WorkerStepProgramStep = {
   name: string;
+  staleAfterSeconds?: number;
   resolver:
     | WorkerStepResolver
     | WorkerConditionalStepResolver
@@ -3049,6 +3054,7 @@ async function prepareMapRows(input: {
   tableNamespace: string;
   rows: Record<string, unknown>[];
   outputFields: string[];
+  cellPolicies?: Record<string, { staleAfterSeconds?: number }>;
 }): Promise<{
   inserted: number;
   skipped: number;
@@ -3073,6 +3079,7 @@ async function prepareMapRows(input: {
     rows: input.rows.map((row) => ({ ...row })),
     runId: input.req.runId,
     userEmail: input.req.userEmail,
+    cellPolicies: input.cellPolicies,
   });
   for (const timing of result.timings ?? []) {
     const phase =
@@ -3221,12 +3228,16 @@ function createMinimalWorkerCtx(
       },
     );
     if (!response.ok) {
-      throw new Error(`Secret ${auth.secret.name} is not available to this run.`);
+      throw new Error(
+        `Secret ${auth.secret.name} is not available to this run.`,
+      );
     }
     const payload = (await response.json()) as { value?: unknown };
     const value = typeof payload.value === 'string' ? payload.value : null;
     if (!value) {
-      throw new Error(`Secret ${auth.secret.name} is not available to this run.`);
+      throw new Error(
+        `Secret ${auth.secret.name} is not available to this run.`,
+      );
     }
     secretRedactor.register(value);
     return auth.kind === 'bearer'
@@ -3359,6 +3370,7 @@ function createMinimalWorkerCtx(
           index: number,
         ) => Promise<unknown> | unknown)
     >,
+    cellPolicies?: Record<string, { staleAfterSeconds?: number }>,
     opts?: WorkerMapOptions,
   ): Promise<unknown> => {
     const mapStartedAt = nowMs();
@@ -3498,6 +3510,7 @@ function createMinimalWorkerCtx(
         req,
         tableNamespace: name,
         outputFields,
+        cellPolicies,
         rows: chunkEntries.map(({ row, rowKey }) => ({
           ...row,
           __deeplineRowKey: rowKey,
@@ -3572,10 +3585,11 @@ function createMinimalWorkerCtx(
         | Record<
             string,
             {
-              status: 'cached' | 'skipped';
+              status: 'cached' | 'skipped' | 'completed';
               stage?: string | null;
               reused?: boolean;
               runId?: string;
+              completedAt?: number;
             }
           >
         | undefined
@@ -3604,10 +3618,11 @@ function createMinimalWorkerCtx(
               const cellMetaPatch: Record<
                 string,
                 {
-                  status: 'cached' | 'skipped';
+                  status: 'cached' | 'skipped' | 'completed';
                   stage?: string | null;
                   reused?: boolean;
                   runId?: string;
+                  completedAt?: number;
                 }
               > = {};
               const waterfallOutputs: RecordedWaterfallOutput[] = [];
@@ -3643,7 +3658,28 @@ function createMinimalWorkerCtx(
                   ),
               };
               for (const [key, value] of fieldEntries) {
-                if (isCompletedWorkerFieldValue(enriched[key])) {
+                const rawCellMeta =
+                  enriched[DEEPLINE_CELL_META_FIELD] &&
+                  typeof enriched[DEEPLINE_CELL_META_FIELD] === 'object'
+                    ? (
+                        enriched[DEEPLINE_CELL_META_FIELD] as Record<
+                          string,
+                          unknown
+                        >
+                      )[key]
+                    : null;
+                const reuseDecision = shouldRecomputeCell({
+                  hasValue: isCompletedWorkerFieldValue(enriched[key]),
+                  meta:
+                    rawCellMeta && typeof rawCellMeta === 'object'
+                      ? (rawCellMeta as {
+                          status?: string;
+                          completedAt?: number;
+                        })
+                      : null,
+                  policy: cellPolicies?.[key],
+                });
+                if (reuseDecision.action === 'reuse') {
                   cellMetaPatch[key] = {
                     status: 'cached',
                     stage: key,
@@ -3673,6 +3709,13 @@ function createMinimalWorkerCtx(
                     stage: key,
                     runId: req.runId,
                   };
+                } else {
+                  cellMetaPatch[key] = {
+                    status: 'completed',
+                    stage: key,
+                    runId: req.runId,
+                    completedAt: nowMs(),
+                  };
                 }
               }
               for (const stepOutput of stepProgramOutputs) {
@@ -4037,7 +4080,15 @@ function createMinimalWorkerCtx(
           const fields = Object.fromEntries(
             program.steps.map((step) => [step.name, step.resolver]),
           );
-          return runMap(this.name, this.rows, fields, opts);
+          const cellPolicies = Object.fromEntries(
+            program.steps.map((step) => [
+              step.name,
+              step.staleAfterSeconds === undefined
+                ? {}
+                : { staleAfterSeconds: step.staleAfterSeconds },
+            ]),
+          );
+          return runMap(this.name, this.rows, fields, cellPolicies, opts);
         },
         {
           emptyColumnName:
@@ -4255,7 +4306,15 @@ function createMinimalWorkerCtx(
         const fields = Object.fromEntries(
           fieldsDef.steps.map((step) => [step.name, step.resolver]),
         );
-        return runMap(name, rows, fields, opts);
+        const cellPolicies = Object.fromEntries(
+          fieldsDef.steps.map((step) => [
+            step.name,
+            step.staleAfterSeconds === undefined
+              ? {}
+              : { staleAfterSeconds: step.staleAfterSeconds },
+          ]),
+        );
+        return runMap(name, rows, fields, cellPolicies, opts);
       }
       throw new Error(
         'ctx.dataset(key, rows, fields, options) is not supported. Use ctx.dataset(key, rows).withColumn(...).run(options).',
@@ -4266,11 +4325,11 @@ function createMinimalWorkerCtx(
         'ctx.map(...) has been replaced by ctx.dataset(...). Use ctx.dataset(key, rows).withColumn(...).run(options).',
       );
     },
-	    tools: {
-	      async execute(requestArg: unknown): Promise<unknown> {
+    tools: {
+      async execute(requestArg: unknown): Promise<unknown> {
         assertNotAborted(abortSignal);
         const request = normalizeToolExecuteArgs(requestArg);
-	        assertNoSecretTaint(request.input, 'ctx.tools.execute input');
+        assertNoSecretTaint(request.input, 'ctx.tools.execute input');
         return await executeWithRuntimeReceipt(
           `tool:${request.id}:${deriveToolRequestIdentity({
             toolId: request.toolId,
@@ -4340,9 +4399,9 @@ function createMinimalWorkerCtx(
         timeoutMs?: number;
         staleAfterSeconds?: number;
       },
-	    ): Promise<unknown> {
-	      const normalizedKey = normalizeContextKey(key, 'runPlay');
-	      const resolvedName = resolvePlayRefName(playRef);
+    ): Promise<unknown> {
+      const normalizedKey = normalizeContextKey(key, 'runPlay');
+      const resolvedName = resolvePlayRefName(playRef);
       assertNoSecretTaint(input, 'ctx.runPlay input');
       if (!resolvedName) {
         throw new Error('ctx.runPlay(...) requires a resolvable play name.');
@@ -4582,18 +4641,15 @@ function createMinimalWorkerCtx(
         }
       });
     },
-	    async fetch(
-	      key: string,
-	      input: string | URL,
-	      init: SecretAwareRequestInit = {},
-	      options?: { staleAfterSeconds?: number },
-	    ): Promise<WorkerFetchResponse> {
-	      assertNotAborted(abortSignal);
-	      const normalizedKey = normalizeContextKey(key, 'fetch');
-      if (
-        valueContainsSecret(input) ||
-        valueContainsSecret(init.body)
-      ) {
+    async fetch(
+      key: string,
+      input: string | URL,
+      init: SecretAwareRequestInit = {},
+      options?: { staleAfterSeconds?: number },
+    ): Promise<WorkerFetchResponse> {
+      assertNotAborted(abortSignal);
+      const normalizedKey = normalizeContextKey(key, 'fetch');
+      if (valueContainsSecret(input) || valueContainsSecret(init.body)) {
         throw new Error(
           'ctx.fetch does not allow secrets in the URL or body. Use an approved secret auth helper.',
         );
@@ -4606,10 +4662,10 @@ function createMinimalWorkerCtx(
       if (init.auth !== undefined && !isSecretAuth(init.auth)) {
         throw new Error('ctx.fetch auth must come from ctx.secrets.');
       }
-	      const url = input.toString();
-	      const method = (init.method ?? 'GET').toUpperCase();
+      const url = input.toString();
+      const method = (init.method ?? 'GET').toUpperCase();
       const secretHeaderMarkers = secretAuthHeaderMarkers(init.auth);
-	      const safeHeaders = {
+      const safeHeaders = {
         ...normalizeFetchHeaders(init.headers),
         ...secretHeaderMarkers,
       };
@@ -4628,7 +4684,7 @@ function createMinimalWorkerCtx(
         safeHeaders,
         url,
       })}${staleRuntimeSuffix(options?.staleAfterSeconds)}`;
-	      return await executeWithRuntimeReceipt(receiptKey, async () => {
+      return await executeWithRuntimeReceipt(receiptKey, async () => {
         const secretHeaders = await resolveSecretAuth(init.auth);
         const headers = {
           ...normalizeFetchHeaders(init.headers),
@@ -4636,23 +4692,23 @@ function createMinimalWorkerCtx(
         };
         const fetchInit = { ...init, headers };
         delete fetchInit.auth;
-	        const response = await fetch(url, fetchInit);
-	        assertNotAborted(abortSignal);
-	        const bodyText = await response.text();
+        const response = await fetch(url, fetchInit);
+        assertNotAborted(abortSignal);
+        const bodyText = await response.text();
         const redactedBodyText = secretRedactor.redactString(bodyText);
-	        return {
-	          ok: response.ok,
-	          status: response.status,
-	          statusText: response.statusText,
-	          url: response.url,
-	          headers: secretRedactor.redact(
-              Object.fromEntries(response.headers.entries()),
-            ) as Record<string, string>,
-	          bodyText: redactedBodyText,
-	          json: secretRedactor.redact(parseFetchJsonOrNull(bodyText)),
-	        };
-	      });
-	    },
+        return {
+          ok: response.ok,
+          status: response.status,
+          statusText: response.statusText,
+          url: response.url,
+          headers: secretRedactor.redact(
+            Object.fromEntries(response.headers.entries()),
+          ) as Record<string, string>,
+          bodyText: redactedBodyText,
+          json: secretRedactor.redact(parseFetchJsonOrNull(bodyText)),
+        };
+      });
+    },
     secrets: {
       get(name: string): SecretHandle {
         if (typeof name !== 'string' || !name.trim()) {

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

@@ -224,6 +224,7 @@ export type ConditionalStepResolver<Row, Value, Else = null> = {
 
 export type StepOptions<Row> = {
   readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+  readonly staleAfterSeconds?: number;
 };
 
 export type StepProgram<Input, Output, Return = Output> = {
@@ -257,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>
@@ -318,7 +320,6 @@ export type DatasetBuilder<
    */
   run(options?: {
     description?: string;
-    staleAfterSeconds?: number;
     key?:
       | (keyof InputRow & string)
       | readonly (keyof InputRow & string)[]

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.74',
-  apiContract: '2026-06-dataset-column-syntax-cutover',
+  version: '0.1.76',
+  apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.74',
+    latest: '0.1.76',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

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

@@ -128,6 +128,9 @@ class WorkerStepProgram<Input, Output, ReturnValue> implements StepProgram<
         {
           name,
           resolver: stepResolver as PlayStepProgramStep['resolver'],
+          ...(options?.staleAfterSeconds !== undefined
+            ? { staleAfterSeconds: options.staleAfterSeconds }
+            : {}),
         },
       ],
       this.returnResolver as StepResolver<

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