deepline 0.3.243 → 0.3.244

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.243',
+  version: '0.3.244',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -1,3 +1,4 @@
+import { prepareRetainedPlayPipelinesForTransport } from '../plays/execution-pipeline';
 import { createWriteStream } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { stat } from 'node:fs/promises';
@@ -206,6 +207,7 @@ type RuntimeApiRequest =
       executionProfile?: string | null;
       maxCreditsPerRun?: number | null;
       staticPipeline?: unknown;
+      retainedPipelineGraph?: unknown;
       source?: 'published' | 'ad_hoc' | 'draft';
       inputFileId?: string;
       inputBytes?: number;
@@ -262,6 +264,7 @@ type RuntimeApiRequest =
       runtimeHarnessWorkerName?: string | null;
       maxCreditsPerRun?: number | null;
       staticPipeline?: unknown;
+      retainedPipelineGraph?: unknown;
       source?: 'published' | 'ad_hoc' | 'draft';
       triggerSource?: 'webhook' | 'cron' | 'sql_listener' | 'api';
       inputFileId?: string;
@@ -1448,7 +1451,9 @@ async function postAppRuntimeApi<TResponse>(
   // attempts (that identity is what makes a receipt retry safe), so a second
   // `JSON.stringify` of a megabyte payload would be pure cost.
   const serializationStartedAt = Date.now();
-  const serializedBody = JSON.stringify(body);
+  const serializedBody = JSON.stringify(
+    prepareRetainedPlayPipelinesForTransport(body),
+  );
   const requestBodySerializeMs = Math.max(
     0,
     Date.now() - serializationStartedAt,
@@ -2503,6 +2508,7 @@ export async function startRunViaAppRuntime(
     executionProfile?: string | null;
     maxCreditsPerRun?: number | null;
     staticPipeline?: unknown;
+    retainedPipelineGraph?: unknown;
     source?: 'published' | 'ad_hoc' | 'draft';
     inputFileId?: string;
     inputBytes?: number;

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -14173,11 +14173,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         });
         return result as TOutput;
       } catch (childError) {
-        this.recordInlineChildFailure(resolvedName, childError);
+        if (!isControlledPlaySuspension(childError)) {
+          this.recordInlineChildFailure(resolvedName, childError);
+        }
         throw childError;
       }
     } catch (error) {
-      if (isPlayExecutionSuspendedError(error)) {
+      if (isControlledPlaySuspension(error)) {
         throw error;
       }
       if (rowStore) {

package/dist/bundling-sources/shared_libs/play-runtime/launch-identity.ts

@@ -55,6 +55,7 @@ export const PLAY_LAUNCH_ENVELOPE_FIELD_ROLES: {
   runtimeArtifact: 'detail',
   runtimeProtocolVersion: 'detail',
   staticPipeline: 'detail',
+  retainedPipelineGraph: 'detail',
   inputSummary: 'detail',
   inputBytes: 'detail',
   inputFileId: 'detail',

package/dist/bundling-sources/shared_libs/play-runtime/protocol.ts

@@ -1,3 +1,9 @@
+import { deployed, readDeployedObject } from '@deepline/deployed-contracts';
+import {
+  type RetainedPipelineCarrier,
+  hydrateRetainedPlayPipelines,
+  prepareRetainedPlayPipelinesForTransport,
+} from '../plays/execution-pipeline';
 import type { PlayBundleArtifact } from '../plays/artifact-types';
 import type {
   PlayCheckpoint,
@@ -177,7 +183,7 @@ export type PlayRunnerBudgetChargeResult = {
   counters: Record<string, number>;
 };
 
-export interface PlayRunnerContextConfig {
+export interface PlayRunnerContextConfig extends RetainedPipelineCarrier {
   executorToken?: string;
   baseUrl?: string;
   /**
@@ -447,3 +453,39 @@ export type PlayRunnerRowOutcomeSummary = {
   /** Rows omitted because a newer Runtime Sheet write took precedence. */
   supersededRows?: number;
 };
+
+export const RETAINED_PLAY_PIPELINE_CONTRACT = deployed.object({
+  id: 'retained-play-pipeline',
+  unknown: 'preserve',
+  fields: {
+    retainedPipelineGraph: deployed.optional(deployed.record(), {
+      whenAbsent:
+        'read the historical inline staticPipeline or stored staticPipelineV2',
+    }),
+    staticPipeline: deployed.optional(deployed.json(), {
+      whenAbsent:
+        'read the named retained pipeline root, otherwise no pipeline',
+    }),
+  },
+});
+
+/** Runner envelope ownership stays here; the shared codec owns only contracts. */
+export function preparePlayRunnerConfigForTransport(
+  config: PlayRunnerExecutionConfig,
+): PlayRunnerExecutionConfig {
+  return {
+    ...config,
+    context: prepareRetainedPlayPipelinesForTransport(config.context),
+  };
+}
+
+export function hydratePlayRunnerConfig(
+  config: PlayRunnerExecutionConfig,
+): PlayRunnerExecutionConfig {
+  return {
+    ...config,
+    context: hydrateRetainedPlayPipelines(
+      readDeployedObject(RETAINED_PLAY_PIPELINE_CONTRACT, config.context).value,
+    ) as unknown as PlayRunnerContextConfig,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/index.ts

@@ -1,3 +1,4 @@
+import { hydratePlayRunnerConfig } from '../protocol';
 import { appendFileSync, createReadStream, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
@@ -1908,6 +1909,7 @@ async function run(
   config: PlayRunnerExecutionConfig,
   options?: ExecutePlayRunnerOptions,
 ): Promise<PlayRunnerResult> {
+  config = hydratePlayRunnerConfig(config);
   const runStartedAt = Date.now();
   const runnerRunAttempt =
     typeof config.context.runAttempt === 'number' &&

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts

@@ -1,3 +1,4 @@
+import { preparePlayRunnerConfigForTransport } from '../../protocol';
 import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { gzipSync } from 'node:zlib';
@@ -695,7 +696,7 @@ export async function stageRunnerPayload(input: {
         runnerCode: bundle,
         artifactBundledCode: compactedArtifact.bundledCode,
         artifactSourceMap: input.config.artifact.sourceMap,
-        config: remoteConfig,
+        config: preparePlayRunnerConfigForTransport(remoteConfig),
         crashPusherCode:
           buildDaytonaCrashTerminalPusherSource(runtimeLimitSeconds),
       }),

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/local-process.ts

@@ -1,3 +1,4 @@
+import { preparePlayRunnerConfigForTransport } from '../../protocol';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { cp, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
@@ -407,7 +408,13 @@ export const localProcessPlayRunnerBackend: PlayRunnerBackend = {
             },
             async () => {
               await writeFile(runnerPath, bundle, 'utf-8');
-              await writeFile(configPath, JSON.stringify(localConfig), 'utf-8');
+              await writeFile(
+                configPath,
+                JSON.stringify(
+                  preparePlayRunnerConfigForTransport(localConfig),
+                ),
+                'utf-8',
+              );
             },
           );
           logLocalRunnerPerf(

package/dist/bundling-sources/shared_libs/play-runtime/runtime-api.ts

@@ -1,3 +1,7 @@
+import {
+  prepareRetainedPlayPipelinesForTransport,
+  hydrateRetainedPlayPipelines,
+} from '../plays/execution-pipeline';
 import { createHash, randomUUID } from 'node:crypto';
 import {
   createRuntimePool,
@@ -514,6 +518,7 @@ type RuntimeApiActionRequest =
   | {
       action: 'resolve_play';
       playRef: string;
+      acceptRetainedPipelineGraph?: boolean;
     }
   | {
       action: 'ensure_sheet';
@@ -784,7 +789,7 @@ async function postRuntimeApi<TResponse>(
       response = await fetch(url, {
         method: 'POST',
         headers: resolveRuntimeApiHeaders(context, vercelHeaders),
-        body: JSON.stringify(body),
+        body: JSON.stringify(prepareRetainedPlayPipelinesForTransport(body)),
         signal: context.abortSignal
           ? AbortSignal.any([context.abortSignal, abortController.signal])
           : abortController.signal,
@@ -3579,13 +3584,19 @@ export async function resolveRuntimeReferencedPlay(
   context: RuntimeApiContext,
   playRef: string,
 ): Promise<ResolvedRuntimePlay | null> {
-  const response = await postRuntimeApi<{
+  const wire = await postRuntimeApi<{
     play: ResolvedRuntimePlay | null;
     manifest?: { staticPipeline?: PlayStaticPipeline | null } | null;
   }>(context, {
     action: 'resolve_play',
     playRef,
+    acceptRetainedPipelineGraph: true,
   });
+  const response = {
+    ...wire,
+    play: hydrateRetainedPlayPipelines(wire.play),
+    manifest: hydrateRetainedPlayPipelines(wire.manifest),
+  };
   if (!response.play) {
     return null;
   }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -1,3 +1,4 @@
+import type { RetainedPipelineCarrier } from '../plays/execution-pipeline';
 /**
  * Scheduler-backend interface — owns play workflow lifecycle.
  *
@@ -39,7 +40,7 @@ export type PlaySchedulerBackendId =
 
 export type { PlayRunInputPayload };
 
-export type PlaySchedulerSubmitInput = {
+export type PlaySchedulerSubmitInput = RetainedPipelineCarrier & {
   runId: string;
   /**
    * Admit an exact replay only. This is an ephemeral admission instruction:
@@ -92,8 +93,6 @@ export type PlaySchedulerSubmitInput = {
   /** Immutable scheduler/worker/runner ABI snapshot (not a Git SHA). */
   runtimeProtocolVersion?: PlayRuntimeProtocolVersion | null;
   input: PlayRunInputPayload;
-  /** Bounded launch metadata used only by the asynchronous ledger projector. */
-  staticPipeline?: unknown;
   inputSummary?: Record<string, unknown>;
   /** Convex metadata for the exact input saved before scheduler submission. */
   inputFileId?: string;

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -1,3 +1,8 @@
+import {
+  retainedPlayPipelineFields,
+  hydrateRetainedPlayPipelines,
+  prepareRetainedPlayPipelinesForTransport,
+} from '../../plays/execution-pipeline';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, sep } from 'node:path';
@@ -4963,7 +4968,9 @@ async function submitPostgresSchedulerRunTransaction(
             'replayedFromRunId', launch_payload.launch_json ->> 'replayedFromRunId',
             'secretRefs', launch_payload.launch_json -> 'secretRefs',
             'inputSummary', launch_payload.launch_json -> 'inputSummary'
-          )),
+          )) || CASE WHEN launch_payload.launch_json ? 'retainedPipelineGraph'
+            THEN jsonb_build_object('retainedPipelineGraph', launch_payload.launch_json -> 'retainedPipelineGraph')
+            ELSE '{}'::jsonb END,
           ${causalOutboxCreatedAt('run_insert.run_id', options)}
         FROM run_insert
         CROSS JOIN launch_payload
@@ -5016,7 +5023,7 @@ async function submitPostgresSchedulerRunTransaction(
       input.graphHash,
       input.runtimeBackend,
       input.artifactStorageKey,
-      stringifyPostgresJson(input),
+      stringifyPostgresJson(prepareRetainedPlayPipelinesForTransport(input)),
       postgresSchedulerNotifyChannel('queue', options),
       JSON.stringify({ runId: input.runId, playName: input.playName }),
       releaseAdmissionKey,
@@ -5418,6 +5425,7 @@ export type PostgresSchedulerCronSourcePin = {
   artifactHash: string | null;
   graphHash: string | null;
   staticPipeline: unknown | null;
+  retainedPipelineGraph?: unknown;
   input: PlaySchedulerSubmitInput['input'];
   source: 'published' | 'draft';
   schedulerSchema: string | null;
@@ -5442,7 +5450,7 @@ export function postgresSchedulerCronSourcePinFromLaunch(
     artifactKind,
     artifactHash: launch.artifactHash || null,
     graphHash: launch.graphHash || null,
-    staticPipeline: launch.staticPipeline ?? null,
+    ...retainedPlayPipelineFields(launch.staticPipeline ?? null, launch),
     input: launch.input,
     source: launch.source === 'draft' ? 'draft' : 'published',
     schedulerSchema: launch.schedulerSchema ?? null,
@@ -5621,7 +5629,9 @@ export async function seedPostgresSchedulerCronSchedule(
       input.dueAtMs,
       input.cron.trim(),
       input.timezone?.trim() || null,
-      stringifyPostgresJson(sourcePin),
+      stringifyPostgresJson(
+        prepareRetainedPlayPipelinesForTransport(sourcePin),
+      ),
       input.queueName,
       task.taskName,
       stringifyPostgresJson(task.params),
@@ -6038,7 +6048,9 @@ export async function firePostgresSchedulerCronSchedule(
             'asyncAncestryPlayIds', launch_payload.launch_json -> 'asyncAncestryPlayIds',
             'secretRefs', launch_payload.launch_json -> 'secretRefs',
             'inputSummary', launch_payload.launch_json -> 'inputSummary'
-          )),
+          )) || CASE WHEN launch_payload.launch_json ? 'retainedPipelineGraph'
+            THEN jsonb_build_object('retainedPipelineGraph', launch_payload.launch_json -> 'retainedPipelineGraph')
+            ELSE '{}'::jsonb END,
           ${causalOutboxCreatedAt('run_insert.run_id', options)}
         FROM run_insert
         CROSS JOIN launch_payload
@@ -6078,7 +6090,7 @@ export async function firePostgresSchedulerCronSchedule(
       schedule.dueAtMs,
       successorDueAtMs,
       launch.runId,
-      stringifyPostgresJson(launch),
+      stringifyPostgresJson(prepareRetainedPlayPipelinesForTransport(launch)),
       input.queueName,
       playTask.taskName,
       stringifyPostgresJson(playTask.params),
@@ -7463,7 +7475,7 @@ export async function claimPostgresSchedulerOverdueDetachedRunnerCeilings(
     runId: row.run_id,
     attempt: row.attempt,
     leaseToken: row.lease_token,
-    launch: row.launch_json,
+    launch: parseLaunchJson(row.launch_json),
     suspension: row.suspension_json,
   }));
 }
@@ -13924,7 +13936,10 @@ export function buildPostgresSchedulerRunnerContext(
     toolResponseReceiptRevision: toolResponseReceiptRevisionFromLaunch(
       launch.contractSnapshot,
     ),
-    staticPipeline: staticPipelineFromContractSnapshot(launch.contractSnapshot),
+    ...retainedPlayPipelineFields(
+      staticPipelineFromContractSnapshot(launch.contractSnapshot),
+      launch,
+    ),
     sandboxRuntimeLimits: sandboxRuntimeLimitsFromContractSnapshot(
       launch.contractSnapshot,
     ),
@@ -16221,7 +16236,9 @@ export async function appendPostgresRunLedgerStart(
       runId: input.runId,
       eventId: `run-start-callback:${input.runId}`,
       eventType: 'run.started',
-      payload: stableStringify(input.start),
+      payload: stableStringify(
+        prepareRetainedPlayPipelinesForTransport(input.start),
+      ),
     },
     options,
   );
@@ -18093,6 +18110,7 @@ async function projectPostgresSchedulerCreatedEvent(
   runtimeApi: WorkerRuntimeApiContext,
   event: PostgresSchedulerOutboxEvent,
 ): Promise<void> {
+  event = { ...event, payload: hydrateRetainedPlayPipelines(event.payload) };
   const value = (key: string) => stringPayloadField(event.payload, key);
   const number = (key: string) => numberPayloadField(event.payload, key);
   const raw = (key: string) => payloadField(event.payload, key);
@@ -18153,7 +18171,10 @@ async function projectPostgresSchedulerCreatedEvent(
     runtimeWorkflowName: value('runtimeWorkflowName'),
     runtimeHarnessWorkerName: value('runtimeHarnessWorkerName'),
     maxCreditsPerRun: number('maxCreditsPerRun'),
-    staticPipeline: raw('staticPipeline'),
+    ...retainedPlayPipelineFields(
+      raw('staticPipeline'),
+      event.payload as { retainedPipelineGraph?: unknown },
+    ),
     source: sourcePayloadField(event.payload, 'source'),
     ...(triggerSource === 'api' ||
     triggerSource === 'webhook' ||
@@ -18179,6 +18200,9 @@ async function projectPostgresSchedulerStartEvent(
   event: PostgresSchedulerOutboxEvent,
   launch: (PlaySchedulerSubmitInput & { firstClaimLatencyMs?: number }) | null,
 ): Promise<void> {
+  const payload = hydrateRetainedPlayPipelines(
+    event.payload as Record<string, unknown>,
+  );
   await startRunViaAppRuntime(runtimeApi, {
     deliveryLeaseOwner: event.leaseOwner ?? undefined,
     idempotencyKey: buildRunLedgerStartIdempotencyKey({
@@ -18198,7 +18222,7 @@ async function projectPostgresSchedulerStartEvent(
     schedulerSchema: stringPayloadField(event.payload, 'schedulerSchema'),
     executionProfile: stringPayloadField(event.payload, 'executionProfile'),
     maxCreditsPerRun: numberPayloadField(event.payload, 'maxCreditsPerRun'),
-    staticPipeline: payloadField(event.payload, 'staticPipeline'),
+    ...retainedPlayPipelineFields(payload.staticPipeline, payload),
     source: sourcePayloadField(event.payload, 'source'),
     inputFileId:
       launch?.inputFileId ??
@@ -18619,7 +18643,7 @@ function parseLaunchJson(value: unknown): PlaySchedulerSubmitInput {
       'Postgres scheduler launch_json is missing required fields.',
     );
   }
-  return launch as PlaySchedulerSubmitInput;
+  return hydrateRetainedPlayPipelines(launch as PlaySchedulerSubmitInput);
 }
 
 function parsePostgresSchedulerCronSourcePin(
@@ -18628,7 +18652,9 @@ function parsePostgresSchedulerCronSourcePin(
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('Cron source pin is not an object.');
   }
-  const pin = value as Partial<PostgresSchedulerCronSourcePin>;
+  const pin = hydrateRetainedPlayPipelines(
+    value as Partial<PostgresSchedulerCronSourcePin>,
+  );
   if (
     typeof pin.orgId !== 'string' ||
     typeof pin.playName !== 'string' ||
@@ -18639,6 +18665,7 @@ function parsePostgresSchedulerCronSourcePin(
     throw new Error('Cron source pin is missing required immutable fields.');
   }
   return {
+    ...pin,
     orgId: pin.orgId,
     userId: typeof pin.userId === 'string' ? pin.userId : null,
     playName: pin.playName,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/receipt-gateway.ts

@@ -1,3 +1,4 @@
+import { hydrateRetainedPlayPipelines } from '../../plays/execution-pipeline';
 /**
  * Runtime receipt gateway dispatch.
  *
@@ -866,7 +867,9 @@ export function createReceiptGatewayDispatcher(input: {
         { status: 400 },
       );
     }
-    const body = rawBody as ReceiptGatewayActionBody;
+    const body = hydrateRetainedPlayPipelines(
+      rawBody as ReceiptGatewayActionBody,
+    );
     const scopeError = requireReceiptScope(scope, body);
     if (scopeError) return scopeError;
     const runId = String(body.runId || scope.runId);

package/dist/bundling-sources/shared_libs/plays/execution-pipeline.ts

@@ -1,24 +1,41 @@
+import type { RetainedPipelineCarrier } from './retained-pipeline-graph';
 import type { PlayStaticPipeline } from './static-pipeline';
 import { staticPipelineStorageCodec } from './static-pipeline-storage-codec';
 
+export {
+  retainedPlayPipelineFields,
+  type RetainedPlayContract,
+  type RetainedPipelineCarrier,
+  encodeRetainedPlayPipelines,
+  hydrateRetainedPlayPipelines,
+  prepareRetainedPlayPipelinesForTransport,
+  type RetainedPipelineGraph,
+} from './retained-pipeline-graph';
+
 /**
  * An in-process execution snapshot, deliberately distinct from display graphs
- * and Convex's bounded V1 mirror. Never serialize this wrapper: durable/wire
- * contracts continue to carry the original pipeline fields.
+ * and Convex's bounded V1 mirror. Boundary adapters use the shared retained
+ * contract codec above; JSON serialization of the hydrated pipeline expands
+ * shared child definitions and is not a valid transport.
  */
 export class PlayExecutionPipeline {
   readonly #pipeline: PlayStaticPipeline | null;
 
-  private constructor(pipeline: PlayStaticPipeline | null) {
+  private constructor(
+    pipeline: PlayStaticPipeline | null,
+    readonly retainedPipelineGraph?: unknown,
+  ) {
     this.#pipeline = pipeline;
   }
 
   /** Read the entire storage carrier, so an existing V2 can never be dropped. */
-  static fromStored(record: {
-    staticPipeline?: unknown;
-    staticPipelineV2?: unknown;
-  }): PlayExecutionPipeline {
-    return new PlayExecutionPipeline(staticPipelineStorageCodec.read(record));
+  static fromStored(
+    record: RetainedPipelineCarrier & { staticPipelineV2?: unknown },
+  ): PlayExecutionPipeline {
+    return new PlayExecutionPipeline(
+      staticPipelineStorageCodec.read(record),
+      record.retainedPipelineGraph,
+    );
   }
 
   /** Only for complete compiler/admitted-artifact graphs, never a stored field. */
@@ -58,13 +75,22 @@ export function readPlayExecutionPipeline(
 
 /** Execution readers cannot see (and accidentally forward) the stored mirror. */
 export function readStoredPlayExecutionSnapshot<
-  T extends { staticPipeline?: unknown; staticPipelineV2?: unknown },
+  T extends {
+    staticPipeline?: unknown;
+    staticPipelineV2?: unknown;
+    retainedPipelineGraph?: unknown;
+  },
 >(
   record: T,
-): Omit<T, 'staticPipeline' | 'staticPipelineV2'> & {
+): Omit<T, 'staticPipeline' | 'staticPipelineV2' | 'retainedPipelineGraph'> & {
   executionPipeline: PlayExecutionPipeline;
 } {
-  const { staticPipeline: _v1, staticPipelineV2: _v2, ...metadata } = record;
+  const {
+    staticPipeline: _v1,
+    staticPipelineV2: _v2,
+    retainedPipelineGraph: _graph,
+    ...metadata
+  } = record;
   return {
     ...metadata,
     executionPipeline: PlayExecutionPipeline.fromStored(record),

package/dist/bundling-sources/shared_libs/plays/retained-pipeline-graph.ts

@@ -0,0 +1,291 @@
+/**
+ * Lossless transport for retained execution graphs. A call site remains a
+ * distinct node; equal immutable definition content is stored once. References
+ * are scoped to this envelope, never resolved against a mutable Play registry.
+ *
+ * This is an additive named representation. Readers must be deployed before
+ * WRITE_RETAINED_PIPELINE_GRAPHS is enabled in a separate release.
+ */
+export const WRITE_RETAINED_PIPELINE_GRAPHS = false;
+
+type Scalar = null | boolean | number | string;
+type GraphValue = Scalar | { ref: number };
+type GraphNode = { array: GraphValue[] } | { object: [string, GraphValue][] };
+
+export type RetainedPipelineGraph = {
+  nodes: GraphNode[];
+  roots: Record<string, GraphValue>;
+};
+
+/** The owned execution contract; caller envelopes choose their own adapter. */
+export type RetainedPlayContract = {
+  retainedPipelineGraph?: unknown;
+  staticPipeline?: unknown;
+  authoringContract?: { staticPipeline?: unknown } | null;
+  contractSnapshot?: {
+    staticPipeline?: unknown;
+    authoringContract?: { staticPipeline?: unknown } | null;
+  } | null;
+};
+
+export type RetainedPipelineCarrier = Pick<
+  RetainedPlayContract,
+  'staticPipeline' | 'retainedPipelineGraph'
+>;
+
+// Named roots have fixed meaning. This is not a recursive JSON serializer:
+// customer inputs, checkpoints, runner configs and API responses are not
+// searched for magic property names. Their owners explicitly pass a contract.
+const PIPELINE_ROOT_PATHS = {
+  pipeline: [],
+  authoring: ['authoringContract'],
+  admitted: ['contractSnapshot'],
+  admittedAuthoring: ['contractSnapshot', 'authoringContract'],
+} as const;
+
+function contractAt(input: Record<string, unknown>, path: readonly string[]) {
+  let owner = input;
+  for (const key of path) {
+    if (!record(owner[key])) return undefined;
+    owner = owner[key];
+  }
+  return owner;
+}
+
+function updateContract(
+  input: Record<string, unknown>,
+  path: readonly string[],
+  pipeline: unknown,
+  remove: boolean,
+): Record<string, unknown> {
+  const result = { ...input };
+  let owner = result;
+  for (const key of path) {
+    if (Object.prototype.hasOwnProperty.call(owner, key) && !record(owner[key]))
+      invalid('invalid contract container');
+    const child = record(owner[key]) ? { ...owner[key] } : {};
+    owner[key] = child;
+    owner = child;
+  }
+  if (remove) delete owner.staticPipeline;
+  else owner.staticPipeline = pipeline;
+  return result;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function invalid(detail: string): never {
+  throw new Error(`Invalid retained Play pipeline graph: ${detail}`);
+}
+
+/** Explicit encoder, also used by fixtures before production writer enable. */
+export function encodeRetainedPlayPipelines<T>(input: T): T {
+  if (!record(input)) return input;
+  // Repeated serialization must not expand a previously encoded envelope.
+  const prior =
+    input.retainedPipelineGraph === undefined
+      ? null
+      : readGraph(input.retainedPipelineGraph);
+  const source = prior ? hydrateContractRoots(input, prior.roots) : input;
+  // Retain existing node IDs and all additive graph/node metadata. A reader
+  // that forwards a newer envelope must not rebuild away fields it ignores.
+  const nodes: GraphNode[] = prior
+    ? [...(input.retainedPipelineGraph as RetainedPipelineGraph).nodes]
+    : [];
+  const interned = new Map<string, number>();
+  const objects = new WeakMap<object, number>();
+  const visiting = new WeakSet<object>();
+  const roots: RetainedPipelineGraph['roots'] = prior
+    ? { ...(input.retainedPipelineGraph as RetainedPipelineGraph).roots }
+    : {};
+  for (let id = 0; id < nodes.length; id += 1) {
+    interned.set(JSON.stringify(nodes[id]), id);
+    const value = prior!.values[id];
+    if (value !== null && typeof value === 'object') objects.set(value, id);
+  }
+
+  function encode(value: unknown): GraphValue {
+    if (value === null) return null;
+    if (typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'object') invalid('non-JSON pipeline value');
+    const cached = objects.get(value);
+    if (cached !== undefined) return { ref: cached };
+    if (visiting.has(value)) invalid('cyclic pipeline');
+    visiting.add(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (
+      !Array.isArray(value) &&
+      prototype !== Object.prototype &&
+      prototype !== null
+    ) {
+      invalid('pipeline must contain plain JSON objects');
+    }
+    const node: GraphNode = Array.isArray(value)
+      ? { array: Array.from(value, (entry) => encode(entry ?? null)) }
+      : {
+          object: Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .map(([key, entry]) => [key, encode(entry)]),
+        };
+    // Node signatures contain references, never recursively expanded children.
+    const signature = JSON.stringify(node);
+    let id = interned.get(signature);
+    if (id === undefined) {
+      id = nodes.length;
+      nodes.push(node);
+      interned.set(signature, id);
+    }
+    visiting.delete(value);
+    objects.set(value, id);
+    return { ref: id };
+  }
+
+  let result: Record<string, unknown> = { ...source };
+  for (const [name, path] of Object.entries(PIPELINE_ROOT_PATHS)) {
+    const owner = contractAt(source, path);
+    if (
+      owner &&
+      Object.prototype.hasOwnProperty.call(owner, 'staticPipeline') &&
+      owner.staticPipeline !== undefined
+    ) {
+      roots[name] = encode(owner.staticPipeline);
+      result = updateContract(result, path, undefined, true);
+    }
+  }
+  if (!Object.keys(roots).length) return input;
+  return {
+    ...result,
+    retainedPipelineGraph: {
+      ...(record(input.retainedPipelineGraph)
+        ? input.retainedPipelineGraph
+        : {}),
+      nodes,
+      roots,
+    },
+  } as T;
+}
+
+function readGraph(graph: unknown): {
+  roots: Record<string, unknown>;
+  values: unknown[];
+} {
+  if (!record(graph) || !Array.isArray(graph.nodes) || !record(graph.roots)) {
+    invalid('expected nodes and roots');
+  }
+  const values: unknown[] = [];
+  function decode(value: unknown): unknown {
+    if (
+      value === null ||
+      typeof value === 'string' ||
+      typeof value === 'boolean'
+    )
+      return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (
+      !record(value) ||
+      Object.keys(value).length !== 1 ||
+      !Number.isSafeInteger(value.ref) ||
+      (value.ref as number) < 0 ||
+      (value.ref as number) >= values.length
+    ) {
+      invalid('reference must name a preceding node');
+    }
+    return values[value.ref as number];
+  }
+  for (const node of graph.nodes) {
+    if (!record(node)) invalid('expected node object');
+    if (Array.isArray(node.array) && node.object === undefined) {
+      values.push(node.array.map(decode));
+    } else if (Array.isArray(node.object) && node.array === undefined) {
+      const entries: [string, unknown][] = [];
+      const keys = new Set<string>();
+      for (const entry of node.object) {
+        if (
+          !Array.isArray(entry) ||
+          entry.length !== 2 ||
+          typeof entry[0] !== 'string' ||
+          keys.has(entry[0])
+        ) {
+          invalid('invalid or duplicate object entry');
+        }
+        keys.add(entry[0]);
+        entries.push([entry[0], decode(entry[1])]);
+      }
+      values.push(Object.fromEntries(entries));
+    } else invalid('expected array or object node');
+  }
+  return {
+    roots: Object.fromEntries(
+      Object.entries(graph.roots).map(([name, value]) => [name, decode(value)]),
+    ),
+    values,
+  };
+}
+
+/** Old envelopes pass through unchanged; malformed explicit graphs fail loudly. */
+export function hydrateRetainedPlayPipelines<T>(input: T): T {
+  if (!record(input) || input.retainedPipelineGraph === undefined) return input;
+  return hydrateContractRoots(
+    input,
+    readGraph(input.retainedPipelineGraph).roots,
+  ) as T;
+}
+
+function hydrateContractRoots(
+  input: Record<string, unknown>,
+  roots: Record<string, unknown>,
+): Record<string, unknown> {
+  let result: Record<string, unknown> = { ...input };
+  for (const [name, path] of Object.entries(PIPELINE_ROOT_PATHS)) {
+    if (!Object.prototype.hasOwnProperty.call(roots, name)) continue;
+    const pipeline = roots[name];
+    if (
+      pipeline !== null &&
+      (!record(pipeline) ||
+        !Array.isArray(pipeline.fields) ||
+        !Array.isArray(pipeline.substeps))
+    ) {
+      invalid(`root ${name} must be a complete pipeline or null`);
+    }
+    result = updateContract(result, path, pipeline, false);
+  }
+  return result;
+}
+
+/** Production writers remain inert until the separate reader rollout completes. */
+export function prepareRetainedPlayPipelinesForTransport<T>(input: T): T {
+  // Reader-only builds must preserve new representations when forwarding
+  // them. The rollout switch controls creation from legacy envelopes only.
+  return WRITE_RETAINED_PIPELINE_GRAPHS ||
+    (record(input) && input.retainedPipelineGraph !== undefined)
+    ? encodeRetainedPlayPipelines(input)
+    : input;
+}
+
+/** Project one retained pipeline into a new envelope without losing its format. */
+export function retainedPlayPipelineFields<T>(
+  pipeline: T,
+  source: RetainedPipelineCarrier,
+): { staticPipeline: T; retainedPipelineGraph?: RetainedPipelineGraph } {
+  if (source.retainedPipelineGraph === undefined)
+    return { staticPipeline: pipeline };
+  readGraph(source.retainedPipelineGraph);
+  const graph = source.retainedPipelineGraph as RetainedPipelineGraph;
+  // This is an explicit projection to one pipeline, not a reinterpretation of
+  // the old root. Keep unknown roles and metadata through the projection.
+  const roots = Object.fromEntries(
+    Object.entries(graph.roots).filter(
+      ([name]) =>
+        !Object.prototype.hasOwnProperty.call(PIPELINE_ROOT_PATHS, name),
+    ),
+  );
+  return hydrateRetainedPlayPipelines(
+    encodeRetainedPlayPipelines({
+      staticPipeline: pipeline,
+      retainedPipelineGraph: { ...graph, roots },
+    }),
+  );
+}

package/dist/bundling-sources/shared_libs/plays/static-pipeline-storage-codec.ts

@@ -3,7 +3,58 @@ import {
   createStoredStaticPipelineV2,
   hydrateStoredStaticPipelineV2,
   readStoredStaticPipeline,
+  createStaticPipelineV1CompatibilityProjection,
+  type PlayStaticPipeline,
 } from './static-pipeline';
+import {
+  retainedPlayPipelineFields,
+  encodeRetainedPlayPipelines,
+  hydrateRetainedPlayPipelines,
+  WRITE_RETAINED_PIPELINE_GRAPHS,
+  type RetainedPipelineGraph,
+  type RetainedPipelineCarrier,
+} from './retained-pipeline-graph';
+
+function readExecutionPipeline(
+  record: RetainedPipelineCarrier & { staticPipelineV2?: unknown },
+): PlayStaticPipeline | null {
+  if (record.retainedPipelineGraph !== undefined) {
+    const hydrated = hydrateRetainedPlayPipelines({
+      retainedPipelineGraph: record.retainedPipelineGraph,
+    }) as { staticPipeline?: PlayStaticPipeline | null };
+    if (hydrated.staticPipeline === undefined)
+      throw new Error('Retained execution graph is missing its pipeline root.');
+    return hydrated.staticPipeline;
+  }
+  return readStoredStaticPipeline(record);
+}
+
+/** Runs use the shared graph after all storage readers have been deployed. */
+function executionStorageFields(
+  pipeline: PlayStaticPipeline | null | undefined,
+  carrier?: RetainedPipelineCarrier,
+): {
+  staticPipeline?: PlayStaticPipeline | null;
+  staticPipelineV2?: ReturnType<typeof createStoredStaticPipelineV2>;
+  retainedPipelineGraph?: RetainedPipelineGraph;
+} {
+  if (
+    (!WRITE_RETAINED_PIPELINE_GRAPHS &&
+      carrier?.retainedPipelineGraph === undefined) ||
+    pipeline === undefined
+  ) {
+    return createStaticPipelineStorageFields(pipeline);
+  }
+  const compact = encodeRetainedPlayPipelines(
+    retainedPlayPipelineFields(pipeline, carrier ?? {}),
+  ) as unknown as {
+    retainedPipelineGraph: RetainedPipelineGraph;
+  };
+  return {
+    staticPipeline: createStaticPipelineV1CompatibilityProjection(pipeline),
+    retainedPipelineGraph: compact.retainedPipelineGraph,
+  };
+}
 
 export {
   isStoredStaticPipelineV2IntegrityError,
@@ -23,5 +74,6 @@ export const staticPipelineStorageCodec = Object.freeze({
   flatten: createStoredStaticPipelineV2,
   hydrate: hydrateStoredStaticPipelineV2,
   storageFields: createStaticPipelineStorageFields,
-  read: readStoredStaticPipeline,
+  read: readExecutionPipeline,
+  executionStorageFields,
 });

package/dist/cli/index.js

@@ -3473,7 +3473,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/index.mjs

@@ -3468,7 +3468,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.js

@@ -1286,7 +1286,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.mjs

@@ -1190,7 +1190,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/install-integrity.json

@@ -506,6 +506,7 @@
     "dist/bundling-sources/shared_libs/plays/play-grep-search.ts",
     "dist/bundling-sources/shared_libs/plays/play-reference.ts",
     "dist/bundling-sources/shared_libs/plays/resolve-static-pipeline.ts",
+    "dist/bundling-sources/shared_libs/plays/retained-pipeline-graph.ts",
     "dist/bundling-sources/shared_libs/plays/row-identity.ts",
     "dist/bundling-sources/shared_libs/plays/run-input-summary.ts",
     "dist/bundling-sources/shared_libs/plays/run-summary-types.ts",

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.243";
+    readonly version: "0.3.244";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.243";
+    readonly version: "0.3.244";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.243",
+  version: "0.3.244",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.243",
+  "version": "0.3.244",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",