deepline 0.2.67 → 0.2.69

package/dist/{compiler-manifest-CrAB1ffd.d.mts → compiler-manifest-DFBtSjB2.d.mts}

@@ -1135,19 +1135,44 @@ type PlaySqlQuery = {
     readonly values: readonly unknown[];
 };
 declare const PLAY_SECRET_HANDLE_BRAND: unique symbol;
+/**
+ * An opaque reference to a workspace secret, returned by `ctx.secrets.get`. The handle never carries the value into play code: it stringifies to `[secret:NAME]` and throws on `JSON.stringify`, so a secret cannot reach a play variable, a log line, a dataset cell, or a replay artifact even by accident. Only the runtime resolves it, at the moment it attaches the request header.
+ *
+ * @sdkReference runtime 176 SecretHandle
+ */
 type PlaySecretHandle = {
     readonly [PLAY_SECRET_HANDLE_BRAND]: never;
+    /** Name of the workspace secret, uppercased. Never its value. */
     readonly name: string;
+    /** Renders `[secret:NAME]`, so an interpolated handle leaks nothing. */
     toString(): string;
+    /** Always throws. A secret handle is deliberately not serializable. */
     toJSON(): never;
 };
+/**
+ * One resolved authentication scheme, built by `ctx.secrets.bearer` or `ctx.secrets.header` and attached to a request through `init.auth`.
+ *
+ * @sdkReference runtime 177 SecretAuth
+ */
 type PlaySecretAuth = {
+    /** `bearer` sends `Authorization: Bearer <value>`; `header` sends a named header. */
     readonly kind: 'bearer' | 'header';
+    /** The handle whose value the runtime attaches. */
     readonly secret: PlaySecretHandle;
+    /** Header name, set only when `kind` is `header`. */
     readonly header?: string;
 };
+/**
+ * The `init` accepted by `ctx.fetch`. Same shape as `RequestInit` plus `auth`.
+ *
+ * @sdkReference runtime 174 SecretAwareRequestInit
+ */
 type PlaySecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
+    /** Ordinary request headers, recorded in the durable receipt. Never interpolate a secret value here — use `auth`. */
     headers?: HeadersInit;
