deepline 0.3.227 → 0.3.229

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

@@ -93,7 +93,6 @@ import {
 } from '../log-provenance';
 import {
   buildRunLedgerEventsIdempotencyKey,
-  isRunLedgerProjectionChunk,
   RunLedgerProjectionLeaseLostError,
   type RunLedgerProjectionChunk,
   type RunLedgerProjectionLeaseLostReason,
@@ -101,8 +100,8 @@ import {
   buildRunLedgerStartIdempotencyKey,
   buildRunLedgerTerminalIdempotencyKey,
 } from '../run-ledger-projection-contract';
-import { runLedgerProjectionMismatch } from '../run-ledger-projection-diagnostics';
-import { selectRunEventsForAppRuntimeProjectionChunk } from '../run-ledger-event-transport';
+import { runLedgerProjectionMismatchAcrossCandidates } from '../run-ledger-projection-diagnostics';
+import { runEventsForAppRuntimeProjectionCandidates } from '../run-ledger-event-transport';
 import {
   assertTerminalRunResultWithinLimit,
   isLedgerTerminalResultRef,
@@ -16106,32 +16105,22 @@ export async function assertPostgresRunLedgerDelivery(
           }),
         );
       }
-      let expectedProjectionEvents:
-        | readonly (AcceptedPlayRunLedgerEvent | PlayRunLedgerIngressEvent)[]
-        | undefined;
-      if (input.projectionChunk) {
-        const chunk = input.projectionChunk;
-        // The sender partitions ingress events before the route sanitizes each chunk.
-        const expectedTransportChunk = isRunLedgerProjectionChunk(chunk)
-          ? selectRunEventsForAppRuntimeProjectionChunk(prefixEvents, chunk)
-          : undefined;
-        expectedProjectionEvents =
-          expectedTransportChunk === undefined
-            ? undefined
+      const expectedProjectionCandidates =
+        runEventsForAppRuntimeProjectionCandidates(
+          prefixEvents,
+          input.projectionChunk,
+        ).map((candidate) =>
+          candidate === null
+            ? null
             : input.sanitizeExpectedProjectionEvents
-              ? input.sanitizeExpectedProjectionEvents(expectedTransportChunk)
-              : expectedTransportChunk;
-      } else {
-        expectedProjectionEvents = input.sanitizeExpectedProjectionEvents
-          ? input.sanitizeExpectedProjectionEvents(prefixEvents)
-          : prefixEvents;
-      }
-      const projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null =
-        runLedgerProjectionMismatch({
-          projectedEvents: input.projectedEvents,
-          expectedEvents: expectedProjectionEvents ?? null,
-          ...(input.projectionChunk ? { chunk: input.projectionChunk } : {}),
-        });
+              ? input.sanitizeExpectedProjectionEvents(candidate)
+              : candidate,
+        );
+      const projectionMismatch = runLedgerProjectionMismatchAcrossCandidates({
+        projectedEvents: input.projectedEvents,
+        expectedEventCandidates: expectedProjectionCandidates,
+        ...(input.projectionChunk ? { chunk: input.projectionChunk } : {}),
+      });
       if (projectionMismatch === null) return;
       throw new RunLedgerProjectionLeaseLostError(
         'projected_events_mismatch',

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -1767,6 +1767,7 @@ function createDatasetFromSerializedToolList(
     residentRows: isPartialPreview ? null : sourceRows,
     sourceLabel: serialized.sourceLabel ?? null,
     tableNamespace: serialized.tableNamespace ?? null,
+    columnTypes: serialized.columnTypes,
     workProgress: serialized._metadata?.workProgress,
     resolvers: {
       count: async () => serialized.count,

package/dist/bundling-sources/shared_libs/plays/dataset.ts

@@ -1,4 +1,5 @@
 import type { PlayExecutionFileRef } from './file-refs';
+import type { PlayDatasetColumnTypes } from '../play-data-plane/contracts';
 
 const PLAY_DATASET_BRAND = Symbol.for('deepline.play.dataset');
 const NODE_INSPECT_CUSTOM = Symbol.for('nodejs.util.inspect.custom');
@@ -47,6 +48,7 @@ export interface SerializedPlayDataset<T> {
   sourceLabel?: string | null;
   tableNamespace?: string | null;
   columns?: string[];
+  columnTypes?: PlayDatasetColumnTypes;
   _metadata?: {
     workProgress?: PlayDatasetWorkProgressSummary;
   };
@@ -107,8 +109,7 @@ export type PlayDatasetTransformOptions = {
  * `materialize(limit)` or async iteration only when the dataset is intentionally
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
  * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
- * those hide the runtime cost of loading persisted rows into memory or make
- * behavior depend on whether rows happen to be resident.
+ * these hide loading costs or make behavior depend on row residency.
  *
  * @sdkReference runtime 190
  */
@@ -124,6 +125,8 @@ export interface PlayDataset<T> extends AsyncIterable<T> {
   readonly sourceLabel?: string | null;
   /** Runtime table name. */
   readonly tableNamespace?: string | null;
+  /** Advisory source types; transformed fields must infer from their values. */
+  readonly columnTypes?: PlayDatasetColumnTypes;
   /** Row count. */
   count(): Promise<number>;
   /** Preview rows. */
@@ -161,6 +164,7 @@ export interface PlayDataset<T> extends AsyncIterable<T> {
     sourceLabel?: string | null;
     tableNamespace?: string | null;
     columns?: string[];
+    columnTypes?: PlayDatasetColumnTypes;
     _metadata?: {
       workProgress?: PlayDatasetWorkProgressSummary;
     };
@@ -335,6 +339,7 @@ export function deserializePlayDatasetCell<T>(
     residentRows: rows,
     sourceLabel: dataset.sourceLabel ?? null,
     tableNamespace: dataset.tableNamespace ?? null,
+    columnTypes: dataset.columnTypes,
     workProgress: dataset._metadata?.workProgress,
     resolvers: {
       count: async () => rows.length,
@@ -374,6 +379,7 @@ export function deserializeLegacyPlayDataset<T>(
     residentRows: complete ? rows : null,
     sourceLabel: dataset.sourceLabel ?? null,
     tableNamespace: dataset.tableNamespace ?? null,
+    columnTypes: dataset.columnTypes,
     workProgress: dataset._metadata?.workProgress,
     resolvers: {
       count: async () => dataset.count,
@@ -417,6 +423,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
   readonly backing?: PlayDatasetBacking;
   readonly sourceLabel?: string | null;
   readonly tableNamespace?: string | null;
+  readonly columnTypes?: PlayDatasetColumnTypes;
   private readonly previewRows: readonly T[];
   private readonly previewColumns?: string[];
   private readonly workProgress?: PlayDatasetWorkProgressSummary;
@@ -435,6 +442,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     residentRows?: readonly T[] | null;
     sourceLabel?: string | null;
     tableNamespace?: string | null;
+    columnTypes?: PlayDatasetColumnTypes;
     workProgress?: PlayDatasetWorkProgressSummary;
     resolvers: PlayDatasetResolvers<T>;
   }) {
@@ -449,6 +457,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     this.previewColumns = inferPreviewColumns(this.previewRows);
     this.sourceLabel = input.sourceLabel ?? null;
     this.tableNamespace = input.tableNamespace ?? null;
+    this.columnTypes = input.columnTypes;
     this.workProgress = input.workProgress;
     this.resolvers = input.resolvers;
   }
@@ -592,6 +601,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
       ...(this.sourceLabel ? { sourceLabel: this.sourceLabel } : {}),
       ...(this.tableNamespace ? { tableNamespace: this.tableNamespace } : {}),
       ...(this.previewColumns ? { columns: this.previewColumns } : {}),
+      ...(this.columnTypes ? { columnTypes: this.columnTypes } : {}),
       ...(this.workProgress
         ? { _metadata: { workProgress: this.workProgress } }
         : {}),
@@ -721,6 +731,7 @@ function createTransformedPlayDataset<T, U>(
     backing: source.backing,
     sourceLabel,
     tableNamespace: options?.key ?? null,
+    columnTypes: transform.kind === 'map' ? undefined : source.columnTypes,
     resolvers: {
       count,
       peek: async (limit) => collect(limit),
@@ -747,6 +758,7 @@ export function createDeferredPlayDataset<T>(input: {
   residentRows?: readonly T[] | null;
   sourceLabel?: string | null;
   tableNamespace?: string | null;
+  columnTypes?: PlayDatasetColumnTypes;
   workProgress?: PlayDatasetWorkProgressSummary;
   resolvers: PlayDatasetResolvers<T>;
 }): PlayDataset<T> {
@@ -835,6 +847,7 @@ export function createPlayDataset<T>(
     sourceLabel?: string | null;
     tableNamespace?: string | null;
     datasetId?: string;
+    columnTypes?: PlayDatasetColumnTypes;
   },
 ): PlayDataset<T> {
   // Test/dev helper only. Production play execution should construct
@@ -850,6 +863,7 @@ export function createPlayDataset<T>(
     residentRows: materializedRows,
     sourceLabel: metadata?.sourceLabel ?? null,
     tableNamespace: metadata?.tableNamespace ?? null,
+    columnTypes: metadata?.columnTypes,
     resolvers: {
       count: async () => materializedRows.length,
       peek: async (limit) => materializedRows.slice(0, Math.max(0, limit)),

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

@@ -0,0 +1,72 @@
+import type { PlayStaticPipeline } from './static-pipeline';
+import { staticPipelineStorageCodec } from './static-pipeline-storage-codec';
+
+/**
+ * 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.
+ */
+export class PlayExecutionPipeline {
+  readonly #pipeline: PlayStaticPipeline | null;
+
+  private constructor(pipeline: PlayStaticPipeline | null) {
+    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));
+  }
+
+  /** Only for complete compiler/admitted-artifact graphs, never a stored field. */
+  static fromAdmitted(pipeline: unknown): PlayExecutionPipeline {
+    if (
+      pipeline != null &&
+      (typeof pipeline !== 'object' ||
+        !('fields' in pipeline) ||
+        !Array.isArray(pipeline.fields) ||
+        !('substeps' in pipeline) ||
+        !Array.isArray(pipeline.substeps))
+    ) {
+      throw new Error('Invalid Play execution pipeline snapshot.');
+    }
+    // Do not compile or normalize retained contracts under current authoring
+    // rules. In particular, preserve additive fields and historical contracts.
+    return new PlayExecutionPipeline(
+      (pipeline as PlayStaticPipeline | null | undefined) ?? null,
+    );
+  }
+
+  get pipeline(): PlayStaticPipeline | null {
+    return this.#pipeline;
+  }
+}
+
+/** Reject accidental raw/serialized inputs before launch has side effects. */
+export function readPlayExecutionPipeline(
+  snapshot: PlayExecutionPipeline | undefined,
+): PlayStaticPipeline | null {
+  if (snapshot === undefined) return null;
+  if (!(snapshot instanceof PlayExecutionPipeline)) {
+    throw new Error('Play launch requires a PlayExecutionPipeline snapshot.');
+  }
+  return snapshot.pipeline;
+}
+
+/** Execution readers cannot see (and accidentally forward) the stored mirror. */
+export function readStoredPlayExecutionSnapshot<
+  T extends { staticPipeline?: unknown; staticPipelineV2?: unknown },
+>(
+  record: T,
+): Omit<T, 'staticPipeline' | 'staticPipelineV2'> & {
+  executionPipeline: PlayExecutionPipeline;
+} {
+  const { staticPipeline: _v1, staticPipelineV2: _v2, ...metadata } = record;
+  return {
+    ...metadata,
+    executionPipeline: PlayExecutionPipeline.fromStored(record),
+  };
+}

package/dist/bundling-sources/shared_libs/plays/launch/prepare.ts

@@ -61,7 +61,6 @@ export function buildPlayRunContractSnapshot(input: {
   artifactStorageKey: string;
   artifact: Pick<PlayBundleArtifact, 'compatibility'>;
   validatedSnapshot: PlayRunLaunchValidationSnapshot;
-  transportStaticPipeline?: unknown;
 }): PreparedPlayRunContractSnapshot {
   // The runtime backend is launch infrastructure, not an artifact contract.
   // Copy the admitted artifact compatibility so resumed work cannot acquire
@@ -69,8 +68,7 @@ export function buildPlayRunContractSnapshot(input: {
   const compatibility = normalizePlayContractCompatibility(
     input.artifact.compatibility,
   );
-  const staticPipeline =
-    input.transportStaticPipeline ?? input.validatedSnapshot.staticPipeline;
+  const staticPipeline = input.validatedSnapshot.staticPipeline;
   return {
     source: input.source ?? 'published',
     revisionVersion: null,

package/dist/bundling-sources/shared_libs/plays/sheet-filter.ts

@@ -1,14 +1,13 @@
 // Full-table view basic filters. A tiny, deliberately closed predicate model
 // that compiles mechanically to a parameterized SQL WHERE clause against a
-// runtime sheet's physical (jsonb) user-data columns.
+// runtime sheet's physical user-data columns.
 //
 // This is NOT free-text SQL: operators come from a closed enum, columns must
 // be on a caller-supplied allowlist (the sheet's real columns), and every value
 // is bound as a query parameter. Multiple filters AND together. No OR groups.
 //
-// Sheet user-data columns are stored one-per-column as `jsonb` (a JSON scalar
-// like "completed", 19991, or an object). `col #>> '{}'` extracts the scalar as
-// text; numeric comparisons cast that text to numeric.
+// Sheet user-data columns may be native scalars or JSONB. Normalize each cell
+// through to_jsonb before applying the shared scalar and numeric predicates.
 
 // ── The operator set, and why it grew ────────────────────────────────────────
 //
@@ -204,7 +203,7 @@ function coerceFilterNumber(value: unknown, index: number): number {
 // → 19991, an object → its JSON text. The single-arg `#>> '{}'` path returns the
 // whole value as text (Postgres jsonb → text).
 function columnAsText(quotedColumn: string): string {
-  return `(${quotedColumn} #>> '{}')`;
+  return `(to_jsonb(${quotedColumn}) #>> '{}')`;
 }
 
 function quoteIdentifier(value: string): string {
@@ -302,9 +301,10 @@ export function compileSheetFilterWhere(input: {
         const num = coerceFilterNumber(filter.value, index);
         const sqlOp = NUMERIC_SQL_OPERATOR[filter.op];
         // Guard the numeric cast to jsonb numbers only, so a stray non-numeric
-        // cell can never abort the whole query with a cast error.
+        // cell can never abort the whole query with a cast error. CASE also
+        // prevents PostgreSQL from reordering a numeric cast before its guard.
         clauses.push(
-          `(jsonb_typeof(${quoted}) = 'number' AND ${asText}::numeric ${sqlOp} $${paramIdx})`,
+          `((CASE WHEN jsonb_typeof(to_jsonb(${quoted})) = 'number' THEN ${asText}::numeric END) ${sqlOp} $${paramIdx})`,
         );
         params.push(num);
         paramIdx += 1;
@@ -317,12 +317,8 @@ export function compileSheetFilterWhere(input: {
         // range control means by it. The guard is the same one the scalar
         // comparisons use: a non-numeric cell simply does not match, rather
         // than aborting the query on a cast.
-        const body = `${asText}::numeric BETWEEN $${paramIdx} AND $${paramIdx + 1}`;
-        clauses.push(
-          `(jsonb_typeof(${quoted}) = 'number' AND ${
-            filter.op === 'between' ? body : `NOT (${body})`
-          })`,
-        );
+        const body = `(CASE WHEN jsonb_typeof(to_jsonb(${quoted})) = 'number' THEN ${asText}::numeric END) BETWEEN $${paramIdx} AND $${paramIdx + 1}`;
+        clauses.push(`(${filter.op === 'between' ? body : `NOT (${body})`})`);
         params.push(min, max);
         paramIdx += 2;
         break;

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

@@ -1,5 +1,15 @@
 import { normalizeTableNamespace } from './row-identity';
 import { sqlSafePlayColumnName } from '../play-data-plane/column-names';
+import type {
+  PlaySheetColumnSource,
+  PlaySheetColumnContract,
+  PlaySheetContract,
+} from '../play-data-plane/contracts';
+export type {
+  PlaySheetColumnSource,
+  PlaySheetColumnContract,
+  PlaySheetContract,
+} from '../play-data-plane/contracts';
 import type { PlayDocflow } from './docflow';
 
 export { sqlSafePlayColumnName };
@@ -144,32 +154,6 @@ export function deriveStaticPipelineEntryInputFields(
     : dedupeStaticFieldNames(pipeline.inputFields ?? []);
 }
 
-export type PlaySheetColumnSource =
-  | 'input'
-  | 'datasetColumn'
-  | 'waterfallStep'
-  | 'childPlayColumn';
-
-export interface PlaySheetColumnContract {
-  id: string;
-  sqlName: string;
-  source: PlaySheetColumnSource;
-  field?: string;
-  parentField?: string;
-  playId?: string;
-  waterfallId?: string;
-  outputField?: string;
-  outputSqlName?: string;
-  stepId?: string;
-  toolId?: string;
-  isRowKey?: boolean;
-}
-
-export interface PlaySheetContract {
-  tableNamespace: string;
-  columns: PlaySheetColumnContract[];
-}
-
 export type PlayStaticColumnProducerKind =
   | 'tool'
   | 'waterfall'
@@ -339,13 +323,15 @@ function truncateStaticControlFlowBranchesForStorage(
     maxEmbeddedPlayCallPipelineDepth: number;
     maxStoredSubstepDepth: number;
     storedSubstepDepth: number;
+    preserveAdditiveMetadata: boolean;
   },
 ): PlayStaticControlFlowBranch[] | undefined {
   if (!branches) return undefined;
   return branches.map((branch) =>
     omitUndefinedProperties({
-      label: branch.label,
-      condition: branch.condition,
+      ...(input.preserveAdditiveMetadata
+        ? branch
+        : { label: branch.label, condition: branch.condition }),
       steps: truncateStaticSubstepsForStorage(
         branch.steps,
         nextStoredSubstepInput(input),
@@ -359,6 +345,7 @@ function nextStoredSubstepInput(input: {
   maxEmbeddedPlayCallPipelineDepth: number;
   maxStoredSubstepDepth: number;
   storedSubstepDepth: number;
+  preserveAdditiveMetadata: boolean;
 }) {
   return {
     ...input,
@@ -392,6 +379,7 @@ function truncateStaticSubstepsForStorage(
     maxEmbeddedPlayCallPipelineDepth: number;
     maxStoredSubstepDepth: number;
     storedSubstepDepth: number;
+    preserveAdditiveMetadata: boolean;
   },
 ): PlayStaticSubstep[] {
   return (substeps ?? []).map((substep) => {
@@ -431,6 +419,7 @@ function truncateStaticSubstepsForStorage(
                 input.embeddedPlayCallPipelineDepth + 1,
               maxStoredSubstepDepth: input.maxStoredSubstepDepth,
               storedSubstepDepth: input.storedSubstepDepth + 1,
+              preserveAdditiveMetadata: input.preserveAdditiveMetadata,
             })
           : nestedPipeline;
     }
@@ -479,9 +468,9 @@ function truncateStaticSubstepsForStorage(
         ...base,
         steps: base.steps?.map((step) =>
           omitUndefinedProperties({
-            id: step.id,
-            kind: step.kind,
-            toolId: step.toolId,
+            ...(input.preserveAdditiveMetadata
+              ? step
+              : { id: step.id, kind: step.kind, toolId: step.toolId }),
           }),
         ),
       });
@@ -551,6 +540,7 @@ function truncateStaticSubstepsForStorage(
         embeddedPlayCallPipelineDepth: input.embeddedPlayCallPipelineDepth + 1,
         maxStoredSubstepDepth: input.maxStoredSubstepDepth,
         storedSubstepDepth: input.storedSubstepDepth + 1,
+        preserveAdditiveMetadata: input.preserveAdditiveMetadata,
       }),
     });
   });
@@ -563,6 +553,8 @@ export function truncateStaticPipelineForStorage(
     embeddedPlayCallPipelineDepth?: number;
     maxStoredSubstepDepth?: number;
     storedSubstepDepth?: number;
+    /** Keep retained additive metadata only in the full runtime contract. */
+    preserveAdditiveMetadata?: boolean;
   } = {},
 ): PlayStaticPipeline | null | undefined {
   if (!pipeline) {
@@ -576,6 +568,7 @@ export function truncateStaticPipelineForStorage(
   const maxStoredSubstepDepth =
     options.maxStoredSubstepDepth ?? DEFAULT_MAX_STORED_SUBSTEP_DEPTH;
   const storedSubstepDepth = options.storedSubstepDepth ?? 0;
+  const preserveAdditiveMetadata = options.preserveAdditiveMetadata ?? false;
 
   return stripUndefinedDeep(
     omitUndefinedProperties({
@@ -593,12 +586,14 @@ export function truncateStaticPipelineForStorage(
         maxEmbeddedPlayCallPipelineDepth,
         maxStoredSubstepDepth,
         storedSubstepDepth,
+        preserveAdditiveMetadata,
       }),
       substeps: truncateStaticSubstepsForStorage(pipeline.substeps, {
         embeddedPlayCallPipelineDepth,
         maxEmbeddedPlayCallPipelineDepth,
         maxStoredSubstepDepth,
         storedSubstepDepth,
+        preserveAdditiveMetadata,
       }),
       sheetContract: cloneStorageSafeSheetContract(pipeline.sheetContract),
       sheetContractErrors: pipeline.sheetContractErrors
@@ -615,6 +610,8 @@ export function truncateStaticPipelineForRuntimeContract(
     // Runtime admission must preserve every dataset contract. The caller's
     // serialized artifact-size budget is the bound; a UI depth cap is not.
     maxStoredSubstepDepth: Number.POSITIVE_INFINITY,
+    maxEmbeddedPlayCallPipelineDepth: Number.POSITIVE_INFINITY,
+    preserveAdditiveMetadata: true,
   });
 }
 

package/dist/cli/index.js

@@ -3051,7 +3051,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.227",
+  version: "0.3.229",
   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

@@ -3046,7 +3046,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.227",
+  version: "0.3.229",
   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/{compiler-manifest-Dpd2hEet.d.mts → compiler-manifest-n8ZtPv2h.d.mts}

@@ -220,6 +220,33 @@ interface PlayR2FileRef {
 }
 type PlayExecutionFileRef = PlayR2FileRef;
 
+/** Source evidence is advisory; stored values determine lossless SQL encoding. */
+interface PlayDatasetColumnTypeEvidence {
+    postgresTypeId: number;
+    valueType: 'boolean' | 'number' | 'string' | 'json';
+}
+type PlayDatasetColumnTypes = Record<string, PlayDatasetColumnTypeEvidence>;
+type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
+interface PlaySheetColumnContract {
+    id: string;
+    sqlName: string;
+    source: PlaySheetColumnSource;
+    field?: string;
+    parentField?: string;
+    playId?: string;
+    waterfallId?: string;
+    outputField?: string;
+    outputSqlName?: string;
+    stepId?: string;
+    toolId?: string;
+    isRowKey?: boolean;
+    typeEvidence?: PlayDatasetColumnTypeEvidence;
+}
+interface PlaySheetContract {
+    tableNamespace: string;
+    columns: PlaySheetColumnContract[];
+}
+
 declare const PLAY_DATASET_BRAND: unique symbol;
 type PlayDatasetKind = 'csv' | 'map';
 type PlayDatasetBacking = {
@@ -265,8 +292,7 @@ type PlayDatasetTransformOptions = {
  * `materialize(limit)` or async iteration only when the dataset is intentionally
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
  * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
- * those hide the runtime cost of loading persisted rows into memory or make
- * behavior depend on whether rows happen to be resident.
+ * these hide loading costs or make behavior depend on row residency.
  *
  * @sdkReference runtime 190
  */
@@ -282,6 +308,8 @@ interface PlayDataset<T> extends AsyncIterable<T> {
     readonly sourceLabel?: string | null;
     /** Runtime table name. */
     readonly tableNamespace?: string | null;
+    /** Advisory source types; transformed fields must infer from their values. */
+    readonly columnTypes?: PlayDatasetColumnTypes;
     /** Row count. */
     count(): Promise<number>;
     /** Preview rows. */
@@ -309,6 +337,7 @@ interface PlayDataset<T> extends AsyncIterable<T> {
         sourceLabel?: string | null;
         tableNamespace?: string | null;
         columns?: string[];
+        columnTypes?: PlayDatasetColumnTypes;
         _metadata?: {
             workProgress?: PlayDatasetWorkProgressSummary;
         };
@@ -2983,25 +3012,6 @@ interface PlayStaticPipeline {
     sheetContract?: PlaySheetContract | null;
     sheetContractErrors?: string[];
 }
-type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
-interface PlaySheetColumnContract {
-    id: string;
-    sqlName: string;
-    source: PlaySheetColumnSource;
-    field?: string;
-    parentField?: string;
-    playId?: string;
-    waterfallId?: string;
-    outputField?: string;
-    outputSqlName?: string;
-    stepId?: string;
-    toolId?: string;
-    isRowKey?: boolean;
-}
-interface PlaySheetContract {
-    tableNamespace: string;
-    columns: PlaySheetColumnContract[];
-}
 type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
 interface PlayStaticColumnProducer {
     id: string;