deepline 0.2.49 → 0.2.51

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

@@ -711,6 +711,7 @@ export type MonitorListEntry = {
   webhook_state?: string;
   last_received_event?: string | null;
   bound_plays?: Array<Record<string, unknown>>;
+  consumer_health_truncated?: boolean;
   [key: string]: unknown;
 };
 
@@ -726,6 +727,8 @@ export type MonitorsListResult = {
   is_truncated?: boolean;
   next_cursor?: string | null;
   status_filter_applied?: string;
+  status_summary?: Array<{ status: string; count: number }>;
+  include_consumers?: boolean;
   [key: string]: unknown;
 };
 
@@ -737,6 +740,8 @@ export type MonitorsListOptions = {
   /** Page past a truncated result using a prior response's `next_cursor`. */
   cursor?: string;
   compact?: boolean;
+  /** Include bounded current SQL-listener delivery/run health (requires limit <= 20). */
+  includeConsumers?: boolean;
 };
 
 /**
@@ -814,9 +819,9 @@ export type MonitorsNamespace = {
     definition: MonitorDefinition,
     options?: { dryRun?: boolean },
   ) => Promise<MonitorDeployResult>;
-  /** List deployed monitors (active by default). */
+  /** List deployed monitors (active by default). `includeConsumers` requires limit <= 20. */
   list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
-  /** Fetch one deployed monitor by public key (without dependents). */
+  /** Fetch one deployed monitor by public key with bounded current listener health. */
   get: (key: string) => Promise<MonitorDetail>;
   /**
    * Test a deployed monitor. `validationOnly` safely verifies the callback
@@ -825,7 +830,7 @@ export type MonitorsNamespace = {
   test: (
     key: string,
     payload: Record<string, unknown>,
-    options?: { validationOnly?: boolean },
+    options?: { validationOnly?: boolean; dispatch?: boolean },
   ) => Promise<MonitorTestResult>;
   validate: (key: string) => Promise<MonitorValidateResult>;
   /** List the published plays depending on one monitor's output streams. */
@@ -4531,6 +4536,7 @@ export class DeeplineClient {
       params.set('limit', String(options.limit));
     if (options?.cursor) params.set('cursor', options.cursor);
     if (options?.compact) params.set('compact', 'true');
+    if (options?.includeConsumers) params.set('include_consumers', 'true');
     const query = params.toString();
     // Single interpolation only — see availableMonitors: a nested template in
     // the path confuses the SDK/API contract path extractor.
@@ -4552,7 +4558,7 @@ export class DeeplineClient {
   async testMonitorWebhook(
     key: string,
     payload: Record<string, unknown>,
-    options?: { validationOnly?: boolean },
+    options?: { validationOnly?: boolean; dispatch?: boolean },
   ): Promise<MonitorTestResult> {
     return this.http.request<MonitorTestResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
@@ -4560,7 +4566,11 @@ export class DeeplineClient {
         method: 'POST',
         body: {
           payload,
-          ...(options?.validationOnly ? { mode: 'validation_only' } : {}),
+          ...(options?.validationOnly
+            ? { mode: 'validation_only' }
+            : options?.dispatch
+              ? { mode: 'dispatch' }
+              : {}),
         },
       },
     );

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

@@ -160,7 +160,7 @@ export const 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.49',
+  version: '0.2.51',
   contracts: {
     api: {
       name: 'sdk-http-api',

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

@@ -1343,12 +1343,31 @@ export interface PlayCheckSqlListenerTrigger {
   };
 }
 
+/**
+ * The input delivered to a SQL-listener Play invocation. One changed Customer
+ * DB row starts one run with this top-level event object; it is not an events
+ * array or a polling batch.
+ */
+export interface PlayCheckSqlListenerEventSummary {
+  delivery: 'one_event_per_matched_row';
+  fields: Array<
+    | 'tool'
+    | 'stream'
+    | 'operation'
+    | 'before'
+    | 'after'
+    | 'changedAt'
+    | 'metadata'
+  >;
+}
+
 /**
  * Concise summary of the trigger bindings the server recognized for a play.
  * Only present triggers are populated.
  */
 export interface PlayCheckTriggersSummary {
   sqlListeners?: PlayCheckSqlListenerTrigger[];
+  sqlListenerEvent?: PlayCheckSqlListenerEventSummary;
   cron?: { schedule: string; timezone?: string };
   webhook?: true;
 }

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

@@ -157,6 +157,7 @@ import {
   validatePlayAuthoringField,
   type PlayAuthoringContractEdition,
   type PlaySqlQuery,
+  type PlayAuthoringRunScope,
   type PlayAuthoringRuntimeContext,
 } from '../plays/authoring-contract';
 import {
@@ -1338,6 +1339,7 @@ type ScalarPlayAuthoringRuntimeContext = Pick<
   PlayAuthoringRuntimeContext,
   | 'tools'
   | 'customerDb'
+  | 'run'
   | 'tool'
   | 'step'
   | 'fetch'
@@ -3332,6 +3334,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     return this.currentExecutionScope.logical.runId;
   }
 
+  get run(): PlayAuthoringRunScope {
+    return { id: this.currentRunId };
+  }
+
   private get currentReceiptOwnerRunId(): string {
     return this.currentExecutionScope.receipt.ownerRunId;
   }

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -68,6 +68,7 @@ export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
   'play_authoring_dynamic_identity_unvalidated',
   'play_authoring_fetch_secret_requires_tls',
   'play_authoring_fetch_idempotency_required',
+  'play_authoring_fetch_key_reused_in_loop',
   'play_authoring_binding_invalid',
   'play_authoring_input_schema_unresolved',
 ] as const;
@@ -215,8 +216,23 @@ export type PlayTriggerSqlListenerSummary = {
   operations: string[];
   where?: PlaySqlListenerWhere;
 };
+/** Author-facing shape of one SQL-listener invocation. */
+export type PlayTriggerSqlListenerEventSummary = {
+  delivery: 'one_event_per_matched_row';
+  fields: Array<
+    | 'tool'
+    | 'stream'
+    | 'operation'
+    | 'before'
+    | 'after'
+    | 'changedAt'
+    | 'metadata'
+  >;
+};
 export type PlayTriggersSummary = {
   sqlListeners?: PlayTriggerSqlListenerSummary[];
+  /** Present when the play has at least one sqlListener trigger. */
+  sqlListenerEvent?: PlayTriggerSqlListenerEventSummary;
   cron?: { schedule: string; timezone?: string };
   webhook?: true;
 };
@@ -237,6 +253,18 @@ export function derivePlayTriggersSummary(
         ? { where: listener.where as PlaySqlListenerWhere }
         : {}),
     }));
