deepline 0.1.319 → 0.1.320

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

@@ -1862,7 +1862,9 @@ function attachSdkQueryResultDatasetResult(
   }
   const datasetLimit =
     finitePositiveInteger(dataset.returned_limit) ?? totalRows;
-  const previewRows = rowsFromUnknown(raw?.rows).slice(0, 25);
+  const effectiveCount = Math.min(totalRows, datasetLimit);
+  const rawRows = rowsFromUnknown(raw?.rows);
+  const previewRows = rawRows.slice(0, 25);
   const fetchPage = async (
     offset: number,
     limit: number,
@@ -1927,10 +1929,15 @@ function attachSdkQueryResultDatasetResult(
     datasetId: `sdk-tool-list:${toolId}:${stableHash(datasetScope)}:${datasetLimit}:${safeNonce}`,
     count: Math.min(totalRows, datasetLimit),
     previewRows,
+    residentRows:
+      rawRows.length >= effectiveCount
+        ? rawRows.slice(0, effectiveCount)
+        : null,
     sourceLabel: 'query result rows',
     tableNamespace: null,
     resolvers: {
       count: async () => Math.min(totalRows, datasetLimit),
+      at: async (index) => (await fetchPage(index, 1))[0],
       peek: async (limit) => collectRows(limit),
       materialize: async (limit) => collectRows(limit),
       iterate: () =>

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

@@ -157,7 +157,7 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.319',
+  version: '0.1.320',
   contracts: {
     api: {
       name: 'sdk-http-api',

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

@@ -3658,6 +3658,7 @@ export class PlayContextImpl {
     const originalRequestInput = requestInput as Record<string, unknown>;
     const datasetLimit =
       finitePositiveInteger(dataset.returned_limit) ?? totalRows;
+    const effectiveCount = Math.min(totalRows, datasetLimit);
     const previewRows = rows.slice(0, Math.min(rows.length, 25));
     const executionNonce =
       typeof wrapped.job_id === 'string' && wrapped.job_id.trim()
@@ -3718,12 +3719,15 @@ export class PlayContextImpl {
     const playDataset = createDeferredPlayDataset({
       datasetKind: 'csv',
       datasetId,
-      count: Math.min(totalRows, datasetLimit),
+      count: effectiveCount,
       previewRows,
+      residentRows:
+        rows.length >= effectiveCount ? rows.slice(0, effectiveCount) : null,
       sourceLabel: 'query result rows',
       tableNamespace: null,
       resolvers: {
         count: async () => Math.min(totalRows, datasetLimit),
+        at: async (index) => (await fetchPage(index, 1))[0],
         peek: async (limit) => collectRows(limit),
         materialize: async (limit) => collectRows(limit),
         iterate: () =>
@@ -4803,6 +4807,10 @@ export class PlayContextImpl {
           },
         },
         previewRows,
+        residentRows:
+          immediateMaterializedRows.length === successfulCount
+            ? immediateMaterializedRows
+            : null,
         tableNamespace: resolvedTableNamespace,
         workProgress: {
           total: totalInputCount,
@@ -5417,6 +5425,7 @@ export class PlayContextImpl {
       previewRows: results
         .slice(0, 5)
         .map((row) => this.toMaterializedOutputRow(row)),
+      residentRows: terminalRows,
       tableNamespace: resolvedTableNamespace,
       workProgress: {
         total: totalInputCount,

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

@@ -8139,7 +8139,8 @@ export function createRuntimeBackedPlayDataset(input: {
 }): PlayDataset<Record<string, unknown>> {
   const csvRows =
     input.datasetKind === 'csv' &&
-    (input.initialPreviewRows?.length ?? 0) >= (input.initialCount ?? 0)
+    typeof input.initialCount === 'number' &&
+    (input.initialPreviewRows?.length ?? 0) >= input.initialCount
       ? [...(input.initialPreviewRows ?? [])]
       : null;
   if (csvRows) {
@@ -8151,6 +8152,7 @@ export function createRuntimeBackedPlayDataset(input: {
       ),
       count: input.initialCount ?? csvRows.length,
       previewRows: csvRows.slice(0, 10),
+      residentRows: csvRows,
       sourceLabel: input.sourceLabel ?? null,
       resolvers: {
         count: async () => csvRows.length,
@@ -8181,6 +8183,7 @@ export function createRuntimeBackedPlayDataset(input: {
       input.tableNamespace,
     ),
     count: input.initialCount ?? 0,
+    knownCount: input.initialCount ?? null,
     backing: {
       storage: 'neon_sheet',
       sheet: {
@@ -8222,6 +8225,22 @@ export function createRuntimeBackedPlayDataset(input: {
         );
         return rows.map((row) => row.data);
       },
+      at: async (index) => {
+        const session = await getRuntimeDbSession(runtimeContext, {
+          tableNamespace: input.tableNamespace,
+          logicalTable: 'sheet_rows',
+          operations: ['rows.read'],
+        });
+        const rows = await readRuntimeRows(
+          requireRuntimePostgresSession(session),
+          {
+            limit: 1,
+            offset: index,
+            runId: input.runId ?? null,
+          },
+        );
+        return rows[0]?.data;
+      },
       materialize: async (limit) => {
         const pageSize = 1000;
         const materialized: Record<string, unknown>[] = [];

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

@@ -42,6 +42,7 @@ import {
   createDeferredPlayDataset,
   createPlayDataset,
   isSerializedPlayDataset,
+  residentPlayDatasetRows,
   trimSerializedPlayDatasetPreview,
   type PlayDataset,
   type SerializedPlayDataset,
@@ -1395,6 +1396,15 @@ function serializedListRowsFromResult(input: {
   ]);
   const entries = [...names].flatMap((name) => {
     const dataset = input.listDatasets?.[name];
+    const liveDataset = input.value.extractedLists[name]?.get();
+    const residentRows = liveDataset
+      ? residentPlayDatasetRows(liveDataset)
+      : null;
+    if (residentRows && (!dataset || residentRows.length >= dataset.count)) {
+      return [
+        [name, [...residentRows] as Array<Record<string, unknown>>] as const,
+      ];
+    }
     const preservedRows = preserved?.[name];
     if (preservedRows && (!dataset || preservedRows.length >= dataset.count)) {
       return [[name, preservedRows]] as const;
@@ -1509,6 +1519,7 @@ function createDatasetFromSerializedToolList(
     count: serialized.count,
     backing: serialized.backing,
     previewRows: preview,
+    residentRows: isPartialPreview ? null : sourceRows,
     sourceLabel: serialized.sourceLabel ?? null,
     tableNamespace: serialized.tableNamespace ?? null,
     workProgress: serialized._metadata?.workProgress,

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

@@ -2,6 +2,7 @@ import type { PlayExecutionFileRef } from './file-refs';
 
 const PLAY_DATASET_BRAND = Symbol.for('deepline.play.dataset');
 const NODE_INSPECT_CUSTOM = Symbol.for('nodejs.util.inspect.custom');
+const residentRowsByDataset = new WeakMap<object, readonly unknown[]>();
 const DEFAULT_MATERIALIZE_LIMIT = 10_000;
 export const PLAY_DATASET_EXECUTION_PAGE_ROWS = 1_000;
 export const PLAY_DATASET_EXECUTION_PAGE_BYTES = 64 * 1024 * 1024;
@@ -109,8 +110,12 @@ export type PlayDatasetTransformOptions = {
  *
  * @sdkReference runtime 190
  */
-export interface PlayDataset<T> extends AsyncIterable<T> {
+export interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
   readonly [PLAY_DATASET_BRAND]: true;
+  /** Authoritative row count when known without I/O. */
+  readonly length: number;
+  /** Resident row access. Throws when the requested row requires I/O. */
+  readonly [index: number]: T;
   /** Dataset kind. */
   readonly datasetKind: PlayDatasetKind;
   /** Dataset id. */
@@ -125,6 +130,10 @@ export interface PlayDataset<T> extends AsyncIterable<T> {
   count(): Promise<number>;
   /** Preview rows. */
   peek(limit?: number): Promise<T[]>;
+  /** First row, loading it asynchronously when necessary. */
+  first(): Promise<T | undefined>;
+  /** Row at an array-style index, loading it asynchronously when necessary. */
+  at(index: number): Promise<T | undefined>;
   map<U>(
     mapper: (row: T, index: number) => U | Promise<U>,
     options?: PlayDatasetTransformOptions,
@@ -164,6 +173,7 @@ export interface PlayDataset<T> extends AsyncIterable<T> {
 type PlayDatasetResolvers<T> = {
   count: () => Promise<number>;
   peek: (limit: number) => Promise<T[]>;
+  at?: (index: number) => Promise<T | undefined>;
   materialize: (limit?: number) => Promise<T[]>;
   materializeFullPersistedDataset?: (limit?: number) => Promise<T[]>;
   iterate: () => AsyncIterable<T>;
@@ -223,6 +233,13 @@ export function isPlayDataset<T>(value: unknown): value is PlayDataset<T> {
   );
 }
 
+/** Internal compatibility view for preserving proven-complete rows on replay. */
+export function residentPlayDatasetRows<T>(
+  dataset: PlayDataset<T>,
+): readonly T[] | null {
+  return (residentRowsByDataset.get(dataset as object) as readonly T[]) ?? null;
+}
+
 export function isSerializedPlayDataset<T>(
   value: unknown,
 ): value is SerializedPlayDataset<T> {
@@ -317,6 +334,7 @@ export function deserializePlayDatasetCell<T>(
     count: rows.length,
     backing: dataset.backing,
     previewRows: rows.slice(0, 10),
+    residentRows: rows,
     sourceLabel: dataset.sourceLabel ?? null,
     tableNamespace: dataset.tableNamespace ?? null,
     workProgress: dataset._metadata?.workProgress,
@@ -355,6 +373,7 @@ export function deserializeLegacyPlayDataset<T>(
     count: dataset.count,
     backing: dataset.backing,
     previewRows: rows,
+    residentRows: complete ? rows : null,
     sourceLabel: dataset.sourceLabel ?? null,
     tableNamespace: dataset.tableNamespace ?? null,
     workProgress: dataset._metadata?.workProgress,
@@ -394,6 +413,7 @@ export function trimSerializedPlayDatasetPreview<T>(
 }
 
 class DeferredPlayDataset<T> implements PlayDataset<T> {
+  readonly [index: number]: T;
   readonly [PLAY_DATASET_BRAND] = true as const;
   readonly datasetKind: PlayDatasetKind;
   readonly datasetId: string;
@@ -404,14 +424,18 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
   private readonly previewColumns?: string[];
   private readonly workProgress?: PlayDatasetWorkProgressSummary;
   private cachedCount: number;
+  private knownCount: number | null;
+  private readonly residentRows: readonly T[] | null;
   private readonly resolvers: PlayDatasetResolvers<T>;
 
   constructor(input: {
     datasetKind: PlayDatasetKind;
     datasetId: string;
     count: number;
+    knownCount?: number | null;
     backing?: PlayDatasetBacking;
     previewRows: readonly T[];
+    residentRows?: readonly T[] | null;
     sourceLabel?: string | null;
     tableNamespace?: string | null;
     workProgress?: PlayDatasetWorkProgressSummary;
@@ -420,8 +444,11 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     this.datasetKind = input.datasetKind;
     this.datasetId = input.datasetId;
     this.cachedCount = input.count;
+    this.knownCount =
+      input.knownCount === undefined ? input.count : input.knownCount;
     this.backing = input.backing;
     this.previewRows = input.previewRows;
+    this.residentRows = input.residentRows ?? null;
     this.previewColumns = inferPreviewColumns(this.previewRows);
     this.sourceLabel = input.sourceLabel ?? null;
     this.tableNamespace = input.tableNamespace ?? null;
@@ -429,8 +456,18 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     this.resolvers = input.resolvers;
   }
 
+  get length(): number {
+    if (this.knownCount === null) {
+      throw this.requiresAsyncAccess(
+        'The row count is not known until this lazy transform executes.',
+      );
+    }
+    return this.knownCount;
+  }
+
   async count(): Promise<number> {
     this.cachedCount = await this.resolvers.count();
+    this.knownCount = this.cachedCount;
     return this.cachedCount;
   }
 
@@ -441,6 +478,29 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     return await this.resolvers.peek(limit);
   }
 
+  async first(): Promise<T | undefined> {
+    return await this.at(0);
+  }
+
+  async at(index: number): Promise<T | undefined> {
+    if (!Number.isFinite(index)) return undefined;
+    const integer = Math.trunc(index);
+    const count = integer < 0 ? await this.count() : this.knownCount;
+    const normalized =
+      integer < 0 && count !== null ? count + integer : integer;
+    if (normalized < 0 || (count !== null && normalized >= count)) {
+      return undefined;
+    }
+    if (this.residentRows) return this.residentRows[normalized];
+    if (this.resolvers.at) return await this.resolvers.at(normalized);
+    let current = 0;
+    for await (const row of this.resolvers.iterate()) {
+      if (current === normalized) return row;
+      current += 1;
+    }
+    return undefined;
+  }
+
   map<U>(
     mapper: (row: T, index: number) => U | Promise<U>,
     options?: PlayDatasetTransformOptions,
@@ -531,6 +591,33 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     }
   }
 
+  [Symbol.iterator](): Iterator<T> {
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        'Synchronous iteration is available only when every row is resident.',
+      );
+    }
+    return this.residentRows[Symbol.iterator]();
+  }
+
+  residentAt(index: number): T | undefined {
+    if (this.knownCount !== null && index >= this.knownCount) return undefined;
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        `Row ${index} is not resident and may require dataset paging.`,
+      );
+    }
+    return this.residentRows[index];
+  }
+
+  private requiresAsyncAccess(detail: string): Error {
+    return new Error(
+      `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} ` +
+        `Dataset Handle ${this.sourceLabel ?? this.datasetId}. ` +
+        'Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.',
+    );
+  }
+
   toJSON() {
     return {
       kind: 'dataset' as const,
@@ -666,6 +753,7 @@ function createTransformedPlayDataset<T, U>(
       key: options?.key,
     }),
     count: 0,
+    knownCount: null,
     backing: source.backing,
     sourceLabel,
     tableNamespace: options?.key ?? null,
@@ -687,17 +775,60 @@ export function createDeferredPlayDataset<T>(input: {
   datasetKind: PlayDatasetKind;
   datasetId: string;
   count: number;
+  /** Authoritative synchronous count, or null when execution must determine it. */
+  knownCount?: number | null;
   backing?: PlayDatasetBacking;
   previewRows?: readonly T[];
+  /** Complete in-memory row set. Never pass a bounded preview here. */
+  residentRows?: readonly T[] | null;
   sourceLabel?: string | null;
   tableNamespace?: string | null;
   workProgress?: PlayDatasetWorkProgressSummary;
   resolvers: PlayDatasetResolvers<T>;
 }): PlayDataset<T> {
-  return new DeferredPlayDataset({
+  if (
+    input.residentRows &&
+    input.knownCount !== null &&
+    input.residentRows.length !== (input.knownCount ?? input.count)
+  ) {
+    throw new Error(
+      `Resident Dataset Handle ${input.datasetId} has ${input.residentRows.length} rows but declares ${input.knownCount ?? input.count}.`,
+    );
+  }
+  const target = new DeferredPlayDataset({
     ...input,
     previewRows: input.previewRows ?? [],
   });
+  const boundMethods = new Map<PropertyKey, unknown>();
+  const dataset = new Proxy(target, {
+    get(dataset, property) {
+      if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
+        return dataset.residentAt(Number(property));
+      }
+      const value = Reflect.get(dataset, property, dataset);
+      if (typeof value !== 'function') return value;
+      if (!boundMethods.has(property)) {
+        boundMethods.set(property, value.bind(dataset));
+      }
+      return boundMethods.get(property);
+    },
+    set(_dataset, property) {
+      if (
+        property === 'length' ||
+        (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property))
+      ) {
+        throw new Error(
+          'PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly.',
+        );
+      }
+      return false;
+    },
+  });
+  if (input.residentRows) {
+    residentRowsByDataset.set(target, input.residentRows);
+    residentRowsByDataset.set(dataset, input.residentRows);
+  }
+  return dataset;
 }
 
 export function createPlayDataset<T>(
@@ -719,6 +850,7 @@ export function createPlayDataset<T>(
       `${metadata?.kind ?? 'map'}:${metadata?.tableNamespace ?? metadata?.sourceLabel ?? 'inline'}`,
     count: materializedRows.length,
     previewRows: materializedRows.slice(0, 5),
+    residentRows: materializedRows,
     sourceLabel: metadata?.sourceLabel ?? null,
     tableNamespace: metadata?.tableNamespace ?? null,
     resolvers: {

package/dist/cli/index.js

@@ -1037,7 +1037,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.319",
+  version: "0.1.320",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -11991,7 +11991,7 @@ async function traceCliSpan(phase, fields, run) {
 
 // src/cli/play-check-hints.ts
 var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
-var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
+var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Complete resident handles support read-only length/index/iteration. For paged rows use `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.rows` or `.toArray()`.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
 var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";

package/dist/cli/index.mjs

@@ -1022,7 +1022,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.319",
+  version: "0.1.320",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -12020,7 +12020,7 @@ async function traceCliSpan(phase, fields, run) {
 
 // src/cli/play-check-hints.ts
 var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
-var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
+var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Complete resident handles support read-only length/index/iteration. For paged rows use `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.rows` or `.toArray()`.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
 var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";

package/dist/index.d.mts

@@ -3610,8 +3610,12 @@ type PlayDatasetTransformOptions = {
  *
  * @sdkReference runtime 190
  */
-interface PlayDataset<T> extends AsyncIterable<T> {
+interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
+    /** Authoritative row count when known without I/O. */
+    readonly length: number;
+    /** Resident row access. Throws when the requested row requires I/O. */
+    readonly [index: number]: T;
     /** Dataset kind. */
     readonly datasetKind: PlayDatasetKind;
     /** Dataset id. */
@@ -3626,6 +3630,10 @@ interface PlayDataset<T> extends AsyncIterable<T> {
     count(): Promise<number>;
     /** Preview rows. */
     peek(limit?: number): Promise<T[]>;
+    /** First row, loading it asynchronously when necessary. */
+    first(): Promise<T | undefined>;
+    /** Row at an array-style index, loading it asynchronously when necessary. */
+    at(index: number): Promise<T | undefined>;
     map<U>(mapper: (row: T, index: number) => U | Promise<U>, options?: PlayDatasetTransformOptions): PlayDataset<U>;
     filter(predicate: (row: T, index: number) => boolean | Promise<boolean>, options?: PlayDatasetTransformOptions): PlayDataset<T>;
     slice(start?: number, end?: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;

package/dist/index.d.ts

@@ -3610,8 +3610,12 @@ type PlayDatasetTransformOptions = {
  *
  * @sdkReference runtime 190
  */
-interface PlayDataset<T> extends AsyncIterable<T> {
+interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
+    /** Authoritative row count when known without I/O. */
+    readonly length: number;
+    /** Resident row access. Throws when the requested row requires I/O. */
+    readonly [index: number]: T;
     /** Dataset kind. */
     readonly datasetKind: PlayDatasetKind;
     /** Dataset id. */
@@ -3626,6 +3630,10 @@ interface PlayDataset<T> extends AsyncIterable<T> {
     count(): Promise<number>;
     /** Preview rows. */
     peek(limit?: number): Promise<T[]>;
+    /** First row, loading it asynchronously when necessary. */
+    first(): Promise<T | undefined>;
+    /** Row at an array-style index, loading it asynchronously when necessary. */
+    at(index: number): Promise<T | undefined>;
     map<U>(mapper: (row: T, index: number) => U | Promise<U>, options?: PlayDatasetTransformOptions): PlayDataset<U>;
     filter(predicate: (row: T, index: number) => boolean | Promise<boolean>, options?: PlayDatasetTransformOptions): PlayDataset<T>;
     slice(start?: number, end?: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;

package/dist/index.js

@@ -760,7 +760,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.319",
+  version: "0.1.320",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -5790,6 +5790,7 @@ function isDeeplineExtractorTarget(value) {
 // ../shared_libs/plays/dataset.ts
 var PLAY_DATASET_BRAND = /* @__PURE__ */ Symbol.for("deepline.play.dataset");
 var NODE_INSPECT_CUSTOM = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var residentRowsByDataset = /* @__PURE__ */ new WeakMap();
 var DEFAULT_MATERIALIZE_LIMIT = 1e4;
 var PLAY_DATASET_EXECUTION_PAGE_BYTES = 64 * 1024 * 1024;
 var PLAY_DATASET_CELL_MAX_BYTES = 5 * 1024 * 1024;
@@ -5824,21 +5825,34 @@ var DeferredPlayDataset = class {
   previewColumns;
   workProgress;
   cachedCount;
+  knownCount;
+  residentRows;
   resolvers;
   constructor(input) {
     this.datasetKind = input.datasetKind;
     this.datasetId = input.datasetId;
     this.cachedCount = input.count;
+    this.knownCount = input.knownCount === void 0 ? input.count : input.knownCount;
     this.backing = input.backing;
     this.previewRows = input.previewRows;
+    this.residentRows = input.residentRows ?? null;
     this.previewColumns = inferPreviewColumns(this.previewRows);
     this.sourceLabel = input.sourceLabel ?? null;
     this.tableNamespace = input.tableNamespace ?? null;
     this.workProgress = input.workProgress;
     this.resolvers = input.resolvers;
   }
+  get length() {
+    if (this.knownCount === null) {
+      throw this.requiresAsyncAccess(
+        "The row count is not known until this lazy transform executes."
+      );
+    }
+    return this.knownCount;
+  }
   async count() {
     this.cachedCount = await this.resolvers.count();
+    this.knownCount = this.cachedCount;
     return this.cachedCount;
   }
   async peek(limit = 10) {
@@ -5847,6 +5861,26 @@ var DeferredPlayDataset = class {
     }
     return await this.resolvers.peek(limit);
   }
+  async first() {
+    return await this.at(0);
+  }
+  async at(index) {
+    if (!Number.isFinite(index)) return void 0;
+    const integer = Math.trunc(index);
+    const count = integer < 0 ? await this.count() : this.knownCount;
+    const normalized = integer < 0 && count !== null ? count + integer : integer;
+    if (normalized < 0 || count !== null && normalized >= count) {
+      return void 0;
+    }
+    if (this.residentRows) return this.residentRows[normalized];
+    if (this.resolvers.at) return await this.resolvers.at(normalized);
+    let current = 0;
+    for await (const row of this.resolvers.iterate()) {
+      if (current === normalized) return row;
+      current += 1;
+    }
+    return void 0;
+  }
   map(mapper, options) {
     return createTransformedPlayDataset(this, { kind: "map", mapper }, options);
   }
@@ -5908,6 +5942,28 @@ var DeferredPlayDataset = class {
       yield row;
     }
   }
+  [Symbol.iterator]() {
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        "Synchronous iteration is available only when every row is resident."
+      );
+    }
+    return this.residentRows[Symbol.iterator]();
+  }
+  residentAt(index) {
+    if (this.knownCount !== null && index >= this.knownCount) return void 0;
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        `Row ${index} is not resident and may require dataset paging.`
+      );
+    }
+    return this.residentRows[index];
+  }
+  requiresAsyncAccess(detail) {
+    return new Error(
+      `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} Dataset Handle ${this.sourceLabel ?? this.datasetId}. Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.`
+    );
+  }
   toJSON() {
     return {
       kind: "dataset",
@@ -6009,6 +6065,7 @@ function createTransformedPlayDataset(source, transform, options) {
       key: options?.key
     }),
     count: 0,
+    knownCount: null,
     backing: source.backing,
     sourceLabel,
     tableNamespace: options?.key ?? null,
@@ -6025,10 +6082,42 @@ function createTransformedPlayDataset(source, transform, options) {
   });
 }
 function createDeferredPlayDataset(input) {
-  return new DeferredPlayDataset({
+  if (input.residentRows && input.knownCount !== null && input.residentRows.length !== (input.knownCount ?? input.count)) {
+    throw new Error(
+      `Resident Dataset Handle ${input.datasetId} has ${input.residentRows.length} rows but declares ${input.knownCount ?? input.count}.`
+    );
+  }
+  const target = new DeferredPlayDataset({
     ...input,
     previewRows: input.previewRows ?? []
   });
+  const boundMethods = /* @__PURE__ */ new Map();
+  const dataset = new Proxy(target, {
+    get(dataset2, property) {
+      if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+        return dataset2.residentAt(Number(property));
+      }
+      const value = Reflect.get(dataset2, property, dataset2);
+      if (typeof value !== "function") return value;
+      if (!boundMethods.has(property)) {
+        boundMethods.set(property, value.bind(dataset2));
+      }
+      return boundMethods.get(property);
+    },
+    set(_dataset, property) {
+      if (property === "length" || typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+        throw new Error(
+          "PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly."
+        );
+      }
+      return false;
+    }
+  });
+  if (input.residentRows) {
+    residentRowsByDataset.set(target, input.residentRows);
+    residentRowsByDataset.set(dataset, input.residentRows);
+  }
+  return dataset;
 }
 function createPlayDataset(rows, metadata) {
   const materializedRows = [...rows];
@@ -6037,6 +6126,7 @@ function createPlayDataset(rows, metadata) {
     datasetId: metadata?.datasetId ?? `${metadata?.kind ?? "map"}:${metadata?.tableNamespace ?? metadata?.sourceLabel ?? "inline"}`,
     count: materializedRows.length,
     previewRows: materializedRows.slice(0, 5),
+    residentRows: materializedRows,
     sourceLabel: metadata?.sourceLabel ?? null,
     tableNamespace: metadata?.tableNamespace ?? null,
     resolvers: {
@@ -7346,7 +7436,9 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
     return result;
   }
   const datasetLimit = finitePositiveInteger(dataset.returned_limit) ?? totalRows;
-  const previewRows = rowsFromUnknown(raw?.rows).slice(0, 25);
+  const effectiveCount = Math.min(totalRows, datasetLimit);
+  const rawRows = rowsFromUnknown(raw?.rows);
+  const previewRows = rawRows.slice(0, 25);
   const fetchPage = async (offset, limit) => {
     if (limit <= 0 || offset >= totalRows) return [];
     const response = await options.client.executeTool(toolId, options.input, {
@@ -7393,10 +7485,12 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
     datasetId: `sdk-tool-list:${toolId}:${stableHash(datasetScope)}:${datasetLimit}:${safeNonce}`,
     count: Math.min(totalRows, datasetLimit),
     previewRows,
+    residentRows: rawRows.length >= effectiveCount ? rawRows.slice(0, effectiveCount) : null,
     sourceLabel: "query result rows",
     tableNamespace: null,
     resolvers: {
       count: async () => Math.min(totalRows, datasetLimit),
+      at: async (index) => (await fetchPage(index, 1))[0],
       peek: async (limit) => collectRows(limit),
       materialize: async (limit) => collectRows(limit),
       iterate: () => ({

package/dist/index.mjs

@@ -686,7 +686,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.319",
+  version: "0.1.320",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -5716,6 +5716,7 @@ function isDeeplineExtractorTarget(value) {
 // ../shared_libs/plays/dataset.ts
 var PLAY_DATASET_BRAND = /* @__PURE__ */ Symbol.for("deepline.play.dataset");
 var NODE_INSPECT_CUSTOM = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var residentRowsByDataset = /* @__PURE__ */ new WeakMap();
 var DEFAULT_MATERIALIZE_LIMIT = 1e4;
 var PLAY_DATASET_EXECUTION_PAGE_BYTES = 64 * 1024 * 1024;
 var PLAY_DATASET_CELL_MAX_BYTES = 5 * 1024 * 1024;
@@ -5750,21 +5751,34 @@ var DeferredPlayDataset = class {
   previewColumns;
   workProgress;
   cachedCount;
+  knownCount;
+  residentRows;
   resolvers;
   constructor(input) {
     this.datasetKind = input.datasetKind;
     this.datasetId = input.datasetId;
     this.cachedCount = input.count;
+    this.knownCount = input.knownCount === void 0 ? input.count : input.knownCount;
     this.backing = input.backing;
     this.previewRows = input.previewRows;
+    this.residentRows = input.residentRows ?? null;
     this.previewColumns = inferPreviewColumns(this.previewRows);
     this.sourceLabel = input.sourceLabel ?? null;
     this.tableNamespace = input.tableNamespace ?? null;
     this.workProgress = input.workProgress;
     this.resolvers = input.resolvers;
   }
+  get length() {
+    if (this.knownCount === null) {
+      throw this.requiresAsyncAccess(
+        "The row count is not known until this lazy transform executes."
+      );
+    }
+    return this.knownCount;
+  }
   async count() {
     this.cachedCount = await this.resolvers.count();
+    this.knownCount = this.cachedCount;
     return this.cachedCount;
   }
   async peek(limit = 10) {
@@ -5773,6 +5787,26 @@ var DeferredPlayDataset = class {
     }
     return await this.resolvers.peek(limit);
   }
+  async first() {
+    return await this.at(0);
+  }
+  async at(index) {
+    if (!Number.isFinite(index)) return void 0;
+    const integer = Math.trunc(index);
+    const count = integer < 0 ? await this.count() : this.knownCount;
+    const normalized = integer < 0 && count !== null ? count + integer : integer;
+    if (normalized < 0 || count !== null && normalized >= count) {
+      return void 0;
+    }
+    if (this.residentRows) return this.residentRows[normalized];
+    if (this.resolvers.at) return await this.resolvers.at(normalized);
+    let current = 0;
+    for await (const row of this.resolvers.iterate()) {
+      if (current === normalized) return row;
+      current += 1;
+    }
+    return void 0;
+  }
   map(mapper, options) {
     return createTransformedPlayDataset(this, { kind: "map", mapper }, options);
   }
@@ -5834,6 +5868,28 @@ var DeferredPlayDataset = class {
       yield row;
     }
   }
+  [Symbol.iterator]() {
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        "Synchronous iteration is available only when every row is resident."
+      );
+    }
+    return this.residentRows[Symbol.iterator]();
+  }
+  residentAt(index) {
+    if (this.knownCount !== null && index >= this.knownCount) return void 0;
+    if (!this.residentRows) {
+      throw this.requiresAsyncAccess(
+        `Row ${index} is not resident and may require dataset paging.`
+      );
+    }
+    return this.residentRows[index];
+  }
+  requiresAsyncAccess(detail) {
+    return new Error(
+      `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} Dataset Handle ${this.sourceLabel ?? this.datasetId}. Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.`
+    );
+  }
   toJSON() {
     return {
       kind: "dataset",
@@ -5935,6 +5991,7 @@ function createTransformedPlayDataset(source, transform, options) {
       key: options?.key
     }),
     count: 0,
+    knownCount: null,
     backing: source.backing,
     sourceLabel,
     tableNamespace: options?.key ?? null,
@@ -5951,10 +6008,42 @@ function createTransformedPlayDataset(source, transform, options) {
   });
 }
 function createDeferredPlayDataset(input) {
-  return new DeferredPlayDataset({
+  if (input.residentRows && input.knownCount !== null && input.residentRows.length !== (input.knownCount ?? input.count)) {
+    throw new Error(
+      `Resident Dataset Handle ${input.datasetId} has ${input.residentRows.length} rows but declares ${input.knownCount ?? input.count}.`
+    );
+  }
+  const target = new DeferredPlayDataset({
     ...input,
     previewRows: input.previewRows ?? []
   });
+  const boundMethods = /* @__PURE__ */ new Map();
+  const dataset = new Proxy(target, {
+    get(dataset2, property) {
+      if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+        return dataset2.residentAt(Number(property));
+      }
+      const value = Reflect.get(dataset2, property, dataset2);
+      if (typeof value !== "function") return value;
+      if (!boundMethods.has(property)) {
+        boundMethods.set(property, value.bind(dataset2));
+      }
+      return boundMethods.get(property);
+    },
+    set(_dataset, property) {
+      if (property === "length" || typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+        throw new Error(
+          "PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly."
+        );
+      }
+      return false;
+    }
+  });
+  if (input.residentRows) {
+    residentRowsByDataset.set(target, input.residentRows);
+    residentRowsByDataset.set(dataset, input.residentRows);
+  }
+  return dataset;
 }
 function createPlayDataset(rows, metadata) {
   const materializedRows = [...rows];
@@ -5963,6 +6052,7 @@ function createPlayDataset(rows, metadata) {
     datasetId: metadata?.datasetId ?? `${metadata?.kind ?? "map"}:${metadata?.tableNamespace ?? metadata?.sourceLabel ?? "inline"}`,
     count: materializedRows.length,
     previewRows: materializedRows.slice(0, 5),
+    residentRows: materializedRows,
     sourceLabel: metadata?.sourceLabel ?? null,
     tableNamespace: metadata?.tableNamespace ?? null,
     resolvers: {
@@ -7272,7 +7362,9 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
     return result;
   }
   const datasetLimit = finitePositiveInteger(dataset.returned_limit) ?? totalRows;
-  const previewRows = rowsFromUnknown(raw?.rows).slice(0, 25);
+  const effectiveCount = Math.min(totalRows, datasetLimit);
+  const rawRows = rowsFromUnknown(raw?.rows);
+  const previewRows = rawRows.slice(0, 25);
   const fetchPage = async (offset, limit) => {
     if (limit <= 0 || offset >= totalRows) return [];
     const response = await options.client.executeTool(toolId, options.input, {
@@ -7319,10 +7411,12 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
     datasetId: `sdk-tool-list:${toolId}:${stableHash(datasetScope)}:${datasetLimit}:${safeNonce}`,
     count: Math.min(totalRows, datasetLimit),
     previewRows,
+    residentRows: rawRows.length >= effectiveCount ? rawRows.slice(0, effectiveCount) : null,
     sourceLabel: "query result rows",
     tableNamespace: null,
     resolvers: {
       count: async () => Math.min(totalRows, datasetLimit),
+      at: async (index) => (await fetchPage(index, 1))[0],
       peek: async (limit) => collectRows(limit),
       materialize: async (limit) => collectRows(limit),
       iterate: () => ({

package/package.json

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