deepline 0.1.271 → 0.1.273

package/README.md

@@ -113,7 +113,7 @@ surfaces we exercise in CI:
    - `client.runs.list({ play: name })`
    - `client.runs.tail(runId)`
    - `client.runs.stop(runId, { reason })`
-3. High-level SDK handles
+3. Connected SDK context (outside a running play)
    - `ctx.play(name).run(...)`
    - `ctx.play(name).runSync(...)`
    - `ctx.runPlay(name, input)`
@@ -122,7 +122,9 @@ surfaces we exercise in CI:
    - `GET /api/v2/runs/:runId`
    - `GET /api/v2/runs/:runId/tail`
 5. In-play composition
-   - `ctx.runPlay(...)`
+   - `ctx.runPlay(key, playRef, input, { description })`
+   - Org-owned `playRef` accepts a bare name, `self/<play>`, or the canonical
+     `<orgSlug>/<play>` returned by `plays get`.
 
 Internal / advanced only:
 

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

@@ -77,6 +77,7 @@ import type {
   CustomerDbQueryResult,
   DeeplineAgentModelDescription,
 } from './types.js';
+import type { MonitorDefinition } from './monitors.js';
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
@@ -609,6 +610,151 @@ export type DbNamespace = {
   }) => Promise<CustomerDbQueryResult>;
 };
 