+    summary.sqlListenerEvent = {
+      delivery: 'one_event_per_matched_row',
+      fields: [
+        'tool',
+        'stream',
+        'operation',
+        'before',
+        'after',
+        'changedAt',
+        'metadata',
+      ],
+    };
   }
   if (bindings.cron?.schedule) {
     summary.cron = bindings.cron.timezone
@@ -652,6 +680,7 @@ export const PLAY_AUTHORING_RUNTIME_CONTEXT_MEMBERS = [
   'dataset',
   'fetch',
   'log',
+  'run',
   'runPlay',
   'runSteps',
   'secrets',
@@ -743,6 +772,31 @@ export type PlayAuthoringRunStepsOptions = {
   description?: string;
 };
 
+/**
+ * Stable identity of the currently executing Play invocation.
+ *
+ * The id is unchanged while Deepline resumes or retries the same durable run.
+ * A separately submitted run intentionally receives a new id.
+ */
+export type PlayAuthoringRunScope = {
+  readonly id: string;
+};
+
+/** Factual authoring guidance rendered into SDK and offline-agent references. */
+export const 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.',
+  },
+} as const;
+
 /** The complete customer-authored `ctx` Interface shared by every Adapter. */
 export interface PlayAuthoringRuntimeContext {
   /**
@@ -776,6 +830,12 @@ export interface PlayAuthoringRuntimeContext {
     >,
   ): never;
 
+  /**
+   * Identity for this durable run. Use this to build a replay-stable external
+   * idempotency key, for example when posting a sequence of batches.
+   */
+  readonly run: PlayAuthoringRunScope;
+
   tools: {
     /**
      * Execute a provider tool through the durable receipt contract.
@@ -2294,6 +2354,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  csv<T = Record<string, unknown>>(path: string | CsvInput<T & object>, options?: CsvOptions): Promise<PlayDataset<T>>;',
   '  dataset<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): DatasetBuilder<PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object>;',
   '  map<TSource extends PlayDatasetInput<object>>(key: string, items: TSource, options?: DatasetDefinitionOptions<PlayDatasetRow<TSource> & object>): never;',
+  '  readonly run: { readonly id: string };',
   `  runSteps<TInput extends Record<string, unknown>, TOutput>(program: RunnableStepProgram<TInput, TOutput>, input: TInput, options?: { description?: ${cloudReferenceType('ctx.runSteps.options.description')} }): Promise<TOutput>;`,
   '  tools: { execute<K extends string>(request: ToolExecutionRequest<K>): Promise<ToolExecutionOutput<K>> };',
   `  customerDb: { query<TRow extends Record<string, unknown> = Record<string, unknown>>(statement: SqlQuery, options?: { maxRows?: ${cloudReferenceType('ctx.customerDb.query.options.maxRows')}; timeoutMs?: ${cloudReferenceType('ctx.customerDb.query.options.timeoutMs')} }): Promise<TRow[]> };`,

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

@@ -10,6 +10,7 @@ import {
   join,
   relative,
   resolve,
+  sep,
 } from 'node:path';
 import { builtinModules } from 'node:module';
 import { Parser } from 'acorn';
@@ -94,6 +95,8 @@ export type PlayLocalFileDiscoveryResult = {
 
 export type PlayBundlingAdapter = {
   projectRoot: string;
+  /** Optional root used only to make source-graph identity independent of temporary absolute paths. */
+  sourceIdentityRoot?: string;
   nodeModulesDir: string;
   cacheDir?: string;
   sdkSourceRoot: string;
@@ -179,6 +182,24 @@ function sha256(value: string): string {
   return createHash('sha256').update(value).digest('hex');
 }
 
+function sourceIdentityPath(
+  filePath: string,
+  adapter: PlayBundlingAdapter,
+): string {
+  if (!adapter.sourceIdentityRoot) return filePath;
+  const identityRoot = resolve(adapter.sourceIdentityRoot);
+  const logicalPath = relative(identityRoot, resolve(filePath));
+  if (
+    !logicalPath ||
+    logicalPath === '..' ||
+    logicalPath.startsWith(`..${sep}`) ||
+    isAbsolute(logicalPath)
+  ) {
+    return filePath;
+  }
+  return logicalPath.split(/[\\/]+/).join('/');
+}
+
 function formatEsbuildMessage(message: Message): string {
   const location = message.location
     ? `${message.location.file}:${message.location.line}:${message.location.column}`
@@ -1598,9 +1619,12 @@ async function analyzeSourceGraph(
   const sourceHash = sha256(sourceCode);
   const graphHash = sha256(
     JSON.stringify({
-      entryFile: absoluteEntryFile,
+      entryFile: sourceIdentityPath(absoluteEntryFile, adapter),
       localFiles: [...localFiles.entries()]
-        .map(([filePath, contents]) => ({ filePath, hash: sha256(contents) }))
+        .map(([filePath, contents]) => ({
+          filePath: sourceIdentityPath(filePath, adapter),
+          hash: sha256(contents),
+        }))
         .sort((left, right) => left.filePath.localeCompare(right.filePath)),
       nodeBuiltins: [...nodeBuiltins].sort(),
       packages: [...packages.entries()]
@@ -1608,7 +1632,7 @@ async function analyzeSourceGraph(
         .sort((left, right) => left.name.localeCompare(right.name)),
       importedPlayDependencies: [...importedPlayDependencies.values()]
         .map((dependency) => ({
-          filePath: dependency.filePath,
+          filePath: sourceIdentityPath(dependency.filePath, adapter),
           playName: dependency.playName,
         }))
         .sort((left, right) => left.filePath.localeCompare(right.filePath)),
@@ -1660,7 +1684,7 @@ function artifactCachePath(
   adapter: PlayBundlingAdapter,
 ): string {
   return join(
-    adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR,
+    /* turbopackIgnore: true */ adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR,
     `${graphHash}.${artifactKind}.json`,
   );
 }
@@ -1672,7 +1696,11 @@ async function readArtifactCache(
 ): Promise<PlayBundleArtifact | null> {
   try {
     const serialized = await readFile(
-      artifactCachePath(graphHash, artifactKind, adapter),
+      /* turbopackIgnore: true */ artifactCachePath(
+        graphHash,
+        artifactKind,
+        adapter,
+      ),
       'utf-8',
     );
     return JSON.parse(serialized) as PlayBundleArtifact;
@@ -1686,9 +1714,9 @@ async function writeArtifactCache(
   adapter: PlayBundlingAdapter,
 ): Promise<void> {
   const cacheDir = adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR;
-  await mkdir(cacheDir, { recursive: true });
+  await mkdir(/* turbopackIgnore: true */ cacheDir, { recursive: true });
   await writeFile(
-    artifactCachePath(
+    /* turbopackIgnore: true */ artifactCachePath(
       artifact.graphHash,
       artifact.artifactKind ?? PLAY_ARTIFACT_KINDS.cjsNode20,
       adapter,

package/dist/bundling-sources/shared_libs/plays/enrich-compat-adapter.ts

@@ -0,0 +1,21 @@
+export const ENRICH_COMPAT_DEFAULT_PLAY_NAME = 'deepline-enrich-v1-compat';
+export const ENRICH_COMPAT_DEFAULT_MAP_NAME = 'deepline_enrich_rows';
+
+export type EnrichCompatibilityOptions = {
+  playName?: string;
+  mapName?: string;
+};
+
+export type EnrichCompatibilityPlan = {
+  playName: string;
+  mapName: string;
+};
+
+export function buildEnrichCompatibilityPlan(
+  options: EnrichCompatibilityOptions = {},
+): EnrichCompatibilityPlan {
+  return {
+    playName: options.playName?.trim() || ENRICH_COMPAT_DEFAULT_PLAY_NAME,
+    mapName: options.mapName?.trim() || ENRICH_COMPAT_DEFAULT_MAP_NAME,
+  };
+}