+    /**
+     * The single authenticated header for this request. One value, not a list: exactly one `ctx.secrets` auth attaches per `ctx.fetch`. An API wanting two credentialed headers at once — Supabase with both `apikey` and `Authorization` — cannot express both. Put the must-stay-secret credential in `auth`; pass a genuinely non-secret second value in `headers`. If both are secret, the request needs a server-side proxy holding one of them.
+     */
     auth?: PlaySecretAuth;
 };
 type PlayLooseObject = {
@@ -1324,13 +1349,27 @@ type PlayAuthoringRuntimeStepOptions = {
 type PlayAuthoringFetchOptions = {
     staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
+/**
+ * The value `ctx.fetch(...)` resolves to: a plain durable record, not a WHATWG `Response`. The body is read once at request time so the call can be checkpointed and replayed, so `bodyText` and `json` are already-materialized properties. There is no `.json()`, `.text()`, or `.body` to await — `await res.json()` is a type error, not a typing problem.
+ *
+ * @sdkReference runtime 175 PlayFetchResponse
+ */
 type PlayAuthoringFetchResponse = {
+    /** True when the response status is in the 2xx range. */
     ok: boolean;
+    /** HTTP status code as returned by the upstream server. */
     status: number;
+    /** HTTP status text as returned by the upstream server. */
     statusText: string;
+    /** Final response URL after any redirects. */
     url: string;
+    /** Response headers, lowercased, with any known secret values redacted. */
     headers: Record<string, string>;
+    /** Full response body as text, with any known secret values redacted. */
     bodyText: string;
+    /**
+     * The parsed body, eagerly decoded at request time. Read it as a property — `const body = res.json`, never `await res.json()`. Null when the body is empty AND when it is not valid JSON: a malformed payload is reported as null rather than thrown, so check `res.ok` and fall back to `res.bodyText` before treating null as an empty result.
+     */
     json: unknown | null;
 };
 type PlayAuthoringCustomerDbQueryOptions = {
@@ -1400,8 +1439,23 @@ interface PlayAuthoringRuntimeContext {
      */
     fetch(key: string, url: string | URL, init?: PlaySecretAwareRequestInit, options?: PlayAuthoringFetchOptions): Promise<PlayAuthoringFetchResponse>;
     secrets: {
+        /**
+         * Reference a workspace secret by name without reading its value. This is the only supported way to authenticate an outbound request from a Play: `process.env.X` is rejected at check time because an env read puts the raw value in a play variable, where it can reach a log line or a replay artifact. A handle cannot — pass it to `bearer` or `header` and the runtime resolves it only while attaching the header. Names are uppercased; manage stored values with `deepline secrets set` / `deepline secrets list`.
+         *
+         * @sdkReference runtime 171 ctx.secrets.get(name)
+         */
         get(name: string): PlaySecretHandle;
+        /**
+         * Send the secret as `Authorization: Bearer <value>`.
+         *
+         * @sdkReference runtime 172 ctx.secrets.bearer(secret)
+         */
         bearer(secret: PlaySecretHandle): PlaySecretAuth;
+        /**
+         * Send the secret as a named header, for APIs that do not use bearer tokens — `x-api-key`, `apikey`, `private-token`, and similar.
+         *
+         * @sdkReference runtime 173 ctx.secrets.header(header, secret)
+         */
         header(header: string, secret: PlaySecretHandle): PlaySecretAuth;
     };
     /**
@@ -2344,6 +2398,7 @@ declare const PLAY_AUTHORING_FIELD_REGISTRY: {
         readonly issueCode: "play_authoring_durable_policy_invalid";
         readonly description: "Stable durable identity for one external HTTP request.";
         readonly errorMessage: "ctx.fetch key must be a non-empty static string.";
+        readonly unresolvedHint: "Push the aggregation server-side and call it once: a SQL function, a view, or a provider endpoint that returns the whole result. Keep unrolled literal keys only for a handful of genuinely distinct calls. To fan out over rows, use ctx.dataset with a static key — the per-row receipt identity comes from the row, not from the key. Do not compute the key.";
     };
     readonly 'ctx.fetch.staleAfterSeconds': {
         readonly schema: _sinclair_typebox.TUnion<[_sinclair_typebox.TNull, _sinclair_typebox.TInteger]>;

package/dist/{compiler-manifest-CrAB1ffd.d.ts → compiler-manifest-DFBtSjB2.d.ts}

@@ -1135,19 +1135,44 @@ type PlaySqlQuery = {
     readonly values: readonly unknown[];
 };
 declare const PLAY_SECRET_HANDLE_BRAND: unique symbol;
+/**
+ * An opaque reference to a workspace secret, returned by `ctx.secrets.get`. The handle never carries the value into play code: it stringifies to `[secret:NAME]` and throws on `JSON.stringify`, so a secret cannot reach a play variable, a log line, a dataset cell, or a replay artifact even by accident. Only the runtime resolves it, at the moment it attaches the request header.
+ *
+ * @sdkReference runtime 176 SecretHandle
+ */
 type PlaySecretHandle = {
     readonly [PLAY_SECRET_HANDLE_BRAND]: never;
+    /** Name of the workspace secret, uppercased. Never its value. */
     readonly name: string;
+    /** Renders `[secret:NAME]`, so an interpolated handle leaks nothing. */
     toString(): string;
+    /** Always throws. A secret handle is deliberately not serializable. */
     toJSON(): never;
 };
+/**
+ * One resolved authentication scheme, built by `ctx.secrets.bearer` or `ctx.secrets.header` and attached to a request through `init.auth`.
+ *
+ * @sdkReference runtime 177 SecretAuth
+ */
 type PlaySecretAuth = {
+    /** `bearer` sends `Authorization: Bearer <value>`; `header` sends a named header. */
     readonly kind: 'bearer' | 'header';
+    /** The handle whose value the runtime attaches. */
     readonly secret: PlaySecretHandle;
+    /** Header name, set only when `kind` is `header`. */
     readonly header?: string;
 };
+/**
+ * The `init` accepted by `ctx.fetch`. Same shape as `RequestInit` plus `auth`.
+ *
+ * @sdkReference runtime 174 SecretAwareRequestInit
+ */
 type PlaySecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
+    /** Ordinary request headers, recorded in the durable receipt. Never interpolate a secret value here — use `auth`. */
     headers?: HeadersInit;
+    /**
+     * The single authenticated header for this request. One value, not a list: exactly one `ctx.secrets` auth attaches per `ctx.fetch`. An API wanting two credentialed headers at once — Supabase with both `apikey` and `Authorization` — cannot express both. Put the must-stay-secret credential in `auth`; pass a genuinely non-secret second value in `headers`. If both are secret, the request needs a server-side proxy holding one of them.
+     */
     auth?: PlaySecretAuth;
 };
 type PlayLooseObject = {
@@ -1324,13 +1349,27 @@ type PlayAuthoringRuntimeStepOptions = {
 type PlayAuthoringFetchOptions = {
     staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
+/**
+ * The value `ctx.fetch(...)` resolves to: a plain durable record, not a WHATWG `Response`. The body is read once at request time so the call can be checkpointed and replayed, so `bodyText` and `json` are already-materialized properties. There is no `.json()`, `.text()`, or `.body` to await — `await res.json()` is a type error, not a typing problem.
+ *
+ * @sdkReference runtime 175 PlayFetchResponse
+ */
 type PlayAuthoringFetchResponse = {
+    /** True when the response status is in the 2xx range. */
     ok: boolean;
+    /** HTTP status code as returned by the upstream server. */
     status: number;
+    /** HTTP status text as returned by the upstream server. */
     statusText: string;
+    /** Final response URL after any redirects. */
     url: string;
+    /** Response headers, lowercased, with any known secret values redacted. */
     headers: Record<string, string>;
+    /** Full response body as text, with any known secret values redacted. */
     bodyText: string;
+    /**
+     * The parsed body, eagerly decoded at request time. Read it as a property — `const body = res.json`, never `await res.json()`. Null when the body is empty AND when it is not valid JSON: a malformed payload is reported as null rather than thrown, so check `res.ok` and fall back to `res.bodyText` before treating null as an empty result.
+     */
     json: unknown | null;
 };
 type PlayAuthoringCustomerDbQueryOptions = {
@@ -1400,8 +1439,23 @@ interface PlayAuthoringRuntimeContext {
      */
     fetch(key: string, url: string | URL, init?: PlaySecretAwareRequestInit, options?: PlayAuthoringFetchOptions): Promise<PlayAuthoringFetchResponse>;
     secrets: {
+        /**
+         * Reference a workspace secret by name without reading its value. This is the only supported way to authenticate an outbound request from a Play: `process.env.X` is rejected at check time because an env read puts the raw value in a play variable, where it can reach a log line or a replay artifact. A handle cannot — pass it to `bearer` or `header` and the runtime resolves it only while attaching the header. Names are uppercased; manage stored values with `deepline secrets set` / `deepline secrets list`.
+         *
+         * @sdkReference runtime 171 ctx.secrets.get(name)
+         */
         get(name: string): PlaySecretHandle;
+        /**
+         * Send the secret as `Authorization: Bearer <value>`.
+         *
+         * @sdkReference runtime 172 ctx.secrets.bearer(secret)
+         */
         bearer(secret: PlaySecretHandle): PlaySecretAuth;
+        /**
+         * Send the secret as a named header, for APIs that do not use bearer tokens — `x-api-key`, `apikey`, `private-token`, and similar.
+         *
+         * @sdkReference runtime 173 ctx.secrets.header(header, secret)
+         */
         header(header: string, secret: PlaySecretHandle): PlaySecretAuth;
     };
     /**
@@ -2344,6 +2398,7 @@ declare const PLAY_AUTHORING_FIELD_REGISTRY: {
         readonly issueCode: "play_authoring_durable_policy_invalid";
         readonly description: "Stable durable identity for one external HTTP request.";
         readonly errorMessage: "ctx.fetch key must be a non-empty static string.";
+        readonly unresolvedHint: "Push the aggregation server-side and call it once: a SQL function, a view, or a provider endpoint that returns the whole result. Keep unrolled literal keys only for a handful of genuinely distinct calls. To fan out over rows, use ctx.dataset with a static key — the per-row receipt identity comes from the row, not from the key. Do not compute the key.";
     };
     readonly 'ctx.fetch.staleAfterSeconds': {
         readonly schema: _sinclair_typebox.TUnion<[_sinclair_typebox.TNull, _sinclair_typebox.TInteger]>;

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest, O as PlayAuthoringStepProgramOptions } from './compiler-manifest-CrAB1ffd.mjs';
-export { Q as DEEPLINE_EXTRACTOR_TARGETS, R as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, S as DeeplineEmailStatusGetterValue, U as DeeplineExtractorTarget, V as DeeplineGetterValue, W as DeeplineGetterValueMap, X as JOB_CHANGE_STATUS_VALUES, Y as JobChangeStatus, Z as PHONE_STATUS_VALUES, _ as PhoneStatus, $ as PlayDataset, a0 as PlayDatasetInput, a1 as PreviousCell, a2 as ProviderTransientError, a3 as ProviderTransientErrorCategory, a4 as ProviderUnavailableError, a5 as ProviderUnavailableReason, a6 as ToolExecutionErrorCategory, a7 as ToolExecutionErrorOrigin, a8 as ToolExecutionFailureV1, a9 as ToolExecutionNetworkKind, aa as ToolExecutionNetworkScope, ab as getProviderUnavailableReason, ac as isDeeplineExtractorTarget, ad as isProviderUnavailable, ae as isProviderWaterfallUnavailableError } from './compiler-manifest-CrAB1ffd.mjs';
+import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest, O as PlayAuthoringStepProgramOptions } from './compiler-manifest-DFBtSjB2.mjs';
+export { Q as DEEPLINE_EXTRACTOR_TARGETS, R as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, S as DeeplineEmailStatusGetterValue, U as DeeplineExtractorTarget, V as DeeplineGetterValue, W as DeeplineGetterValueMap, X as JOB_CHANGE_STATUS_VALUES, Y as JobChangeStatus, Z as PHONE_STATUS_VALUES, _ as PhoneStatus, $ as PlayDataset, a0 as PlayDatasetInput, a1 as PreviousCell, a2 as ProviderTransientError, a3 as ProviderTransientErrorCategory, a4 as ProviderUnavailableError, a5 as ProviderUnavailableReason, a6 as ToolExecutionErrorCategory, a7 as ToolExecutionErrorOrigin, a8 as ToolExecutionFailureV1, a9 as ToolExecutionNetworkKind, aa as ToolExecutionNetworkScope, ab as getProviderUnavailableReason, ac as isDeeplineExtractorTarget, ad as isProviderUnavailable, ae as isProviderWaterfallUnavailableError } from './compiler-manifest-DFBtSjB2.mjs';
 import '@sinclair/typebox';
 
 declare const FIXTURE_BEHAVIOR_VERSION: 1;
@@ -1235,6 +1235,8 @@ interface ProductNotification {
 }
 interface PlayDescription {
     name: string;
+    /** Stable registry key. Same value `plays list` reports for this play. */
+    playKey?: string;
     reference?: string;
     displayName?: string;
     description?: string | null;
@@ -1256,6 +1258,17 @@ interface PlayDescription {
         checkCommand: string;
     };
     currentPublishedVersion?: number | null;
+    /**
+     * Version currently serving runs by name, from the live revision. Null when
+     * the play has never been published.
+     */
+    liveVersion?: number | null;
+    /** Whether this play's cron and webhook triggers are armed. */
+    triggerStatus?: {
+        cron: string | null;
+        webhook: string | null;
+        blockedReason: string | null;
+    };
     isDraftDirty?: boolean;
     latestRunId?: string | null;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest, O as PlayAuthoringStepProgramOptions } from './compiler-manifest-CrAB1ffd.js';
-export { Q as DEEPLINE_EXTRACTOR_TARGETS, R as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, S as DeeplineEmailStatusGetterValue, U as DeeplineExtractorTarget, V as DeeplineGetterValue, W as DeeplineGetterValueMap, X as JOB_CHANGE_STATUS_VALUES, Y as JobChangeStatus, Z as PHONE_STATUS_VALUES, _ as PhoneStatus, $ as PlayDataset, a0 as PlayDatasetInput, a1 as PreviousCell, a2 as ProviderTransientError, a3 as ProviderTransientErrorCategory, a4 as ProviderUnavailableError, a5 as ProviderUnavailableReason, a6 as ToolExecutionErrorCategory, a7 as ToolExecutionErrorOrigin, a8 as ToolExecutionFailureV1, a9 as ToolExecutionNetworkKind, aa as ToolExecutionNetworkScope, ab as getProviderUnavailableReason, ac as isDeeplineExtractorTarget, ad as isProviderUnavailable, ae as isProviderWaterfallUnavailableError } from './compiler-manifest-CrAB1ffd.js';
+import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest, O as PlayAuthoringStepProgramOptions } from './compiler-manifest-DFBtSjB2.js';
+export { Q as DEEPLINE_EXTRACTOR_TARGETS, R as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, S as DeeplineEmailStatusGetterValue, U as DeeplineExtractorTarget, V as DeeplineGetterValue, W as DeeplineGetterValueMap, X as JOB_CHANGE_STATUS_VALUES, Y as JobChangeStatus, Z as PHONE_STATUS_VALUES, _ as PhoneStatus, $ as PlayDataset, a0 as PlayDatasetInput, a1 as PreviousCell, a2 as ProviderTransientError, a3 as ProviderTransientErrorCategory, a4 as ProviderUnavailableError, a5 as ProviderUnavailableReason, a6 as ToolExecutionErrorCategory, a7 as ToolExecutionErrorOrigin, a8 as ToolExecutionFailureV1, a9 as ToolExecutionNetworkKind, aa as ToolExecutionNetworkScope, ab as getProviderUnavailableReason, ac as isDeeplineExtractorTarget, ad as isProviderUnavailable, ae as isProviderWaterfallUnavailableError } from './compiler-manifest-DFBtSjB2.js';
 import '@sinclair/typebox';
 
 declare const FIXTURE_BEHAVIOR_VERSION: 1;
@@ -1235,6 +1235,8 @@ interface ProductNotification {
 }
 interface PlayDescription {
     name: string;
+    /** Stable registry key. Same value `plays list` reports for this play. */
+    playKey?: string;
     reference?: string;
     displayName?: string;
     description?: string | null;
@@ -1256,6 +1258,17 @@ interface PlayDescription {
         checkCommand: string;
     };
     currentPublishedVersion?: number | null;
+    /**
+     * Version currently serving runs by name, from the live revision. Null when
+     * the play has never been published.
+     */
+    liveVersion?: number | null;
+    /** Whether this play's cron and webhook triggers are armed. */
+    triggerStatus?: {
+        cron: string | null;
+        webhook: string | null;
+        blockedReason: string | null;
+    };
     isDraftDirty?: boolean;
     latestRunId?: string | null;
 }

package/dist/index.js

@@ -780,7 +780,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.67",
+  version: "0.2.69",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -808,6 +808,13 @@ var SDK_RELEASE = {
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
+    commandIntroducedIn: [
+      {
+        command: "notifications",
+        introducedIn: "0.2.40",
+        reason: "deepline notifications was added in SDK CLI 0.2.40. Older versions have no way to configure a Play failure alert, so a cron Play that dies reports to nobody."
+      }
+    ],
     commandMinimumSupported: [
       {
         command: "enrich",
@@ -4061,6 +4068,10 @@ var DeeplineClient = class {
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
+      // playKey and triggerStatus were projected away here, so `plays describe`
+      // was strictly less informative than `plays list` for the same play — no
+      // stable key, and no way to see that a cron was armed.
+      ...play.playKey ? { playKey: play.playKey } : {},
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
@@ -4078,6 +4089,11 @@ var DeeplineClient = class {
       examples: [runCommand],
       ...cloneEditStarter ? { cloneEditStarter } : {},
       currentPublishedVersion: play.currentPublishedVersion ?? null,
+      // Read the live version off the live revision. It was previously only
+      // ever written by the publish/live routes, so every list and describe
+      // payload reported liveVersion: null even for an actively serving play.
+      liveVersion: play.liveRevision?.version ?? null,
+      ...play.triggerStatus ? { triggerStatus: play.triggerStatus } : {},
       isDraftDirty: play.isDraftDirty
     };
   }

package/dist/index.mjs

@@ -703,7 +703,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.67",
+  version: "0.2.69",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -731,6 +731,13 @@ var SDK_RELEASE = {
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
+    commandIntroducedIn: [
+      {
+        command: "notifications",
+        introducedIn: "0.2.40",
+        reason: "deepline notifications was added in SDK CLI 0.2.40. Older versions have no way to configure a Play failure alert, so a cron Play that dies reports to nobody."
+      }
+    ],
     commandMinimumSupported: [
       {
         command: "enrich",
@@ -3984,6 +3991,10 @@ var DeeplineClient = class {
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
+      // playKey and triggerStatus were projected away here, so `plays describe`
+      // was strictly less informative than `plays list` for the same play — no
+      // stable key, and no way to see that a cron was armed.
+      ...play.playKey ? { playKey: play.playKey } : {},
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
@@ -4001,6 +4012,11 @@ var DeeplineClient = class {
       examples: [runCommand],
       ...cloneEditStarter ? { cloneEditStarter } : {},
       currentPublishedVersion: play.currentPublishedVersion ?? null,
+      // Read the live version off the live revision. It was previously only
+      // ever written by the publish/live routes, so every list and describe
+      // payload reported liveVersion: null even for an actively serving play.
+      liveVersion: play.liveRevision?.version ?? null,
+      ...play.triggerStatus ? { triggerStatus: play.triggerStatus } : {},
       isDraftDirty: play.isDraftDirty
     };
   }

package/dist/install-integrity.json

@@ -225,8 +225,8 @@
     "dist/cli/index.d.ts",
     "dist/cli/index.js",
     "dist/cli/index.mjs",
-    "dist/compiler-manifest-CrAB1ffd.d.mts",
-    "dist/compiler-manifest-CrAB1ffd.d.ts",
+    "dist/compiler-manifest-DFBtSjB2.d.mts",
+    "dist/compiler-manifest-DFBtSjB2.d.ts",
     "dist/helpers.d.mts",
     "dist/helpers.d.ts",
     "dist/helpers.js",

package/dist/plays/bundle-play-file.d.mts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-CrAB1ffd.mjs';
-export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-CrAB1ffd.mjs';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-DFBtSjB2.mjs';
+export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-DFBtSjB2.mjs';
 import '@sinclair/typebox';
 
 type PlayPackageImport = {

package/dist/plays/bundle-play-file.d.ts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-CrAB1ffd.js';
-export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-CrAB1ffd.js';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-DFBtSjB2.js';
+export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-DFBtSjB2.js';
 import '@sinclair/typebox';
 
 type PlayPackageImport = {

package/dist/plays/bundle-play-file.mjs

@@ -2684,6 +2684,22 @@ var PLAY_SQL_LISTENER_TOOL_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*\.[a-zA-Z][a-zA-Z0-
 var PLAY_SQL_LISTENER_WHERE_OPERATOR_SET = new Set(
   PLAY_SQL_LISTENER_WHERE_OPERATORS
 );
+var PLAY_AUTHORING_DOCUMENTATION = {
+  fetchBatching: {
+    warning: "A static ctx.fetch key inside a loop is a warning because every iteration must still have distinct method, URL, body, or safe headers. One durable receipt must never stand in for every request.",
+    guidance: "Keep the static fetch label. For a mutating batch, make the body distinct and use a replay-stable external Idempotency-Key such as `${ctx.run.id}:signals:${batchIndex}`."
+  },
+  runId: {
+    semantics: "ctx.run.id is stable while Deepline retries or resumes one durable run. A separately submitted run receives a new id.",
+    use: "Use it when deriving an external idempotency key for a sequence of batches."
+  },
+  staticCallKeys: {
+    constraint: "Durable call keys \u2014 the ctx.fetch key, the ctx.dataset key, the ctx.step id \u2014 must be static string literals. The key names a durable receipt, so check, publish, and replay have to agree on it before the body runs. A key computed at runtime cannot be resolved at check time and is rejected.",
+    consequence: "This is an architectural constraint, not a style rule. A play cannot loop over a computed key, so it cannot page a large table with a helper like page(pageNumber). Unrolling one literal key per page is not a design at any real page count.",
+    workaround: "Push the aggregation server-side and call it once: a SQL function, a view, or a provider endpoint that returns the whole result. Keep unrolled literal keys only for a handful of genuinely distinct calls. To fan out over rows, use ctx.dataset with a static key \u2014 the per-row receipt identity comes from the row, not from the key."
+  }
+};
+var PLAY_AUTHORING_STATIC_FETCH_KEY_HINT = `${PLAY_AUTHORING_DOCUMENTATION.staticCallKeys.workaround} Do not compute the key.`;
 var SecretEnvironmentNameSchema = Type.String({
   pattern: "^[A-Z][A-Z0-9_]{1,63}$",
   description: "An uppercase environment variable name beginning with a letter."
@@ -3526,7 +3542,8 @@ var PLAY_AUTHORING_FIELD_REGISTRY = {
     resolution: "static-required",
     issueCode: "play_authoring_durable_policy_invalid",
     description: "Stable durable identity for one external HTTP request.",
-    errorMessage: "ctx.fetch key must be a non-empty static string."
+    errorMessage: "ctx.fetch key must be a non-empty static string.",
+    unresolvedHint: PLAY_AUTHORING_STATIC_FETCH_KEY_HINT
   },
   "ctx.fetch.staleAfterSeconds": {
     schema: Type.Union([Type.Null(), Type.Integer({ minimum: 0 })]),

package/package.json

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