deepline 0.1.186 → 0.1.188

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -168,6 +168,10 @@ import {
   WorkerRunWorkDispatcher,
   type WorkerRunMapBatchesResult,
 } from './runtime/run-work-dispatcher';
+import {
+  boundedWorkflowPreviewRows,
+  WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES,
+} from './runtime/workflow-preview';
 import { WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL } from './runtime/worker-platform-budget';
 import {
   PLAY_RUNTIME_CONTRACT,
@@ -252,6 +256,7 @@ import { normalizePlayRunFailure } from '../../../shared_libs/play-runtime/run-f
 import {
   createRuntimePersistenceLatch,
   isRuntimePersistenceCircuitOpenError,
+  RuntimePersistenceCircuitOpenError,
   tripRuntimePersistenceLatch,
 } from '../../../shared_libs/play-runtime/persistence-latch';
 import {
@@ -2420,7 +2425,8 @@ type WorkerMapBlockedChunkSummary = {
 };
 
 type WorkerMapChunkSummary<T extends Record<string, unknown>> =
-  WorkerMapCompletedChunkSummary<T> | WorkerMapBlockedChunkSummary;
+  | WorkerMapCompletedChunkSummary<T>
+  | WorkerMapBlockedChunkSummary;
 
 function serializeDurableStepValue<T>(value: T, depth = 0): T {
   if (depth > 20 || value == null) return value;
@@ -2479,7 +2485,9 @@ type WorkerConditionalStepResolver = {
 type WorkerStepProgramStep = {
   name: string;
   resolver:
-    WorkerStepResolver | WorkerConditionalStepResolver | WorkerStepProgram;
+    | WorkerStepResolver
+    | WorkerConditionalStepResolver
+    | WorkerStepProgram;
 };
 
 type WorkerStepProgram = {
@@ -3416,7 +3424,9 @@ function resolveSheetContractFromReq(
   // `staticPipeline` field is what `resolveSheetContractForTableNamespace`
   // expects. Reach in safely.
   const snapshot = req.contractSnapshot as
-    { staticPipeline?: unknown } | undefined | null;
+    | { staticPipeline?: unknown }
+    | undefined
+    | null;
   const pipeline = snapshot?.staticPipeline;
   if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
     return null;
@@ -3508,7 +3518,9 @@ async function releaseRuntimeLeasesOnTeardown(input: {
 
 function staticPipelineFromReq(req: RunRequest): PlayStaticPipeline | null {
   const snapshot = req.contractSnapshot as
-    { staticPipeline?: unknown } | undefined | null;
+    | { staticPipeline?: unknown }
+    | undefined
+    | null;
   const pipeline = snapshot?.staticPipeline;
   if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
     return null;
@@ -5100,6 +5112,15 @@ function createMinimalWorkerCtx(
         }
       };
 
+      const runtimePersistenceCircuitError = (): Error | null => {
+        if (persistFailure) {
+          tripRuntimePersistenceLatch(persistenceLatch, persistFailure);
+        }
+        return persistenceLatch.tripped
+          ? new RuntimePersistenceCircuitOpenError(persistenceLatch)
+          : null;
+      };
+
       const persistExecutedRows = async () => {
         const rowsToPersist = executedRows
           .map((row, executedIndex) =>
@@ -5207,11 +5228,13 @@ function createMinimalWorkerCtx(
         pendingPersistRows = 0;
         pendingPersistBytes = 0;
         const task = persistFlushChain.then(async () => {
-          if (persistFailure) throw persistFailure;
+          const circuitError = runtimePersistenceCircuitError();
+          if (circuitError) throw circuitError;
           await persistExecutedRows();
         });
         persistFlushChain = task.catch((error) => {
           persistFailure ??= error;
+          tripRuntimePersistenceLatch(persistenceLatch, error);
         });
         return task;
       };
@@ -5296,26 +5319,31 @@ function createMinimalWorkerCtx(
         return Promise.resolve();
       };
 
-      const schedulePersistExecutedRows = () => {
-        if (persistFailure) return;
+      const schedulePersistExecutedRows = (): Promise<void> | null => {
+        const circuitError = runtimePersistenceCircuitError();
+        if (circuitError) return Promise.reject(circuitError);
         if (
           pendingPersistRows >= MAP_INCREMENTAL_PERSIST_CHUNK_ROWS ||
           pendingPersistBytes >= MAP_INCREMENTAL_PERSIST_CHUNK_BYTES
         ) {
-          void enqueuePersistExecutedRows().catch(() => undefined);
-          return;
+          return enqueuePersistExecutedRows();
         }
-        if (scheduledPersistTimer) return;
+        if (scheduledPersistTimer) return null;
         scheduledPersistTimer = setTimeout(() => {
           scheduledPersistTimer = null;
           void enqueuePersistExecutedRows().catch(() => undefined);
         }, MAP_INCREMENTAL_PERSIST_INTERVAL_MS);
+        return null;
       };
 
-      const notePersistableRow = (row: Record<string, unknown>) => {
+      const notePersistableRow = async (
+        row: Record<string, unknown>,
+      ): Promise<void> => {
         pendingPersistRows += 1;
         pendingPersistBytes += JSON.stringify(row).length;
-        schedulePersistExecutedRows();
+        await (schedulePersistExecutedRows() ?? Promise.resolve());
+        const circuitError = runtimePersistenceCircuitError();
+        if (circuitError) throw circuitError;
       };
 
       let idx = 0;
@@ -5325,6 +5353,8 @@ function createMinimalWorkerCtx(
           (async () => {
             while (true) {
               if (abortSignal?.aborted) return;
+              const circuitError = runtimePersistenceCircuitError();
+              if (circuitError) throw circuitError;
               const myIndex = idx++;
               if (myIndex >= rowsToExecute.length) return;
               const rowSlot = await governor.acquireRowSlot({
@@ -5472,7 +5502,7 @@ function createMinimalWorkerCtx(
                   executedRows[myIndex] = enriched as T &
                     Record<string, unknown>;
                   completedExecutedRows += 1;
-                  notePersistableRow(enriched);
+                  await notePersistableRow(enriched);
                   reportChunkProgress(false);
                 } catch (rowError) {
                   // Receipt persistence errors stay run-fatal, but keep the
@@ -5522,7 +5552,7 @@ function createMinimalWorkerCtx(
                   };
                   failedExecutedRows += 1;
                   if (!failFastRowErrors) {
-                    notePersistableRow(enriched);
+                    await notePersistableRow(enriched);
                   }
                   // Bounded per-chunk samples: every failure is persisted on
                   // its row, but only the first few get a log line so a wide
@@ -5636,7 +5666,8 @@ function createMinimalWorkerCtx(
           rangeStart: baseOffset + chunkStart,
           rangeEnd: baseOffset + chunkStart,
           rowsRead: chunkRows.length,
-          rowsWritten: 0,
+          rowsWritten:
+            persistedExecutedIndexes.size + persistedFailedIndexes.size,
           rowsExecuted: rowsToExecute.length,
           rowsCached: 0,
           rowsDuplicateReused: duplicateInputReuseCount,
@@ -5867,7 +5898,11 @@ function createMinimalWorkerCtx(
         // storage may keep only the bounded preview sample; same-run play code
         // that needs more rows uses volatileWorkflowChunkRows, which is not
         // part of the persisted step result.
-        preview: toWorkflowSerializableValue(publicOut.slice(0, 5)),
+        preview: boundedWorkflowPreviewRows(publicOut, {
+          maxRows: WORKER_DATASET_PREVIEW_ROWS,
+          maxBytes: WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES,
+          serialize: toWorkflowSerializableValue,
+        }),
         cachedRows:
           includeCachedRowsInChunkResult &&
           out.length <= WORKER_DATASET_IN_MEMORY_ROWS
@@ -6993,7 +7028,8 @@ function createMinimalWorkerCtx(
                 // the small structural shape ChildPlayAwait needs; bridge it the
                 // same way the inline implementation did.
                 workflowStep: workflowStep as unknown as
-                  WorkflowStepLike | undefined,
+                  | WorkflowStepLike
+                  | undefined,
                 workflowId,
                 playName: resolvedName,
                 key: normalizedKey,

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/workflow-preview.ts

@@ -0,0 +1,26 @@
+export const WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES = 64 * 1024;
+
+const jsonByteLength = (value: unknown): number =>
+  new TextEncoder().encode(JSON.stringify(value)).byteLength;
+
+export function boundedWorkflowPreviewRows<T extends Record<string, unknown>>(
+  rows: readonly T[],
+  input: {
+    maxRows: number;
+    maxBytes: number;
+    serialize?: (row: T) => T;
+  },
+): T[] {
+  const preview: T[] = [];
+  let bytes = 2; // Opening and closing array brackets.
+  for (const row of rows) {
+    if (preview.length >= input.maxRows) break;
+    const serialized = input.serialize ? input.serialize(row) : row;
+    const rowBytes = jsonByteLength(serialized) + (preview.length > 0 ? 1 : 0);
+    if (rowBytes > input.maxBytes) continue;
+    if (bytes + rowBytes > input.maxBytes) break;
+    preview.push(serialized);
+    bytes += rowBytes;
+  }
+  return preview;
+}

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

@@ -117,9 +117,16 @@ import type { ToolExecution } from './client.js';
 /**
  * Optional trigger bindings for a play.
  *
- * Plays can be triggered by webhooks (with HMAC signature verification)
- * or cron schedules. Bindings are declared as the third argument to
- * {@link definePlay}.
+ * A play can be triggered three ways, declared as the third argument to
+ * {@link definePlay}:
+ * - `webhook` — an inbound HTTP call (with optional HMAC signature verification);
+ * - `cron` — a schedule; or
+ * - `sqlListeners` — a **monitor**: the play runs whenever a monitor writes a new
+ *   row to its output stream. This is how you build a play "on top of" a monitor
+ *   (e.g. run enrichment every time a watched company posts a new job). Each
+ *   listener binds to a monitor tool id + one of its output stream keys (see
+ *   `deepline monitors available <id>` for a tool's streams and row columns).
+ *   The changed row is delivered to the handler as the listener event's `after`.
  *
  * @example Webhook with HMAC verification
  * ```typescript
@@ -141,6 +148,20 @@ import type { ToolExecution } from './client.js';
  * });
  * ```
  *
+ * @example Monitor-triggered (run a play on a monitor's output)
+ * ```typescript
+ * definePlay('on-new-job-opening', handler, {
+ *   sqlListeners: [
+ *     {
+ *       id: 'jobs',
+ *       tool: 'tamradar.company_radar',
+ *       stream: 'company_job_openings',
+ *       operations: ['INSERT'],
+ *     },
+ *   ],
+ * });
+ * ```
+ *
  * @sdkReference runtime 030
  */
 export type PlayBindings = {

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

@@ -105,10 +105,10 @@ export const SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: '0.1.186',
+  version: '0.1.188',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.186',
+    latest: '0.1.188',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

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

@@ -922,10 +922,98 @@ export interface PlayCheckResult {
   warnings?: string[];
   staticPipeline?: Record<string, unknown> | null;
   toolGetterHints?: PlayCheckToolGetterHint[];
+  /**
+   * Recognized trigger bindings parsed from the play source (`sqlListeners` /
+   * cron / webhook). Present only when the play declares at least one trigger,
+   * so an author can confirm the binding was recognized rather than silently
+   * dropped. Field names mirror the `definePlay` binding contract.
+   */
+  triggers?: PlayCheckTriggersSummary | null;
+  /**
+   * Structured, machine-actionable issues surfaced by the check. An ADDITIVE
+   * channel alongside `errors[]`: every `error`-severity issue is also present
+   * in `errors[]` (so string-level tooling keeps working), while an agent can
+   * read `code` / `validOptions` / `docsHint` to self-correct. `warning`
+   * severity issues do NOT make the check invalid.
+   */
+  issues?: PlayCheckIssue[];
+  /**
+   * Affirmative echo of what Deepline recognized — triggers, tools,
+   * datasets/columns, inputs, outputs — so a valid check reflects the parsed
+   * shape rather than a bare "ok".
+   */
+  recognized?: PlayCheckRecognizedSummary;
+  /**
+   * Human one-liner over {@link PlayCheckResult.recognized}, e.g.
+   * `1 trigger · 2 tools · 1 dataset · 14 columns`.
+   */
+  summary?: string;
   artifactHash?: string | null;
   graphHash?: string | null;
 }
 
+/** Severity of a {@link PlayCheckIssue}. `error` fails the check; `warning` does not. */
+export type PlayCheckIssueSeverity = 'error' | 'warning';
+
+/**
+ * One structured, machine-actionable issue surfaced by `deepline plays check`.
+ * Mirrors the server-side `PlayCheckIssue` contract. `code` is a stable machine
+ * code from a closed server-side set; `validOptions` enumerates the valid values
+ * (tool ids / stream keys / columns / operators) so an agent self-corrects by
+ * reading the structure instead of brute-forcing the compiler.
+ */
+export interface PlayCheckIssue {
+  code: string;
+  severity: PlayCheckIssueSeverity;
+  message: string;
+  path?: string;
+  hint?: string;
+  validOptions?: string[];
+  docsHint?: string;
+}
+
+/**
+ * Affirmative "here's what Deepline recognized" echo returned alongside a
+ * check's issues. Field names reuse the public play binding contract.
+ */
+export interface PlayCheckRecognizedSummary {
+  triggers?: PlayCheckTriggersSummary;
+  tools?: string[];
+  datasets?: { name: string; columns?: string[] }[];
+  inputs?: string[];
+  outputs?: string[];
+}
+
+/**
+ * One recognized SQL-listener trigger echoed back by {@link DeeplineClient.checkPlayArtifact}.
+ */
+export interface PlayCheckSqlListenerTrigger {
+  id: string;
+  tool?: string;
+  stream?: string;
+  operations: string[];
+  /**
+   * The recognized `sqlListeners.where` row filter, echoed back so an author can
+   * confirm Deepline bound it. Mirrors the server `StoredSqlListenerWhere` shape
+   * (`before` / `after` maps of column → operator filter). Absent when the
+   * listener declares no `where`.
+   */
+  where?: {
+    before?: Record<string, Record<string, unknown>>;
+    after?: Record<string, Record<string, unknown>>;
+  };
+}
+
+/**
+ * Concise summary of the trigger bindings the server recognized for a play.
+ * Only present triggers are populated.
+ */
+export interface PlayCheckTriggersSummary {
+  sqlListeners?: PlayCheckSqlListenerTrigger[];
+  cron?: { schedule: string; timezone?: string };
+  webhook?: true;
+}
+
 export interface PlayCheckToolGetterHint {
   toolId: string;
   lists: Array<{