+/**
+ * Whether the current workspace can use Deepline Monitors, from
+ * `GET /api/v2/monitors/access`. Reachable without monitor access (requires
+ * only an authenticated session/API key); a denial is a normal 200 body, not a
+ * 403.
+ */
+export type MonitorsAccessStatus = {
+  has_access: boolean;
+  reason?: string;
+};
+
+/**
+ * The monitor tools catalog (deployable monitor TYPES), from
+ * `GET /api/v2/monitors/tools`. Server-owned shape: describing one tool returns
+ * the full payload/stream contract, while list mode returns the compact
+ * inventory. Kept as an open record so the SDK does not have to bump when the
+ * server enriches the catalog.
+ */
+export type MonitorsAvailableResult = {
+  tools?: Array<Record<string, unknown>>;
+  total?: number;
+  returned?: number;
+  is_truncated?: boolean;
+  [key: string]: unknown;
+};
+
+/** Options for `client.monitors.available(...)` (list or describe mode). */
+export type MonitorsAvailableOptions = {
+  provider?: string;
+  search?: string;
+  limit?: number | string;
+  /**
+   * Request the full catalog contract in LIST mode (payload schemas + streams).
+   * List mode is compact by default; ignored when describing a single tool.
+   */
+  full?: boolean;
+  /** Ask the server for high-signal fields only. */
+  compact?: boolean;
+};
+
+/** One deployed monitor row returned by `client.monitors.list(...)`. */
+export type MonitorListEntry = {
+  key?: string;
+  monitor_key?: string;
+  status?: string;
+  tool?: string;
+  name?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Deployed-monitor registry page from `GET /api/v2/monitors/deployed`. `total`
+ * is the TRUE registry count for the status filter, not this page's size; page
+ * past a truncated result with `next_cursor`.
+ */
+export type MonitorsListResult = {
+  monitors?: MonitorListEntry[];
+  total?: number;
+  returned?: number;
+  is_truncated?: boolean;
+  next_cursor?: string | null;
+  status_filter_applied?: string;
+  [key: string]: unknown;
+};
+
+/** Options for `client.monitors.list(...)`. */
+export type MonitorsListOptions = {
+  /** active (default), disabled, or all. */
+  status?: string;
+  limit?: number | string;
+  /** Page past a truncated result using a prior response's `next_cursor`. */
+  cursor?: string;
+  compact?: boolean;
+};
+
+/**
+ * Server-owned monitor payload shapes returned by the deploy/check/get/mutation
+ * endpoints. Kept as open records because the render layer and the endpoints
+ * own the exact field set (output contracts, pricing, reuse candidates, delete
+ * plans, dependents) and it must not require an SDK bump to evolve.
+ */
+export type MonitorCheckResult = Record<string, unknown>;
+export type MonitorDeployResult = Record<string, unknown>;
+export type MonitorDetail = Record<string, unknown>;
+export type MonitorDependents = Record<string, unknown>;
+export type MonitorUpdateResult = Record<string, unknown>;
+export type MonitorDeleteResult = Record<string, unknown>;
+export type MonitorReactivateResult = Record<string, unknown>;
+
+/**
+ * Public monitors namespace exposed as `client.monitors`.
+ *
+ * Mirrors the /api/v2/monitors resource family so the monitors CLI and
+ * programmatic callers share one product surface — every `deepline monitors`
+ * verb maps to a method here. Monitors are fully expressible as SDK code: author
+ * a definition with {@link defineMonitor}, then check/deploy/list/get/update/
+ * delete/reactivate through this namespace.
+ *
+ * @sdkReference client 040 client.monitors
+ */
+export type MonitorsNamespace = {
+  /** Whether the current workspace can use monitors (`{ has_access, reason }`). */
+  status: () => Promise<MonitorsAccessStatus>;
+  /**
+   * The deployable monitor tools catalog. Call with no tool id for the list, or
+   * with a tool id (positional or `{ tool }`) to describe one tool's full
+   * payload/stream contract.
+   */
+  available: (
+    toolIdOrOptions?: string | (MonitorsAvailableOptions & { tool?: string }),
+    options?: MonitorsAvailableOptions,
+  ) => Promise<MonitorsAvailableResult>;
+  /** Validate a monitor definition without deploying it (no spend). */
+  check: (definition: MonitorDefinition) => Promise<MonitorCheckResult>;
+  /** Deploy a monitor from a definition. May spend Deepline credits. */
+  deploy: (
+    definition: MonitorDefinition,
+    options?: { dryRun?: boolean },
+  ) => Promise<MonitorDeployResult>;
+  /** List deployed monitors (active by default). */
+  list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
+  /** Fetch one deployed monitor by public key (without dependents). */
+  get: (key: string) => Promise<MonitorDetail>;
+  /** List the published plays depending on one monitor's output streams. */
+  dependents: (key: string) => Promise<MonitorDependents>;
+  /** Update a deployed monitor by public key. */
+  update: (
+    key: string,
+    patch: Record<string, unknown>,
+  ) => Promise<MonitorUpdateResult>;
+  /**
+   * Delete a deployed monitor by public key. Deprovisions the upstream provider
+   * resource unless `localOnly` is set. `dryRun` returns the delete plan.
+   */
+  delete: (
+    key: string,
+    options?: { localOnly?: boolean; dryRun?: boolean },
+  ) => Promise<MonitorDeleteResult>;
+  /** Reactivate a disabled monitor. `dryRun` returns the reactivation cost. */
+  reactivate: (
+    key: string,
+    options?: { dryRun?: boolean },
+  ) => Promise<MonitorReactivateResult>;
+};
+
 /** One credit grant pool reported by the billing subscription status endpoint. */
 export type BillingCreditPool = {
   pool: string;
@@ -1220,6 +1366,8 @@ export class DeeplineClient {
   readonly db: DbNamespace;
   /** Billing namespace: subscription status/cancel and invoice history. */
   readonly billing: BillingNamespace;
+  /** Monitors namespace: access, catalog, deploy/check, and lifecycle. */
+  readonly monitors: MonitorsNamespace;
 
   /**
    * Create a low-level SDK client.
@@ -1256,6 +1404,19 @@ export class DeeplineClient {
         list: (options) => this.listBillingInvoices(options),
       },
     };
+    this.monitors = {
+      status: () => this.getMonitorsAccess(),
+      available: (toolIdOrOptions, options) =>
+        this.getMonitorsAvailable(toolIdOrOptions, options),
+      check: (definition) => this.checkMonitor(definition),
+      deploy: (definition, options) => this.deployMonitor(definition, options),
+      list: (options) => this.listMonitors(options),
+      get: (key) => this.getMonitor(key),
+      dependents: (key) => this.getMonitorDependents(key),
+      update: (key, patch) => this.updateMonitor(key, patch),
+      delete: (key, options) => this.deleteMonitor(key, options),
+      reactivate: (key, options) => this.reactivateMonitor(key, options),
+    };
   }
 
   /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
@@ -3710,6 +3871,192 @@ export class DeeplineClient {
     );
   }
 
+  // ——————————————————————————————————————————————————————————
+  // Monitors
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Whether the current workspace can use Deepline Monitors. Reachable without
+   * monitor access; a denial is a normal 200 body, not a 403. Prefer
+   * `client.monitors.status()`.
+   */
+  async getMonitorsAccess(): Promise<MonitorsAccessStatus> {
+    // No forbiddenAsApiError: the endpoint answers 200 in both the granted and
+    // denied cases, so a 403 would be a real auth failure, not a denial body.
+    const payload = await this.http.request<MonitorsAccessStatus>(
+      '/api/v2/monitors/access',
+      { method: 'GET' },
+    );
+    return {
+      has_access: payload.has_access === true,
+      ...(typeof payload.reason === 'string' && payload.reason.trim()
+        ? { reason: payload.reason.trim() }
+        : {}),
+    };
+  }
+
+  /**
+   * The deployable monitor tools catalog. Pass a tool id (positional or
+   * `{ tool }`) to describe one tool's full payload/stream contract, or no tool
+   * id for the compact inventory. Prefer `client.monitors.available(...)`.
+   */
+  async getMonitorsAvailable(
+    toolIdOrOptions?:
+      | string
+      | (MonitorsAvailableOptions & { tool?: string }),
+    maybeOptions?: MonitorsAvailableOptions,
+  ): Promise<MonitorsAvailableResult> {
+    const positionalTool =
+      typeof toolIdOrOptions === 'string' ? toolIdOrOptions : undefined;
+    // The first argument is either the tool id (string) or an options object.
+    // When it is a string (or omitted), `maybeOptions` carries the options;
+    // when it is an options object, use it directly.
+    const options =
+      toolIdOrOptions && typeof toolIdOrOptions === 'object'
+        ? toolIdOrOptions
+        : (maybeOptions ?? {});
+    const optionTool =
+      toolIdOrOptions && typeof toolIdOrOptions === 'object'
+        ? toolIdOrOptions.tool
+        : undefined;
+    const tool = positionalTool ?? optionTool;
+    const params = new URLSearchParams();
+    if (options.provider) params.set('provider', options.provider);
+    if (tool) params.set('tool', tool);
+    if (options.search) params.set('search', options.search);
+    if (options.limit !== undefined) params.set('limit', String(options.limit));
+    // List mode is compact by default (id + name + deployed_count). `full`
+    // restores the heavy catalog; `compact` stays an explicit alias. Describing
+    // a single tool always returns the full contract, so this is skipped there.
+    const compactList = !tool && options.full !== true;
+    if (compactList || options.compact) params.set('compact', 'true');
+    const query = params.toString();
+    // Precompute the query suffix: a nested template literal in the request
+    // path (`...tools${query ? `?...` : ''}`) breaks the SDK/API contract
+    // checker's backtick path extraction. Keep the path a single interpolation.
+    const suffix = query ? `?${query}` : '';
+    return this.http.request<MonitorsAvailableResult>(
+      `/api/v2/monitors/tools${suffix}`,
+      { method: 'GET', forbiddenAsApiError: true },
+    );
+  }
+
+  /** Validate a monitor definition without deploying it. Prefer `client.monitors.check(...)`. */
+  async checkMonitor(
+    definition: MonitorDefinition,
+  ): Promise<MonitorCheckResult> {
+    return this.http.request<MonitorCheckResult>('/api/v2/monitors/check', {
+      method: 'POST',
+      body: definition,
+      forbiddenAsApiError: true,
+    });
+  }
+
+  /**
+   * Deploy a monitor from a definition. `dryRun` validates via the check
+   * endpoint and returns the plan without deploying. Prefer
+   * `client.monitors.deploy(...)`.
+   */
+  async deployMonitor(
+    definition: MonitorDefinition,
+    options?: { dryRun?: boolean },
+  ): Promise<MonitorDeployResult> {
+    if (options?.dryRun) {
+      // The deploy plan is served by the CHECK endpoint. No deploy call is ever
+      // made in dry-run mode.
+      return this.http.request<MonitorDeployResult>('/api/v2/monitors/check', {
+        method: 'POST',
+        body: definition,
+        forbiddenAsApiError: true,
+      });
+    }
+    return this.http.request<MonitorDeployResult>('/api/v2/monitors/deploy', {
+      method: 'POST',
+      body: definition,
+      forbiddenAsApiError: true,
+    });
+  }
+
+  /** List deployed monitors. Prefer `client.monitors.list(...)`. */
+  async listMonitors(
+    options?: MonitorsListOptions,
+  ): Promise<MonitorsListResult> {
+    const params = new URLSearchParams();
+    if (options?.status) params.set('status', options.status);
+    if (options?.limit !== undefined) params.set('limit', String(options.limit));
+    if (options?.cursor) params.set('cursor', options.cursor);
+    if (options?.compact) params.set('compact', 'true');
+    const query = params.toString();
+    // Single interpolation only — see availableMonitors: a nested template in
+    // the path confuses the SDK/API contract path extractor.
+    const suffix = query ? `?${query}` : '';
+    return this.http.request<MonitorsListResult>(
+      `/api/v2/monitors/deployed${suffix}`,
+      { method: 'GET', forbiddenAsApiError: true },
+    );
+  }
+
+  /** Fetch one deployed monitor by public key. Prefer `client.monitors.get(...)`. */
+  async getMonitor(key: string): Promise<MonitorDetail> {
+    return this.http.request<MonitorDetail>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}`,
+      { method: 'GET', forbiddenAsApiError: true },
+    );
+  }
+
+  /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
+  async getMonitorDependents(key: string): Promise<MonitorDependents> {
+    return this.http.request<MonitorDependents>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/dependents`,
+      { method: 'GET', forbiddenAsApiError: true },
+    );
+  }
+
+  /** Update a deployed monitor by public key. Prefer `client.monitors.update(...)`. */
+  async updateMonitor(
+    key: string,
+    patch: Record<string, unknown>,
+  ): Promise<MonitorUpdateResult> {
+    return this.http.request<MonitorUpdateResult>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}`,
+      { method: 'PATCH', body: patch, forbiddenAsApiError: true },
+    );
+  }
+
+  /**
+   * Delete a deployed monitor by public key. Deprovisions the upstream provider
+   * resource unless `localOnly`; `dryRun` returns the delete plan. Prefer
+   * `client.monitors.delete(...)`.
+   */
+  async deleteMonitor(
+    key: string,
+    options?: { localOnly?: boolean; dryRun?: boolean },
+  ): Promise<MonitorDeleteResult> {
+    const params = new URLSearchParams();
+    if (options?.localOnly) params.set('local_only', 'true');
+    if (options?.dryRun) params.set('dry_run', 'true');
+    const query = params.toString();
+    return this.http.request<MonitorDeleteResult>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}${query ? `?${query}` : ''}`,
+      { method: 'DELETE', forbiddenAsApiError: true },
+    );
+  }
+
+  /**
+   * Reactivate a disabled monitor. `dryRun` returns the reactivation cost.
+   * Prefer `client.monitors.reactivate(...)`.
+   */
+  async reactivateMonitor(
+    key: string,
+    options?: { dryRun?: boolean },
+  ): Promise<MonitorReactivateResult> {
+    const query = options?.dryRun ? '?dry_run=true' : '';
+    return this.http.request<MonitorReactivateResult>(
+      `/api/v2/monitors/deployed/${encodeURIComponent(key)}/reactivate${query}`,
+      { method: 'POST', body: {}, forbiddenAsApiError: true },
+    );
+  }
+
   /**
    * Check API connectivity and server health.
    *

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

@@ -67,6 +67,20 @@ export type {
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
   BillingTopUpResult,
+  MonitorsNamespace,
+  MonitorsAccessStatus,
+  MonitorsAvailableOptions,
+  MonitorsAvailableResult,
+  MonitorsListOptions,
+  MonitorsListResult,
+  MonitorListEntry,
+  MonitorCheckResult,
+  MonitorDeployResult,
+  MonitorDetail,
+  MonitorDependents,
+  MonitorUpdateResult,
+  MonitorDeleteResult,
+  MonitorReactivateResult,
   IngestionStorageRepairResult,
   PlayStatus,
   PlaySheetRow,
@@ -78,6 +92,14 @@ export type {
   RunsTailOptions,
   ToolExecution,
 } from './client.js';
+
+// ——— Monitors framework ———
+export { defineMonitor } from './monitors.js';
+export type {
+  MonitorDefinition,
+  MonitorPayload,
+  MonitorControls,
+} from './monitors.js';
 export { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 export {
   DEEPLINE_TOOL_CATEGORIES,

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

@@ -0,0 +1,134 @@
+/**
+ * Monitor authoring and typing for the Deepline SDK.
+ *
+ * A **monitor** is a Deepline-native signal feed. A deployed monitor writes
+ * events into a Customer DB table (one row per finding). Plays react to those
+ * rows through `sqlListeners` bindings (see {@link definePlay}). This module is
+ * the code-first authoring surface for monitors — the same product model the
+ * `deepline monitors` CLI drives, expressed as typed SDK code.
+ *
+ * Use {@link defineMonitor} to author a typed monitor definition, then deploy or
+ * validate it with the monitors namespace:
+ *
+ * ```typescript
+ * import { DeeplineClient, defineMonitor } from 'deepline';
+ *
+ * const monitor = defineMonitor({
+ *   key: 'stripe-job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   name: 'Stripe job openings',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ *
+ * const client = new DeeplineClient();
+ * const plan = await client.monitors.check(monitor); // validate, no spend
+ * await client.monitors.deploy(monitor);             // deploy for real
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * A monitor definition: the exact object accepted by
+ * `client.monitors.check(...)` and `client.monitors.deploy(...)` and by the
+ * `/api/v2/monitors/{check,deploy}` endpoints the CLI uses.
+ *
+ * @typeParam TPayload - Provider-specific monitor payload shape (defaults to a
+ *   loose record). Pass a concrete shape to `defineMonitor<TPayload>(...)` for
+ *   compile-time checking of the payload fields.
+ */
+export type MonitorDefinition<
+  TPayload extends MonitorPayload = MonitorPayload,
+> = {
+  /** Stable public key for this monitor, unique within the workspace. */
+  key: string;
+  /** Monitor tool id, e.g. `"deepline_native.company_radar"`. */
+  tool: string;
+  /** Optional human-readable name shown in listings and detail views. */
+  name?: string;
+  /** Provider-specific monitor payload (e.g. domain + radar_type). */
+  payload: TPayload;
+  /** Optional Deepline lifecycle metadata (deploy/reuse controls). */
+  controls?: MonitorControls;
+};
+
+/** Provider-specific monitor payload. Keys and value types depend on the tool. */
+export type MonitorPayload = Record<string, unknown>;
+
+/**
+ * Deepline lifecycle metadata attached to a monitor definition. These are
+ * Deepline-side deploy/reuse controls, not provider payload fields. The set is
+ * intentionally open (server-owned) so newer controls do not require an SDK
+ * bump; known controls are typed for discoverability.
+ */
+export type MonitorControls = {
+  [key: string]: unknown;
+};
+
+/**
+ * Define a typed monitor definition.
+ *
+ * Mirrors {@link definePlay} as the code-first authoring entrypoint: it gives
+ * compile-time type safety on the definition object and returns it verbatim for
+ * passing to `client.monitors.check(...)` / `client.monitors.deploy(...)`. It
+ * performs the same lightweight local invariants the server enforces (non-empty
+ * `key` and `tool`, object `payload`) so authoring mistakes fail before a
+ * network round-trip.
+ *
+ * @typeParam TPayload - Provider payload shape.
+ * @param definition - The monitor definition.
+ * @returns The validated definition object.
+ *
+ * @example
+ * ```typescript
+ * const monitor = defineMonitor({
+ *   key: 'job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ * ```
+ */
+export function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(
+  definition: MonitorDefinition<TPayload>,
+): MonitorDefinition<TPayload> {
+  if (!definition || typeof definition !== 'object') {
+    throw new Error('defineMonitor(definition) requires a definition object.');
+  }
+  const key = typeof definition.key === 'string' ? definition.key.trim() : '';
+  if (!key) {
+    throw new Error('defineMonitor(definition) requires a non-empty "key".');
+  }
+  const tool =
+    typeof definition.tool === 'string' ? definition.tool.trim() : '';
+  if (!tool) {
+    throw new Error(
+      'defineMonitor(definition) requires a non-empty monitor tool id in "tool" ' +
+        '(e.g. "deepline_native.company_radar").',
+    );
+  }
+  if (
+    !definition.payload ||
+    typeof definition.payload !== 'object' ||
+    Array.isArray(definition.payload)
+  ) {
+    throw new Error(
+      'defineMonitor(definition) requires "payload" to be a JSON object.',
+    );
+  }
+  if (
+    definition.name !== undefined &&
+    typeof definition.name !== 'string'
+  ) {
+    throw new Error('defineMonitor(definition) "name" must be a string.');
+  }
+  if (
+    definition.controls !== undefined &&
+    (typeof definition.controls !== 'object' ||
+      Array.isArray(definition.controls))
+  ) {
+    throw new Error(
+      'defineMonitor(definition) "controls" must be a JSON object.',
+    );
+  }
+  return definition;
+}

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

