deepline 0.3.325 → 0.3.327

package/dist/{compiler-manifest-CsnWj-AK.d.ts → compiler-manifest-9TkZ_ykI.d.ts}

@@ -2,765 +2,765 @@
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 
-type EmailStatusVerdict = 'send' | 'send_with_caution' | 'verify_next' | 'hold' | 'drop';
-type EmailStatusValue = 'valid' | 'invalid' | 'catch_all' | 'valid_catch_all' | 'unknown' | 'do_not_mail' | 'spamtrap' | 'abuse' | 'disposable';
-type EmailDeliverability = 'high' | 'medium' | 'low' | 'unknown';
-type EmailMxClass = 'consumer_mailbox' | 'workspace_mailbox' | 'security_gateway' | 'on_prem' | 'unknown';
-type EmailStatus = {
-    verdict: EmailStatusVerdict;
-    status: EmailStatusValue;
-    verified: boolean;
-    confidence: number | null;
-    reasons: string[];
-    signals: {
-        catch_all: boolean | null;
-        deliverability: EmailDeliverability;
-        mx_class: EmailMxClass;
-        mx_provider: string | null;
-        mx_record: string | null;
-        fraud_score: number | null;
-        disposable: boolean | null;
-        role_based: boolean | null;
-        free_email: boolean | null;
-        abuse: boolean | null;
-        spamtrap: boolean | null;
-        suspect: boolean | null;
-        valid: boolean | null;
-    };
-    provider: {
-        name: string;
-        raw_status: string | boolean | number | null;
-        raw_score: number | null;
-    };
-};
-type EmailStatusMapEntry = {
-    status: EmailStatusValue;
-    verdict?: EmailStatusVerdict;
-    verified?: boolean;
-    reason?: string;
-};
-type EmailStatusRule = EmailStatusMapEntry & {
-    when: Record<string, string | number | boolean | null>;
-};
-type EmailStatusExtractorConfig = {
-    provider: string;
-    rawStatus?: string[];
-    rawScore?: string[];
-    valid?: string[];
-    deliverability?: string[];
-    catchAll?: string[];
-    mxProvider?: string[];
-    mxRecord?: string[];
-    fraudScore?: string[];
-    disposable?: string[];
-    roleBased?: string[];
-    freeEmail?: string[];
-    abuse?: string[];
-    spamtrap?: string[];
-    suspect?: string[];
-    statusMap?: Record<string, EmailStatusMapEntry>;
-    rules?: EmailStatusRule[];
-};
-
-declare const JOB_CHANGE_STATUS_VALUES: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
-type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
-type JobChangeGetterValue = {
-    status: JobChangeStatus;
-    date: string | null;
-    new_company: string | null;
-    new_title: string | null;
-};
-declare const PHONE_STATUS_VALUES: readonly ["valid", "invalid", "unknown"];
-type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
-declare const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: {
-    readonly id: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly email: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly personal_email: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly phone: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly linkedin: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly linkedin_url: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly domain: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly website: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly first_name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly last_name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly full_name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly company: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly company_name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly organization_name: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly company_domain: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly company_website: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly company_linkedin_url: {
-        readonly identity: true;
-        readonly valueKind: "string";
-    };
-    readonly title: {
-        readonly identity: false;
-        readonly valueKind: "string";
-    };
-    readonly industry: {
-        readonly identity: false;
-        readonly valueKind: "string";
-    };
-    readonly status: {
-        readonly identity: false;
-        readonly valueKind: "string";
-    };
-    readonly job_change: {
-        readonly identity: false;
-        readonly valueKind: "job_change";
-    };
-    readonly job_change_status: {
-        readonly identity: false;
-        readonly valueKind: "job_change_status";
-        readonly enum: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
-    };
-    readonly email_status: {
-        readonly identity: false;
-        readonly valueKind: "email_status";
-    };
-    readonly phone_status: {
-        readonly identity: false;
-        readonly valueKind: "phone_status";
-        readonly enum: readonly ["valid", "invalid", "unknown"];
-    };
-};
-type DeeplineExtractorTarget = keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
-declare const DEEPLINE_EXTRACTOR_TARGETS: DeeplineExtractorTarget[];
-type DeeplineEmailStatusGetterValue = EmailStatus;
-type DeeplineGetterValueMap = {
-    id: string;
-    name: string;
-    email: string;
-    personal_email: string;
-    phone: string;
-    linkedin: string;
-    linkedin_url: string;
-    domain: string;
-    website: string;
-    first_name: string;
-    last_name: string;
-    full_name: string;
-    company: string;
-    company_name: string;
-    organization_name: string;
-    company_domain: string;
-    company_website: string;
-    company_linkedin_url: string;
-    title: string;
-    industry: string;
-    status: string;
-    job_change: JobChangeGetterValue;
-    job_change_status: JobChangeStatus;
-    email_status: EmailStatus;
-    phone_status: PhoneStatus;
-};
-type DeeplineGetterValue<TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget> = DeeplineGetterValueMap[TTarget];
-declare function isDeeplineExtractorTarget(value: string): value is DeeplineExtractorTarget;
-
-interface PlayR2FileRef {
-    storageKind: 'r2';
-    storageKey: string;
-    logicalPath: string;
-    fileName: string;
-    contentHash: string;
-    contentType: string;
-    bytes: number;
-}
-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 = {
-    storage: 'neon_sheet';
-    sheet: {
-        playName: string;
-        tableNamespace: string;
-    };
-} | {
-    storage: 'r2_file';
-    file: PlayExecutionFileRef;
-};
-type PlayDatasetWorkProgressSummary = {
-    total: number;
-    executed: number;
-    reused: number;
-    skipped: number;
-    pending: number;
-    failed: number;
-    degraded?: boolean;
-    duplicates?: {
-        exact?: number;
-        semantic?: number;
-        rejected?: number;
-    };
-};
-type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
-type PlayDatasetRow<TInput> = TInput extends PlayDataset<infer Row> ? Row : TInput extends ReadonlyArray<infer Row> ? Row : TInput extends Iterable<infer Row> ? Row : TInput extends AsyncIterable<infer Row> ? Row : never;
-type PlayDatasetTransformOptions = {
-    key?: string;
-    sourceLabel?: string | null;
-};
+declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
+declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
+type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
 /**
- * Durable handle for rows produced by `ctx.csv(...)` or `ctx.dataset(...).run()`.
+ * The boundary responsible for a failed tool call.
  *
- * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
- * rows, usually backed by persisted sheet storage, and carries metadata such as
- * dataset kind, dataset id, table namespace, count, and preview rows.
+ * Use `provider` to distinguish a provider answer from caller input and
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
+ * waterfall fallback.
  *
- * Pass dataset handles directly into later `ctx.dataset(...)` stages by default so
- * Deepline keeps row progress, retries, memory use, and table output under
- * runtime control. Use `count()` and `peek()` for bounded inspection. Use
- * `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;
- * these hide loading costs or make behavior depend on row residency.
+ * @sdkReference errors 020
+ */
+type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+/**
+ * The stable reason family for a failed tool call.
  *
- * @sdkReference runtime 190
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
+ * `ProviderTransientError` when the policy is simply “try the next read
+ * provider”; it is the safer and shorter waterfall contract.
+ *
+ * @sdkReference errors 030
  */