@@ -117,7 +117,7 @@ import type { ToolExecution } from './client.js';
 export type PlayCallExecution = 'inline' | 'child-workflow';
 
 export interface PlayCallOptions {
-  description?: string;
+  description: string;
   execution?: PlayCallExecution;
 }
 
@@ -903,7 +903,7 @@ export interface DeeplinePlayRuntimeContext {
     key: string,
     playRef: string | PlayReferenceLike,
     input: Record<string, unknown>,
-    options?: PlayCallOptions,
+    options: PlayCallOptions,
   ): Promise<TOutput>;
 
   /**

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

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

package/dist/bundling-sources/shared_libs/play-runtime/child-execution-strategy.ts

@@ -44,9 +44,23 @@ export function ctxRunPlayInlineOnlyMessage(
     explicit_timeout: 'it sets an explicit timeout',
     explicit_child_workflow: 'it requests execution: "child-workflow"',
   };
+  const nextStep: Record<CtxRunPlayInlineOnlyReason, string> = {
+    dataset_child:
+      'Move the per-record enrichment into a scalar core play, call that core with ctx.runPlay(), and keep ctx.dataset()/ctx.csv() in the router. If this child must process a batch, trigger it as a top-level play and let it own the follow-up actions.',
+    event_wait_child:
+      'Trigger it as a top-level play. Event waits need their own run lifecycle and cannot be awaited through ctx.runPlay().',
+    suspending_child:
+      'Trigger it as a top-level play. Work that can suspend needs its own run lifecycle and cannot be awaited through ctx.runPlay().',
+    missing_static_contract:
+      'Use a published play with a resolvable static contract, or move lifecycle-owning work into a top-level play.',
+    explicit_timeout:
+      'Remove the child timeout if the child is a scalar lookup, or trigger the child as a top-level play when it needs independent timing.',
+    explicit_child_workflow:
+      'Remove execution: "child-workflow" for a scalar lookup, or trigger the child as a top-level play when it needs its own lifecycle.',
+  };
   return (
-    `${CTX_RUN_PLAY_INLINE_ONLY}: ctx.runPlay("${childPlayName}") only composes a resolved scalar child; ` +
-    `${detail[reason]}. Move that work to a top-level play and compose only the scalar result.`
+    `${CTX_RUN_PLAY_INLINE_ONLY}: ctx.runPlay("${childPlayName}") can only call a scalar, per-record play; ` +
+    `${detail[reason]}. ${nextStep[reason]}`
   );
 }
 

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

@@ -6731,6 +6731,15 @@ export class PlayContextImpl {
   ): Promise<TOutput> {
     assertNoSecretTaint(input, 'ctx.runPlay input');
     const normalizedKey = this.normalizeContextKey(key, 'runPlay');
+    if (
+      arguments.length === 3 &&
+      typeof playRef === 'object' &&
+      playRef !== null
+    ) {
+      throw new Error(
+        'ctx.runPlay(...) signature is ctx.runPlay(key, playRef, input, { description }). Add a stable call key as the first argument.',
+      );
+    }
     const resolvedName =
       typeof playRef === 'string'
         ? playRef