-interface PlayDataset<T> extends AsyncIterable<T> {
-    readonly [PLAY_DATASET_BRAND]: true;
-    /** Dataset kind. */
-    readonly datasetKind: PlayDatasetKind;
-    /** Dataset id. */
-    readonly datasetId: string;
-    /** Backing store info. */
-    readonly backing?: PlayDatasetBacking;
-    /** Display label. */
-    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. */
-    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>;
-    take(limit: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;
+type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+/**
+ * The transport failure observed when `category` is `network`.
+ *
+ * This is `null` for failures that are not network failures.
+ *
+ * @sdkReference errors 040
+ */
+type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+/**
+ * The request boundary on which a network failure occurred.
+ *
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
+ * Deepline transport failures and never qualify as provider fallthrough.
+ *
+ * @sdkReference errors 050
+ */
+type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+/**
+ * Bounded, primitive-only diagnostics explicitly approved for customers.
+ * Raw provider bodies, credentials, prompts, stacks, and causes never belong
+ * in this shared API/SDK/Play contract.
+ *
+ * @sdkReference errors 063
+ */
+type ToolExecutionPublicDetails = Readonly<Record<string, string | number | boolean | null>>;
+/**
+ * Portable version-1 `tool_error` payload.
+ *
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
+ * `message` remains on the Error object and is deliberately not a policy
+ * field.
+ *
+ * @sdkReference errors 064
+ */
+type ToolExecutionFailureV1 = {
+    /** Payload version. */
+    schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    /** Public tool id passed to `tools.execute`. */
+    toolId: string;
+    /** Provider responsible for the operation, or `null`. */
+    provider: string | null;
+    /** Provider operation name, or `null`. */
+    operation: string | null;
+    /** Stable machine-readable failure code, or `null`. */
+    code: string | null;
+    /** Boundary responsible for the failure. */
+    origin: ToolExecutionErrorOrigin;
+    /** Stable reason family. */
+    category: ToolExecutionErrorCategory;
+    /** Whether repeating the same semantic call is delivery-safe. */
+    retryable: boolean;
+    /** HTTP status when one exists, or `null`. */
+    statusCode: number | null;
+    /** Provider or Deepline request id, or `null`. */
+    requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
+    retryAfterMs: number | null;
+    /** Network failure kind, or `null`. */
+    networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null`. */
+    networkScope: ToolExecutionNetworkScope | null;
+    /** Explicitly allowlisted customer diagnostics, when present. */
+    publicDetails?: ToolExecutionPublicDetails | null;
+};
+/**
+ * Constructor input for a structured tool failure.
+ *
+ * Deepline creates these values while decoding the versioned wire payload.
+ * Customer code normally reads `ToolExecutionError` fields instead of
+ * constructing an error.
+ *
+ * @sdkReference errors 065
+ */
+type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
     /**
-     * Explicit escape hatch for bounded result sets.
-     * Large datasets should flow by handle through Neon-backed storage, not
-     * through worker memory as giant arrays.
+     * Local diagnostic context inherited from DeeplineError. This is not part of
+     * the portable failure payload and is intentionally omitted by serialization.
      */
-    materialize(options?: number | PlayDatasetMaterializeOptions): Promise<T[]>;
-    toJSON(): {
-        kind: 'dataset';
-        datasetKind: PlayDatasetKind;
-        datasetId: string;
-        count: number;
-        backing?: PlayDatasetBacking;
-        sourceLabel?: string | null;
-        tableNamespace?: string | null;
-        columns?: string[];
-        columnTypes?: PlayDatasetColumnTypes;
-        _metadata?: {
-            workProgress?: PlayDatasetWorkProgressSummary;
-        };
-        preview: T[];
-    };
-}
-type PlayDatasetMaterializeScope = 'result' | 'full_persisted_dataset';
-type PlayDatasetMaterializeOptions = {
-    /** Rows returned by this operation, or every current row in its persisted dataset. */
-    scope?: PlayDatasetMaterializeScope;
-    /** Maximum number of rows to load into memory. */
-    limit?: number;
+    details?: Record<string, unknown>;
 };
-
 /**
- * Customer pricing reported by the execution API, never provider spend.
- * `credits_charged` and `cost_usd` describe the price of the original call;
- * they do not acknowledge durable handoff or wallet posting. Receipt replay
- * preserves this observation and does not imply a new charge or fresher state.
+ * Provider-owned failure categories that may fall through to another read
+ * provider.
+ *
+ * @sdkReference errors 060
  */
-type ToolResultBilling = {
-    credits_charged?: number;
-    cost_usd?: number;
-    /** Missing on historical responses. Pending pricing has no final amount. */
-    pricing_status?: 'final' | 'pending';
-    settlement_status?: 'pending' | 'queued' | 'settled' | 'released' | 'requires_recovery';
-    billing_outcome_reason?: 'free_operation' | 'provider_no_billable_result' | 'provider_reported_zero_usage' | 'zero_price';
-    estimated_credits?: number;
-    estimated_cost_usd?: number;
-    /** Preserve additive public pricing details across runtime/deployment skew. */
-    [key: string]: unknown;
-};
-type ToolResultExecutionMetadata = {
-    idempotent: true;
-    cached: boolean;
-    source: 'live' | 'checkpoint' | 'cache' | 'in_flight' | 'source_run';
-    cacheKey?: string;
-    receiptRole?: 'owner' | 'follower';
-    receiptKey?: string;
-    /** Canonical saved result identity; receiptKey may name a transport alias. */
-    resultReceiptKey?: string;
-    attachedToReceiptKey?: string;
-};
-type ToolResultTargetMetadata = {
-    value: unknown;
-    path: string;
-};
-type ToolResultListMetadata = {
-    path: string;
-    count: number | null;
-    keys: Record<string, string>;
-};
-type ToolResultExtractorDescriptor = {
-    paths: readonly string[];
-    transforms?: readonly string[];
-    enum?: readonly string[];
-    overrides?: readonly ToolResultExtractorOverride[];
-    emailStatus?: EmailStatusExtractorConfig;
-};
-type ToolResultExtractorOverride = {
-    paths: readonly string[];
-    equals?: string | number | boolean | null;
-    value: string | number | boolean | null;
-};
-type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
-    get(): T | null;
-};
-type ToolResultListAccessor<T = Record<string, unknown>, TKey extends string = string> = Omit<ToolResultListMetadata, 'keys'> & {
-    keys: Partial<Record<TKey, string>> & Record<string, string>;
-    get(): PlayDataset<T>;
-};
-type ToolResponseEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
-    /** @deprecated Use declared getters or toolResponse.rawV2. */
-    raw: TData;
-    /** Complete parsed and scrubbed provider response, materialized from raw-v2. */
-    rawV2?: unknown;
-    /** Durable descriptor for deriving the legacy raw view from `rawV2`. */
-    view?: 'data' | 'rawV2';
-    meta?: TMeta;
-};
-type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
-    status: string;
-    job_id?: string;
-    /** Deepline-owned execution/result metadata. */
-    meta?: Record<string, unknown>;
-    billing?: ToolResultBilling;
-    toolResponse: ToolResponseEnvelope<TResult, TMeta>;
-    extractedValues: Record<string, ToolResultTargetAccessor>;
-    extractedLists: Record<string, ToolResultListAccessor>;
-    /** Convenience alias for play code. Serialized output uses toolResponse. */
-    toolOutput: ToolResponseEnvelope<TResult, TMeta>;
-    _metadata: {
-        toolId: string;
-        execution: ToolResultExecutionMetadata;
-        targets: Record<string, {
-            value: unknown;
-            path: string;
-        }>;
-        extractors?: Record<string, ToolResultExtractorDescriptor>;
-        lists: Record<string, {
-            path: string;
-            count: number | null;
-            keys: Record<string, string>;
-        }>;
-        /** Original declarations preserve semantic accessor names across replay. */
-        listExtractorPaths?: readonly string[];
-    };
-};
-type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
-    extractedValues: {
-        [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
-    };
-    extractedLists: {
-        [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
-    };
-};
+type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
 /**
- * Canonical result returned by Deepline tool execution.
+ * Base error class shared by the SDK and play runtime.
  *
- * The top-level object is Deepline-owned execution metadata and semantic
- * extraction state. The canonical provider response lives under
- * `toolResponse.rawV2`. Response metadata lives under `toolResponse.meta`. Semantic single-value
- * getters live under `extractedValues.<name>.get()`, and list getters live
- * under `extractedLists.<name>.get()`.
+ * The global brand preserves `instanceof DeeplineError` when a bundled play
+ * and the runtime load separate physical copies of this module.
  *
- * Use extractors first when a tool contract exposes them. Use list getters for
- * row-shaped data. Use `toolResponse.rawV2` for provider-specific fields or
- * debugging. Inspect the observed response before selecting a nested field;
- * provider envelopes are preserved, including pagination and sibling resources.
- * This is parsed, scrubbed data, not the original HTTP bytes or headers.
+ * @sdkReference errors 010
+ */
+declare class DeeplineError extends Error {
+    /** HTTP status when the failure crossed an HTTP boundary. */
+    statusCode?: number;
+    /** Stable machine-readable error code when one exists. */
+    code?: string;
+    /** Local diagnostic context; not a portable error contract. */
+    details?: Record<string, unknown>;
+    /**
+     * Construct a Deepline error.
+     *
+     * SDK and runtime code construct these errors. Application and Play code
+     * normally catches the public subclasses instead.
+     *
+     * @param message Human-readable failure summary.
+     * @param statusCode HTTP status when one exists.
+     * @param code Stable machine-readable code when one exists.
+     * @param details Local diagnostic context; never a portable error contract.
+     */
+    constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A failed `tools.execute` call with stable, allowlisted provenance.
  *
- * @sdkReference runtime 200
+ * `retryable` means Deepline's delivery/idempotency contract says it is safe
+ * to repeat the same semantic call. It does not describe durable receipt
+ * repairability and does not make arbitrary side-effecting fallbacks safe.
+ *
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
+ * this base class when you need structured diagnostics for every tool failure.
+ *
+ * @sdkReference errors 070
  */
-type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
-
-declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
-declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
-type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+declare class ToolExecutionError extends DeeplineError {
+    /** Public tool id passed to `tools.execute`. */
+    readonly toolId: string;
+    /** Provider responsible for the operation, or `null` when unattributed. */
+    readonly provider: string | null;
+    /** Provider operation name, or `null` when unavailable. */
+    readonly operation: string | null;
+    /** Boundary responsible for the failure. */
+    readonly origin: ToolExecutionErrorOrigin;
+    /** Stable reason family for policy and diagnostics. */
+    readonly category: ToolExecutionErrorCategory;
+    /**
+     * Whether repeating the same semantic call is delivery-safe.
+     *
+     * This does not mean the error may be ignored. Waterfall fallthrough is
+     * represented by `ProviderTransientError`.
+     */
+    readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null` when unavailable. */
+    readonly requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
+    readonly retryAfterMs: number | null;
+    /** Network failure kind, or `null` for non-network failures. */
+    readonly networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null` for non-network failures. */
+    readonly networkScope: ToolExecutionNetworkScope | null;
+    /** Explicitly allowlisted diagnostics safe for SDK and Play callers. */
+    readonly publicDetails: ToolExecutionPublicDetails | null;
+    /**
+     * Construct a structured tool error.
+     *
+     * Deepline constructs this from the versioned `tool_error` payload.
+     * Application and Play code should catch it rather than create it.
+     */
+    constructor(message: string, options: ToolExecutionErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
 /**
- * The boundary responsible for a failed tool call.
+ * A provider-owned transient failure that is safe to handle as an empty
+ * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
+ * never satisfy this type.
  *
- * Use `provider` to distinguish a provider answer from caller input and
- * Deepline infrastructure. `unknown` fails closed and must not trigger a
- * waterfall fallback.
+ * `retryable` remains independent: it says whether the same semantic call may
+ * be repeated safely. Falling through to a different read provider depends on
+ * this class, not on `retryable`.
  *
- * @sdkReference errors 020
+ * @sdkReference errors 080
  */
-type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+declare class ProviderTransientError extends ToolExecutionError {
+    /** Provider attribution is guaranteed for this subtype. */
+    readonly origin: "provider";
+    /** Provider failure category that made this error eligible for fallthrough. */
+    readonly category: ProviderTransientErrorCategory;
+    /** Constructed by Deepline when a provider-owned transient failure arrives. */
+    constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
+        category: ProviderTransientErrorCategory;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/** Why a provider cannot serve the current read request. */
+type ProviderUnavailableReason = ProviderTransientErrorCategory | 'account_capacity' | 'credentials_missing';
 /**
- * The stable reason family for a failed tool call.
- *
- * Branch on this field only after narrowing to `ToolExecutionError`. Catch
- * `ProviderTransientError` when the policy is simply “try the next read
- * provider”; it is the safer and shorter waterfall contract.
- *
- * @sdkReference errors 030
+ * A provider failure that permits a read waterfall to try its next provider.
+ * A missing provider connection is included because another provider may still
+ * serve the read. Invalid credentials, caller input, and Deepline billing
+ * failures remain loud.
  */
-type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+type ProviderUnavailableError = ProviderTransientError | (ToolExecutionError & {
+    readonly origin: 'provider';
+    readonly code: 'PROVIDER_ACCOUNT_CAPACITY';
+}) | (ToolExecutionError & {
+    readonly origin: 'caller';
+    readonly code: 'INTEGRATION_CREDENTIALS_MISSING';
+});
 /**
- * The transport failure observed when `category` is `network`.
- *
- * This is `null` for failures that are not network failures.
+ * Return the provider-specific reason a read cannot run right now.
  *
- * @sdkReference errors 040
+ * `null` means this error must stay loud: it is caller input, an invalid
+ * customer credential, Deepline billing, or an internal failure. A missing
+ * provider connection is different: an explicit read waterfall may continue
+ * to a configured fallback and record the unavailable leg.
  */
-type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+declare function getProviderUnavailableReason(error: unknown): ProviderUnavailableReason | null;
 /**
- * The request boundary on which a network failure occurred.
- *
- * `deepline_to_provider` is provider-side. Client and runtime scopes are
- * Deepline transport failures and never qualify as provider fallthrough.
+ * Whether a provider cannot serve this read right now.
  *
- * @sdkReference errors 050
+ * Use this in an explicit `catch` to advance a read-only waterfall. For
+ * diagnostics, use `getProviderUnavailableReason(error)`.
  */
-type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+declare function isProviderUnavailable(error: unknown): error is ProviderUnavailableError;
+/** @deprecated Use isProviderUnavailable. */
+declare const isProviderWaterfallUnavailableError: typeof isProviderUnavailable;
+
 /**
- * Bounded, primitive-only diagnostics explicitly approved for customers.
- * Raw provider bodies, credentials, prompts, stacks, and causes never belong
- * in this shared API/SDK/Play contract.
- *
- * @sdkReference errors 063
+ * Public tool-response contracts shared by the API, SDK, Play bundler, and
+ * runtime. This is a versioned response transformation contract: a change to
+ * the persisted public tool-result shape must introduce a new value here and
+ * have newly built Play artifacts select it. Receipt-cache revisions are
+ * intentionally separate: ordinary response-contract changes do not refresh
+ * durable receipts unless the response transformation changed as well.
  */
-type ToolExecutionPublicDetails = Readonly<Record<string, string | number | boolean | null>>;
+declare const V2_TOOL_RESPONSE_CONTRACT: "v2-tool-response";
+declare const RAW_V2_TOOL_RESPONSE_CONTRACT: "raw-v2";
+type ToolResponseContract = typeof V2_TOOL_RESPONSE_CONTRACT | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
+
 /**
- * Portable version-1 `tool_error` payload.
+ * Previous durable cell value passed to object-column resolvers.
  *
- * This allowlisted shape crosses the API, runtime, and SDK boundaries.
- * `message` remains on the Error object and is deliberately not a policy
- * field.
+ * The runtime supplies this when a row+column is being recomputed after a
+ * previous value existed. `value` has the same type that the column returns;
+ * freshness metadata lives beside it.
  *
- * @sdkReference errors 064
+ * @sdkReference runtime 120
  */
-type ToolExecutionFailureV1 = {
-    /** Payload version. */
-    schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
-    /** Public tool id passed to `tools.execute`. */
-    toolId: string;
-    /** Provider responsible for the operation, or `null`. */
-    provider: string | null;
-    /** Provider operation name, or `null`. */
-    operation: string | null;
-    /** Stable machine-readable failure code, or `null`. */
-    code: string | null;
-    /** Boundary responsible for the failure. */
-    origin: ToolExecutionErrorOrigin;
-    /** Stable reason family. */
-    category: ToolExecutionErrorCategory;
-    /** Whether repeating the same semantic call is delivery-safe. */
-    retryable: boolean;
-    /** HTTP status when one exists, or `null`. */
-    statusCode: number | null;
-    /** Provider or Deepline request id, or `null`. */
-    requestId: string | null;
-    /** Suggested same-call retry delay in milliseconds, or `null`. */
-    retryAfterMs: number | null;
-    /** Network failure kind, or `null`. */
-    networkKind: ToolExecutionNetworkKind | null;
-    /** Network boundary that failed, or `null`. */
-    networkScope: ToolExecutionNetworkScope | null;
-    /** Explicitly allowlisted customer diagnostics, when present. */
-    publicDetails?: ToolExecutionPublicDetails | null;
+type PreviousCell<Value = unknown> = {
+    /** Previous completed value for this row+column. */
+    value: Value;
+    /** Millisecond timestamp when the previous value completed. */
+    completedAt?: number;
+    /** Millisecond timestamp when the previous value becomes stale; `null` means no expiry. */
+    staleAt?: number | null;
+    /** Resolved numeric TTL in seconds for the previous value, when present. */
+    staleAfterSeconds?: number;
+};
+
+type PlaySandboxRuntimeLimits = {
+    timeoutSeconds: number;
+    memoryGiB: number;
+    cpu: number;
+    diskGiB: number;
+};
+type PlaySandboxSize = 'standard';
+type PlaySandboxRuntimeDeclaration = {
+    timeout?: string;
+    size?: PlaySandboxSize;
+};
+
+type EmailStatusVerdict = 'send' | 'send_with_caution' | 'verify_next' | 'hold' | 'drop';
+type EmailStatusValue = 'valid' | 'invalid' | 'catch_all' | 'valid_catch_all' | 'unknown' | 'do_not_mail' | 'spamtrap' | 'abuse' | 'disposable';
+type EmailDeliverability = 'high' | 'medium' | 'low' | 'unknown';
+type EmailMxClass = 'consumer_mailbox' | 'workspace_mailbox' | 'security_gateway' | 'on_prem' | 'unknown';
+type EmailStatus = {
+    verdict: EmailStatusVerdict;
+    status: EmailStatusValue;
+    verified: boolean;
+    confidence: number | null;
+    reasons: string[];
+    signals: {
+        catch_all: boolean | null;
+        deliverability: EmailDeliverability;
+        mx_class: EmailMxClass;
+        mx_provider: string | null;
+        mx_record: string | null;
+        fraud_score: number | null;
+        disposable: boolean | null;
+        role_based: boolean | null;
+        free_email: boolean | null;
+        abuse: boolean | null;
+        spamtrap: boolean | null;
+        suspect: boolean | null;
+        valid: boolean | null;
+    };
+    provider: {
+        name: string;
+        raw_status: string | boolean | number | null;
+        raw_score: number | null;
+    };
+};
+type EmailStatusMapEntry = {
+    status: EmailStatusValue;
+    verdict?: EmailStatusVerdict;
+    verified?: boolean;
+    reason?: string;
+};
+type EmailStatusRule = EmailStatusMapEntry & {
+    when: Record<string, string | number | boolean | null>;
+};
+type EmailStatusExtractorConfig = {
+    provider: string;
+    rawStatus?: string[];
+    rawScore?: string[];
+    valid?: string[];
+    deliverability?: string[];
+    catchAll?: string[];
+    mxProvider?: string[];
+    mxRecord?: string[];
+    fraudScore?: string[];
+    disposable?: string[];
+    roleBased?: string[];
+    freeEmail?: string[];
+    abuse?: string[];
+    spamtrap?: string[];
+    suspect?: string[];
+    statusMap?: Record<string, EmailStatusMapEntry>;
+    rules?: EmailStatusRule[];
+};
+
+declare const JOB_CHANGE_STATUS_VALUES: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
+type JobChangeGetterValue = {
+    status: JobChangeStatus;
+    date: string | null;
+    new_company: string | null;
+    new_title: string | null;
+};
+declare const PHONE_STATUS_VALUES: readonly ["valid", "invalid", "unknown"];
+type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
+declare const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: {
+    readonly id: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly personal_email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly phone: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly first_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly last_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly full_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly organization_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly title: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly industry: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly status: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly job_change: {
+        readonly identity: false;
+        readonly valueKind: "job_change";
+    };
+    readonly job_change_status: {
+        readonly identity: false;
+        readonly valueKind: "job_change_status";
+        readonly enum: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+    };
+    readonly email_status: {
+        readonly identity: false;
+        readonly valueKind: "email_status";
+    };
+    readonly phone_status: {
+        readonly identity: false;
+        readonly valueKind: "phone_status";
+        readonly enum: readonly ["valid", "invalid", "unknown"];
+    };
 };
-/**
- * Constructor input for a structured tool failure.
- *
- * Deepline creates these values while decoding the versioned wire payload.
- * Customer code normally reads `ToolExecutionError` fields instead of
- * constructing an error.
- *
- * @sdkReference errors 065
- */
-type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
-    /**
-     * Local diagnostic context inherited from DeeplineError. This is not part of
-     * the portable failure payload and is intentionally omitted by serialization.
-     */
-    details?: Record<string, unknown>;
+type DeeplineExtractorTarget = keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+declare const DEEPLINE_EXTRACTOR_TARGETS: DeeplineExtractorTarget[];
+type DeeplineEmailStatusGetterValue = EmailStatus;
+type DeeplineGetterValueMap = {
+    id: string;
+    name: string;
+    email: string;
+    personal_email: string;
+    phone: string;
+    linkedin: string;
+    linkedin_url: string;
+    domain: string;
+    website: string;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    company: string;
+    company_name: string;
+    organization_name: string;
+    company_domain: string;
+    company_website: string;
+    company_linkedin_url: string;
+    title: string;
+    industry: string;
+    status: string;
+    job_change: JobChangeGetterValue;
+    job_change_status: JobChangeStatus;
+    email_status: EmailStatus;
+    phone_status: PhoneStatus;
 };
-/**
- * Provider-owned failure categories that may fall through to another read
- * provider.
- *
- * @sdkReference errors 060
- */
-type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
-/**
- * Base error class shared by the SDK and play runtime.
- *
- * The global brand preserves `instanceof DeeplineError` when a bundled play
- * and the runtime load separate physical copies of this module.
- *
- * @sdkReference errors 010
- */
-declare class DeeplineError extends Error {
-    /** HTTP status when the failure crossed an HTTP boundary. */
-    statusCode?: number;
-    /** Stable machine-readable error code when one exists. */
-    code?: string;
-    /** Local diagnostic context; not a portable error contract. */
-    details?: Record<string, unknown>;
-    /**
-     * Construct a Deepline error.
-     *
-     * SDK and runtime code construct these errors. Application and Play code
-     * normally catches the public subclasses instead.
-     *
-     * @param message Human-readable failure summary.
-     * @param statusCode HTTP status when one exists.
-     * @param code Stable machine-readable code when one exists.
-     * @param details Local diagnostic context; never a portable error contract.
-     */
-    constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
-    static [Symbol.hasInstance](value: unknown): boolean;
+type DeeplineGetterValue<TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget> = DeeplineGetterValueMap[TTarget];
+declare function isDeeplineExtractorTarget(value: string): value is DeeplineExtractorTarget;
+
+interface PlayR2FileRef {
+    storageKind: 'r2';
+    storageKey: string;
+    logicalPath: string;
+    fileName: string;
+    contentHash: string;
+    contentType: string;
+    bytes: number;
 }
-/**
- * A failed `tools.execute` call with stable, allowlisted provenance.
- *
- * `retryable` means Deepline's delivery/idempotency contract says it is safe
- * to repeat the same semantic call. It does not describe durable receipt
- * repairability and does not make arbitrary side-effecting fallbacks safe.
- *
- * In a Play, catch `ProviderTransientError` to continue a read waterfall and
- * let every other `ToolExecutionError` remain loud. In an SDK client, catch
- * this base class when you need structured diagnostics for every tool failure.
- *
- * @sdkReference errors 070
- */
-declare class ToolExecutionError extends DeeplineError {
-    /** Public tool id passed to `tools.execute`. */
-    readonly toolId: string;
-    /** Provider responsible for the operation, or `null` when unattributed. */
-    readonly provider: string | null;
-    /** Provider operation name, or `null` when unavailable. */
-    readonly operation: string | null;
-    /** Boundary responsible for the failure. */
-    readonly origin: ToolExecutionErrorOrigin;
-    /** Stable reason family for policy and diagnostics. */
-    readonly category: ToolExecutionErrorCategory;
-    /**
-     * Whether repeating the same semantic call is delivery-safe.
-     *
-     * This does not mean the error may be ignored. Waterfall fallthrough is
-     * represented by `ProviderTransientError`.
-     */
-    readonly retryable: boolean;
-    /** Provider or Deepline request id, or `null` when unavailable. */
-    readonly requestId: string | null;
-    /** Suggested same-call retry delay in milliseconds, or `null`. */
-    readonly retryAfterMs: number | null;
-    /** Network failure kind, or `null` for non-network failures. */
-    readonly networkKind: ToolExecutionNetworkKind | null;
-    /** Network boundary that failed, or `null` for non-network failures. */
-    readonly networkScope: ToolExecutionNetworkScope | null;
-    /** Explicitly allowlisted diagnostics safe for SDK and Play callers. */
-    readonly publicDetails: ToolExecutionPublicDetails | null;
-    /**
-     * Construct a structured tool error.
-     *
-     * Deepline constructs this from the versioned `tool_error` payload.
-     * Application and Play code should catch it rather than create it.
-     */
-    constructor(message: string, options: ToolExecutionErrorOptions);
-    static [Symbol.hasInstance](value: unknown): boolean;
+type PlayExecutionFileRef = PlayR2FileRef;
+
+/** Source evidence is advisory; stored values determine lossless SQL encoding. */
+interface PlayDatasetColumnTypeEvidence {
+    postgresTypeId: number;
+    valueType: 'boolean' | 'number' | 'string' | 'json';
 }
-/**
- * A provider-owned transient failure that is safe to handle as an empty
- * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
- * never satisfy this type.
- *
- * `retryable` remains independent: it says whether the same semantic call may
- * be repeated safely. Falling through to a different read provider depends on
- * this class, not on `retryable`.
- *
- * @sdkReference errors 080
- */
-declare class ProviderTransientError extends ToolExecutionError {
-    /** Provider attribution is guaranteed for this subtype. */
-    readonly origin: "provider";
-    /** Provider failure category that made this error eligible for fallthrough. */
-    readonly category: ProviderTransientErrorCategory;
-    /** Constructed by Deepline when a provider-owned transient failure arrives. */
-    constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
-        category: ProviderTransientErrorCategory;
-    });
-    static [Symbol.hasInstance](value: unknown): boolean;
+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;
 }
-/** Why a provider cannot serve the current read request. */
-type ProviderUnavailableReason = ProviderTransientErrorCategory | 'account_capacity' | 'credentials_missing';
-/**
- * A provider failure that permits a read waterfall to try its next provider.
- * A missing provider connection is included because another provider may still
- * serve the read. Invalid credentials, caller input, and Deepline billing
- * failures remain loud.
- */
-type ProviderUnavailableError = ProviderTransientError | (ToolExecutionError & {
-    readonly origin: 'provider';
-    readonly code: 'PROVIDER_ACCOUNT_CAPACITY';
-}) | (ToolExecutionError & {
-    readonly origin: 'caller';
-    readonly code: 'INTEGRATION_CREDENTIALS_MISSING';
-});
+interface PlaySheetContract {
+    tableNamespace: string;
+    columns: PlaySheetColumnContract[];
+}
+
+declare const PLAY_DATASET_BRAND: unique symbol;
+type PlayDatasetKind = 'csv' | 'map';
+type PlayDatasetBacking = {
+    storage: 'neon_sheet';
+    sheet: {
+        playName: string;
+        tableNamespace: string;
+    };
+} | {
+    storage: 'r2_file';
+    file: PlayExecutionFileRef;
+};
+type PlayDatasetWorkProgressSummary = {
+    total: number;
+    executed: number;
+    reused: number;
+    skipped: number;
+    pending: number;
+    failed: number;
+    degraded?: boolean;
+    duplicates?: {
+        exact?: number;
+        semantic?: number;
+        rejected?: number;
+    };
+};
+type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
+type PlayDatasetRow<TInput> = TInput extends PlayDataset<infer Row> ? Row : TInput extends ReadonlyArray<infer Row> ? Row : TInput extends Iterable<infer Row> ? Row : TInput extends AsyncIterable<infer Row> ? Row : never;
+type PlayDatasetTransformOptions = {
+    key?: string;
+    sourceLabel?: string | null;
+};
 /**
- * Return the provider-specific reason a read cannot run right now.
+ * Durable handle for rows produced by `ctx.csv(...)` or `ctx.dataset(...).run()`.
  *
- * `null` means this error must stay loud: it is caller input, an invalid
- * customer credential, Deepline billing, or an internal failure. A missing
- * provider connection is different: an explicit read waterfall may continue
- * to a configured fallback and record the unavailable leg.
- */
-declare function getProviderUnavailableReason(error: unknown): ProviderUnavailableReason | null;
-/**
- * Whether a provider cannot serve this read right now.
+ * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
+ * rows, usually backed by persisted sheet storage, and carries metadata such as
+ * dataset kind, dataset id, table namespace, count, and preview rows.
  *
- * Use this in an explicit `catch` to advance a read-only waterfall. For
- * diagnostics, use `getProviderUnavailableReason(error)`.
+ * Pass dataset handles directly into later `ctx.dataset(...)` stages by default so
+ * Deepline keeps row progress, retries, memory use, and table output under
+ * runtime control. Use `count()` and `peek()` for bounded inspection. Use
+ * `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;
+ * these hide loading costs or make behavior depend on row residency.
+ *
+ * @sdkReference runtime 190
  */
-declare function isProviderUnavailable(error: unknown): error is ProviderUnavailableError;
-/** @deprecated Use isProviderUnavailable. */
-declare const isProviderWaterfallUnavailableError: typeof isProviderUnavailable;
+interface PlayDataset<T> extends AsyncIterable<T> {
+    readonly [PLAY_DATASET_BRAND]: true;
+    /** Dataset kind. */
+    readonly datasetKind: PlayDatasetKind;
+    /** Dataset id. */
+    readonly datasetId: string;
+    /** Backing store info. */
+    readonly backing?: PlayDatasetBacking;
+    /** Display label. */
+    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. */
+    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>;
+    take(limit: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;
+    /**
+     * Explicit escape hatch for bounded result sets.
+     * Large datasets should flow by handle through Neon-backed storage, not
+     * through worker memory as giant arrays.
+     */
+    materialize(options?: number | PlayDatasetMaterializeOptions): Promise<T[]>;
+    toJSON(): {
+        kind: 'dataset';
+        datasetKind: PlayDatasetKind;
+        datasetId: string;
+        count: number;
+        backing?: PlayDatasetBacking;
+        sourceLabel?: string | null;
+        tableNamespace?: string | null;
+        columns?: string[];
+        columnTypes?: PlayDatasetColumnTypes;
+        _metadata?: {
+            workProgress?: PlayDatasetWorkProgressSummary;
+        };
+        preview: T[];
+    };
+}
+type PlayDatasetMaterializeScope = 'result' | 'full_persisted_dataset';
+type PlayDatasetMaterializeOptions = {
+    /** Rows returned by this operation, or every current row in its persisted dataset. */
+    scope?: PlayDatasetMaterializeScope;
+    /** Maximum number of rows to load into memory. */
+    limit?: number;
+};
 
 /**
- * Public tool-response contracts shared by the API, SDK, Play bundler, and
- * runtime. This is a versioned response transformation contract: a change to
- * the persisted public tool-result shape must introduce a new value here and
- * have newly built Play artifacts select it. Receipt-cache revisions are
- * intentionally separate: ordinary response-contract changes do not refresh
- * durable receipts unless the response transformation changed as well.
+ * Customer pricing reported by the execution API, never provider spend.
+ * `credits_charged` and `cost_usd` describe the price of the original call;
+ * they do not acknowledge durable handoff or wallet posting. Receipt replay
+ * preserves this observation and does not imply a new charge or fresher state.
  */
-declare const V2_TOOL_RESPONSE_CONTRACT: "v2-tool-response";
-declare const RAW_V2_TOOL_RESPONSE_CONTRACT: "raw-v2";
-type ToolResponseContract = typeof V2_TOOL_RESPONSE_CONTRACT | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
-
+type ToolResultBilling = {
+    credits_charged?: number;
+    cost_usd?: number;
+    /** Missing on historical responses. Pending pricing has no final amount. */
+    pricing_status?: 'final' | 'pending';
+    settlement_status?: 'pending' | 'queued' | 'settled' | 'released' | 'requires_recovery';
+    billing_outcome_reason?: 'free_operation' | 'provider_no_billable_result' | 'provider_reported_zero_usage' | 'zero_price';
+    estimated_credits?: number;
+    estimated_cost_usd?: number;
+    /** Preserve additive public pricing details across runtime/deployment skew. */
+    [key: string]: unknown;
+};
+type ToolResultExecutionMetadata = {
+    idempotent: true;
+    cached: boolean;
+    source: 'live' | 'checkpoint' | 'cache' | 'in_flight' | 'source_run';
+    cacheKey?: string;
+    receiptRole?: 'owner' | 'follower';
+    receiptKey?: string;
+    /** Canonical saved result identity; receiptKey may name a transport alias. */
+    resultReceiptKey?: string;
+    attachedToReceiptKey?: string;
+};
+type ToolResultTargetMetadata = {
+    value: unknown;
+    path: string;
+};
+type ToolResultListMetadata = {
+    path: string;
+    count: number | null;
+    keys: Record<string, string>;
+};
+type ToolResultExtractorDescriptor = {
+    paths: readonly string[];
+    transforms?: readonly string[];
+    enum?: readonly string[];
+    overrides?: readonly ToolResultExtractorOverride[];
+    emailStatus?: EmailStatusExtractorConfig;
+};
+type ToolResultExtractorOverride = {
+    paths: readonly string[];
+    equals?: string | number | boolean | null;
+    value: string | number | boolean | null;
+};
+type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
+    get(): T | null;
+};
+type ToolResultListAccessor<T = Record<string, unknown>, TKey extends string = string> = Omit<ToolResultListMetadata, 'keys'> & {
+    keys: Partial<Record<TKey, string>> & Record<string, string>;
+    get(): PlayDataset<T>;
+};
+type ToolResponseEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
+    /** @deprecated Use declared getters or toolResponse.rawV2. */
+    raw: TData;
+    /** Complete parsed and scrubbed provider response, materialized from raw-v2. */
+    rawV2?: unknown;
+    /** Durable descriptor for deriving the legacy raw view from `rawV2`. */
+    view?: 'data' | 'rawV2';
+    meta?: TMeta;
+};
+type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
+    status: string;
+    job_id?: string;
+    /** Deepline-owned execution/result metadata. */
+    meta?: Record<string, unknown>;
+    billing?: ToolResultBilling;
+    toolResponse: ToolResponseEnvelope<TResult, TMeta>;
+    extractedValues: Record<string, ToolResultTargetAccessor>;
+    extractedLists: Record<string, ToolResultListAccessor>;
+    /** Convenience alias for play code. Serialized output uses toolResponse. */
+    toolOutput: ToolResponseEnvelope<TResult, TMeta>;
+    _metadata: {
+        toolId: string;
+        execution: ToolResultExecutionMetadata;
+        targets: Record<string, {
+            value: unknown;
+            path: string;
+        }>;
+        extractors?: Record<string, ToolResultExtractorDescriptor>;
+        lists: Record<string, {
+            path: string;
+            count: number | null;
+            keys: Record<string, string>;
+        }>;
+        /** Original declarations preserve semantic accessor names across replay. */
+        listExtractorPaths?: readonly string[];
+    };
+};
+type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
+    extractedValues: {
+        [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
+    };
+    extractedLists: {
+        [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
+    };
+};
 /**
- * Previous durable cell value passed to object-column resolvers.
+ * Canonical result returned by Deepline tool execution.
  *
- * The runtime supplies this when a row+column is being recomputed after a
- * previous value existed. `value` has the same type that the column returns;
- * freshness metadata lives beside it.
+ * The top-level object is Deepline-owned execution metadata and semantic
+ * extraction state. The canonical provider response lives under
+ * `toolResponse.rawV2`. Response metadata lives under `toolResponse.meta`. Semantic single-value
+ * getters live under `extractedValues.<name>.get()`, and list getters live
+ * under `extractedLists.<name>.get()`.
  *
- * @sdkReference runtime 120
+ * Use extractors first when a tool contract exposes them. Use list getters for
+ * row-shaped data. Use `toolResponse.rawV2` for provider-specific fields or
+ * debugging. Inspect the observed response before selecting a nested field;
+ * provider envelopes are preserved, including pagination and sibling resources.
+ * This is parsed, scrubbed data, not the original HTTP bytes or headers.
+ *
+ * @sdkReference runtime 200
  */
-type PreviousCell<Value = unknown> = {
-    /** Previous completed value for this row+column. */
-    value: Value;
-    /** Millisecond timestamp when the previous value completed. */
-    completedAt?: number;
-    /** Millisecond timestamp when the previous value becomes stale; `null` means no expiry. */
-    staleAt?: number | null;
-    /** Resolved numeric TTL in seconds for the previous value, when present. */
-    staleAfterSeconds?: number;
-};
-
-type PlaySandboxRuntimeLimits = {
-    timeoutSeconds: number;
-    memoryGiB: number;
-    cpu: number;
-    diskGiB: number;
-};
-type PlaySandboxSize = 'standard';
-type PlaySandboxRuntimeDeclaration = {
-    timeout?: string;
-    size?: PlaySandboxSize;
-};
+type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
 
 declare const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS: readonly [1, 2, 3, 4, 5, 6, 7, 8, 9];
 type PlayAuthoringContractEdition = (typeof SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS)[number];
@@ -3283,4 +3283,4 @@ type PlayCompilerManifest = {
     authoringContract?: AdmittedPlayAuthoringContract;
 };
 
-export { type DeeplineGetterValue as $, type AsyncPlayRunRef as A, type PlayAuthoringCallOptions as B, type PlayAuthoringFetchResponse as C, type PlayAuthoringInputContract as D, type PlayRunId as E, type PlayAuthoringStepProgramStep as F, type PlayAuthoringRuntimeStepOptions as G, type PlaySqlListenerDeclaration as H, type PlaySqlListenerEvent as I, type PlaySqlListenerOperation as J, type PlaySqlQuery as K, type PlayAuthoringStepOptions as L, type PlayAuthoringStepProgram as M, type PlayAuthoringStepProgramResolver as N, type PlayAuthoringStepResolver as O, type PlayArtifactKind as P, type PlayToolExecutionRequest as Q, type PlayAuthoringStepProgramOptions as R, DeeplineError as S, type ToolExecuteResult as T, ToolExecutionError as U, type ToolExecutionErrorOptions as V, CtxFetchHttpError as W, DEEPLINE_EXTRACTOR_TARGETS as X, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS as Y, type DeeplineEmailStatusGetterValue as Z, type DeeplineExtractorTarget as _, type PlayBundleArtifact as a, type DeeplineGetterValueMap as a0, JOB_CHANGE_STATUS_VALUES as a1, type JobChangeStatus as a2, PHONE_STATUS_VALUES as a3, type PhoneStatus as a4, type PlayDataset as a5, type PlayDatasetInput as a6, type PreviousCell as a7, ProviderTransientError as a8, type ProviderTransientErrorCategory as a9, type ProviderUnavailableError as aa, type ProviderUnavailableReason as ab, type ToolExecutionErrorCategory as ac, type ToolExecutionErrorOrigin as ad, type ToolExecutionFailureV1 as ae, type ToolExecutionNetworkKind as af, type ToolExecutionNetworkScope as ag, type ToolExecutionPublicDetails as ah, type ToolResultBilling as ai, getProviderUnavailableReason as aj, isDeeplineExtractorTarget as ak, isProviderUnavailable as al, isProviderWaterfallUnavailableError as am, type PlaySandboxRuntimeDeclaration as b, type PlayCompilerManifest as c, PLAY_ARTIFACT_KINDS as d, type PlayArtifactCompatibility as e, type PlayImportPolicy as f, type PlayPackageImport as g, type PlayRuntimeFeature as h, type PlayAuthoringColumnMap as i, type PlayAuthoringColumnResolver as j, type PlayAuthoringRuntimeContext as k, type PlayAuthoringConditionalStepResolver as l, type PlayAuthoringCsvInput as m, type PlayAuthoringCsvOptions as n, type PlayAuthoringDatasetBuilder as o, type PlayAuthoringDatasetColumnDefinition as p, type PlayAuthoringDatasetColumnRunInput as q, type PlayAuthoringReferenceLike as r, type PlayReturnObject as s, type PlayAuthoringDefineConfig as t, type PlayAuthoringDefinedPlay as u, type PlayAuthoringFetchOptions as v, type PlayAuthoringFileInput as w, type PlayAuthoringAsyncCallOptions as x, type PlayAuthoringBindings as y, type PlayAuthoringCallExecution as z };
+export { type DeeplineGetterValue as $, type AsyncPlayRunRef as A, type PlayAuthoringCallOptions as B, type PlayAuthoringFetchResponse as C, type PlayAuthoringInputContract as D, type PlayRunId as E, type PlayAuthoringStepProgramStep as F, type PlayAuthoringRuntimeStepOptions as G, type PlaySqlListenerDeclaration as H, type PlaySqlListenerEvent as I, type PlaySqlListenerOperation as J, type PlaySqlQuery as K, type PlayAuthoringStepOptions as L, type PlayAuthoringStepProgram as M, type PlayAuthoringStepProgramResolver as N, type PlayAuthoringStepResolver as O, PLAY_ARTIFACT_KINDS as P, type PlayToolExecutionRequest as Q, type PlayAuthoringStepProgramOptions as R, DeeplineError as S, type ToolExecuteResult as T, ToolExecutionError as U, type ToolExecutionErrorOptions as V, CtxFetchHttpError as W, DEEPLINE_EXTRACTOR_TARGETS as X, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS as Y, type DeeplineEmailStatusGetterValue as Z, type DeeplineExtractorTarget as _, type PlayArtifactCompatibility as a, type DeeplineGetterValueMap as a0, JOB_CHANGE_STATUS_VALUES as a1, type JobChangeStatus as a2, PHONE_STATUS_VALUES as a3, type PhoneStatus as a4, type PlayDataset as a5, type PlayDatasetInput as a6, type PreviousCell as a7, ProviderTransientError as a8, type ProviderTransientErrorCategory as a9, type ProviderUnavailableError as aa, type ProviderUnavailableReason as ab, type ToolExecutionErrorCategory as ac, type ToolExecutionErrorOrigin as ad, type ToolExecutionFailureV1 as ae, type ToolExecutionNetworkKind as af, type ToolExecutionNetworkScope as ag, type ToolExecutionPublicDetails as ah, type ToolResultBilling as ai, getProviderUnavailableReason as aj, isDeeplineExtractorTarget as ak, isProviderUnavailable as al, isProviderWaterfallUnavailableError as am, type PlayBundleArtifact as b, type PlayImportPolicy as c, type PlayPackageImport as d, type PlayRuntimeFeature as e, type PlaySandboxRuntimeDeclaration as f, type PlayCompilerManifest as g, type PlayArtifactKind as h, type PlayAuthoringColumnMap as i, type PlayAuthoringColumnResolver as j, type PlayAuthoringRuntimeContext as k, type PlayAuthoringConditionalStepResolver as l, type PlayAuthoringCsvInput as m, type PlayAuthoringCsvOptions as n, type PlayAuthoringDatasetBuilder as o, type PlayAuthoringDatasetColumnDefinition as p, type PlayAuthoringDatasetColumnRunInput as q, type PlayAuthoringReferenceLike as r, type PlayReturnObject as s, type PlayAuthoringDefineConfig as t, type PlayAuthoringDefinedPlay as u, type PlayAuthoringFetchOptions as v, type PlayAuthoringFileInput as w, type PlayAuthoringAsyncCallOptions as x, type PlayAuthoringBindings as y, type PlayAuthoringCallExecution as z };