deepline 0.2.47 → 0.2.49

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

@@ -818,10 +818,14 @@ export type MonitorsNamespace = {
   list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
   /** Fetch one deployed monitor by public key (without dependents). */
   get: (key: string) => Promise<MonitorDetail>;
-  /** Send an explicit payload through the deployed monitor's normal webhook path. */
+  /**
+   * Test a deployed monitor. `validationOnly` safely verifies the callback
+   * envelope; omitted options preserve the historic full-ingestion behavior.
+   */
   test: (
     key: string,
     payload: Record<string, unknown>,
+    options?: { validationOnly?: boolean },
   ) => Promise<MonitorTestResult>;
   validate: (key: string) => Promise<MonitorValidateResult>;
   /** List the published plays depending on one monitor's output streams. */
@@ -1634,7 +1638,8 @@ export class DeeplineClient {
       deploy: (definition, options) => this.deployMonitor(definition, options),
       list: (options) => this.listMonitors(options),
       get: (key) => this.getMonitor(key),
-      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      test: (key, payload, options) =>
+        this.testMonitorWebhook(key, payload, options),
       validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
@@ -4547,10 +4552,17 @@ export class DeeplineClient {
   async testMonitorWebhook(
     key: string,
     payload: Record<string, unknown>,
+    options?: { validationOnly?: boolean },
   ): Promise<MonitorTestResult> {
     return this.http.request<MonitorTestResult>(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
-      { method: 'POST', body: { payload } },
+      {
+        method: 'POST',
+        body: {
+          payload,
+          ...(options?.validationOnly ? { mode: 'validation_only' } : {}),
+        },
+      },
     );
   }
 

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

@@ -176,7 +176,8 @@ export type PlayFetchResponse = PlayAuthoringFetchResponse;
  *
  * 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);
+ * - `webhook` — an inbound HTTP call (with optional legacy HMAC or Standard
+ *   Webhooks 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
@@ -198,6 +199,19 @@ export type PlayFetchResponse = PlayAuthoringFetchResponse;
  * });
  * ```
  *
+ * @example Svix / Standard Webhooks verification with Deepline Secrets
+ * ```typescript
+ * definePlay('visitor-webhook', handler, {
+ *   webhook: {
+ *     auth: {
+ *       type: 'standard-webhooks',
+ *       headerFamily: 'svix',
+ *       signingSecrets: ['VECTOR_WEBHOOK_SECRET'],
+ *     },
+ *   },
+ * });
+ * ```
+ *
  * @example Cron schedule
  * ```typescript
  * definePlay('nightly-sync', handler, {

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.47',
+  version: '0.2.49',
   contracts: {
     api: {
       name: 'sdk-http-api',

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

@@ -1102,6 +1102,7 @@ function durableCtxKey(input: {
   id: string;
   semanticKey?: string | null;
   staleAfterSeconds?: number | null;
+  cacheEpochMs?: number;
 }): string {
   if (input.operation === 'tool') {
     throw new Error('Tool calls use tool receipt keys.');
@@ -1113,6 +1114,7 @@ function durableCtxKey(input: {
     id: input.id,
     semanticKey: input.semanticKey,
     staleAfterSeconds: input.staleAfterSeconds,
+    cacheEpochMs: input.cacheEpochMs,
   });
 }
 
@@ -1391,6 +1393,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private fixtureProviderPacingBypassLogged = false;
   private fixtureProviderPacingEnforcementLogged = false;
   private checkpoint: PlayCheckpoint;
+  private readonly durableCallCacheEpochMs: number;
   /**
    * Durable tool receipts are the replay/cache authority for the execution
    * paths the host supports. Keeping the same completed result in this
@@ -1664,6 +1667,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     };
     this.#options = options;
     this.checkpoint = options.checkpoint ?? emptyCheckpoint();
+    const checkpointCacheEpochMs = this.checkpoint.durableCallCacheEpochMs;
+    this.durableCallCacheEpochMs =
+      typeof checkpointCacheEpochMs === 'number' &&
+      Number.isFinite(checkpointCacheEpochMs) &&
+      checkpointCacheEpochMs >= 0
+        ? checkpointCacheEpochMs
+        : Date.now();
+    this.checkpoint.durableCallCacheEpochMs = this.durableCallCacheEpochMs;
     this.durableMappedToolResultsBackedByReceipts = Boolean(
       (options.claimRuntimeStepReceipt || options.claimRuntimeStepReceipts) &&
       (options.getRuntimeStepReceipt || options.getRuntimeStepReceipts) &&
@@ -3104,6 +3115,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }),
       providerActionVersion,
       staleAfterSeconds: input.staleAfterSeconds,
+      cacheEpochMs: this.durableCallCacheEpochMs,
     });
   }
 
@@ -3286,6 +3298,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         id,
         semanticKey: opts.semanticKey,
         staleAfterSeconds: stalePolicy.staleAfterSeconds,
+        cacheEpochMs: this.durableCallCacheEpochMs,
       });
     return await executeWithDurableRuntimeReceipt<T>({
       operation,

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -779,6 +779,11 @@ export interface ContextOptions {
 }
 
 export interface PlayCheckpoint {
+  /**
+   * Clock captured when this logical run first creates its context. All
+   * staleAfterSeconds receipt buckets use this value across durable resumes.
+   */
+  durableCallCacheEpochMs?: number;
   /** Waterfall batches that have completed: key = `${toolName}:${provider}`, value = results array. */
   completedBatches: Record<string, BatchResult[]>;
   /** Tool call batches that have completed: key = toolId, value = sparse row-cache-key -> result map. */

package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts

@@ -42,6 +42,8 @@ export function buildDurableToolCallCacheKey(input: {
   providerActionVersion?: string | null;
   cachePolicyVersion?: string | null;
   staleAfterSeconds?: number | null;
+  /** Run-stable clock used to choose the stale bucket. */
+  cacheEpochMs?: number;
   playLocalScope?: string | null;
 }): string {
   const orgId = input.orgId?.trim() || 'org';
@@ -70,6 +72,7 @@ export function buildDurableToolCallCacheKey(input: {
         input.cachePolicyVersion ?? DURABLE_CALL_CACHE_POLICY_VERSION,
       staleBucket: durableCacheStaleBucket({
         staleAfterSeconds: input.staleAfterSeconds,
+        nowMs: input.cacheEpochMs,
       }),
     }),
   );
@@ -84,6 +87,8 @@ export function buildDurableCtxCallCacheKey(input: {
   semanticKey?: string | null;
   cachePolicyVersion?: string | null;
   staleAfterSeconds?: number | null;
+  /** Run-stable clock used to choose the stale bucket. */
+  cacheEpochMs?: number;
 }): string {
   const orgId = input.orgId?.trim() || 'org';
   const playId = input.playId?.trim() || 'play';
@@ -104,6 +109,7 @@ export function buildDurableCtxCallCacheKey(input: {
         input.cachePolicyVersion ?? DURABLE_CALL_CACHE_POLICY_VERSION,
       staleBucket: durableCacheStaleBucket({
         staleAfterSeconds: input.staleAfterSeconds,
+        nowMs: input.cacheEpochMs,
       }),
     }),
   );

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/types.ts

@@ -32,6 +32,7 @@ export type PlayRunnerRuntimeResource = {
 
 export type RuntimeResourceTerminalReason =
   | 'completed'
+  | 'suspended'
   | 'runner_failed'
   | 'sandbox_missing'
   | 'sandbox_killed'

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

@@ -56,6 +56,7 @@ export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
   'play_authoring_billing_limit_invalid',
   'play_authoring_billing_limit_unresolved',
   'play_authoring_webhook_hmac_invalid',
+  'play_authoring_standard_webhooks_invalid',
   'play_authoring_secret_invalid',
   'play_authoring_cron_timezone_invalid',
   'play_authoring_tool_request_invalid',
@@ -83,6 +84,16 @@ export type PlayAuthoringContractIssue = {
 };
 
 export type PlaySqlListenerOperation = 'INSERT' | 'UPDATE' | 'DELETE';
+export type PlayStandardWebhookHeaderFamily = 'standard' | 'svix';
+export type PlayStandardWebhookAuth = {
+  type: 'standard-webhooks';
+  /** `webhook-*` for Standard Webhooks, `svix-*` for Svix senders. */
+  headerFamily: PlayStandardWebhookHeaderFamily;
+  /** Deepline Secret names used for ordinary operation and rotation overlap. */
+  signingSecrets: string[];
+  /** Replay-protection window. Omitted means the Standard Webhooks 5-minute default. */
+  toleranceSeconds?: number;
+};
 export const PLAY_SQL_LISTENER_WHERE_OPERATORS = [
   'eq',
   'neq',
@@ -259,6 +270,7 @@ export type PlayAuthoringAstBindings = {
       header?: string;
       secretEnv: string;
     };
+    auth?: PlayStandardWebhookAuth;
   };
   cron?: { schedule: string; timezone?: string };
   sqlListeners?: PlayAuthoringAstSqlListenerDeclaration[];
@@ -287,6 +299,7 @@ export type PlayAuthoringBindings = {
       header?: string;
       secretEnv: string;
     };
+    auth?: PlayStandardWebhookAuth;
   };
   cron?: {
     schedule: string;
@@ -973,6 +986,81 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'bindings.webhook.hmac.header must be a non-empty static string.',
   },
+  'bindings.webhook.auth.type': {
+    schema: Type.Literal('standard-webhooks'),
+    fixtures: {
+      valid: 'standard-webhooks',
+      invalid: 'svix',
+      absent: undefined,
+      unresolved: { expression: 'type' },
+      edition1: undefined,
+    },
+    referenceType: "'standard-webhooks'",
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with headerFamily and signingSecrets.
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_standard_webhooks_invalid',
+    description: 'Uses the Standard Webhooks v1 symmetric signing scheme.',
+    errorMessage:
+      'bindings.webhook.auth.type must be the static literal "standard-webhooks".',
+  },
+  'bindings.webhook.auth.headerFamily': {
+    schema: Type.Union([Type.Literal('standard'), Type.Literal('svix')]),
+    fixtures: {
+      valid: 'svix',
+      invalid: 'webhook',
+      absent: undefined,
+      unresolved: { expression: 'headerFamily' },
+      edition1: undefined,
+    },
+    referenceType: "'standard' | 'svix'",
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with type and signingSecrets.
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_standard_webhooks_invalid',
+    description: 'Header namespace expected from the webhook provider.',
+    errorMessage:
+      'bindings.webhook.auth.headerFamily must be the static literal "standard" or "svix".',
+  },
+  'bindings.webhook.auth.signingSecrets[]': {
+    schema: SecretEnvironmentNameSchema,
+    fixtures: {
+      valid: 'VECTOR_WEBHOOK_SECRET',
+      invalid: 'vector_webhook_secret',
+      absent: undefined,
+      unresolved: { expression: 'secret' },
+      edition1: undefined,
+    },
+    referenceType: 'string',
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with type and headerFamily.
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_standard_webhooks_invalid',
+    description: 'Deepline Secret name used to verify Standard Webhooks.',
+    errorMessage:
+      'bindings.webhook.auth.signingSecrets entries must be uppercase Deepline Secret names beginning with a letter.',
+  },
+  'bindings.webhook.auth.toleranceSeconds': {
+    schema: Type.Integer({ minimum: 1, maximum: 3600 }),
+    fixtures: {
+      valid: 300,
+      invalid: 0,
+      absent: undefined,
+      unresolved: { expression: 'toleranceSeconds' },
+      edition1: undefined,
+    },
+    referenceType: 'number',
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_standard_webhooks_invalid',
+    description:
+      'Accepted delivery timestamp skew in seconds, from 1 through 3600.',
+    errorMessage:
+      'bindings.webhook.auth.toleranceSeconds must be a static whole number from 1 through 3600.',
+  },
   'bindings.cron.schedule': {
     schema: Type.String({ minLength: 1 }),
     fixtures: {
@@ -2157,7 +2245,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `  inline?: ${cloudReferenceType('inline')};`,
   `  billing?: { maxCreditsPerRun?: ${cloudReferenceType('billing.maxCreditsPerRun')} };`,
   `  runtime?: { timeout?: ${cloudReferenceType('runtime.timeout')}; size?: ${cloudReferenceType('runtime.size')} };`,
-  `  webhook?: { hmac?: { algorithm?: ${cloudReferenceType('bindings.webhook.hmac.algorithm')}; header?: ${cloudReferenceType('bindings.webhook.hmac.header')}; secretEnv: ${cloudReferenceType('bindings.webhook.hmac.secretEnv')} } };`,
+  `  webhook?: { hmac?: { algorithm?: ${cloudReferenceType('bindings.webhook.hmac.algorithm')}; header?: ${cloudReferenceType('bindings.webhook.hmac.header')}; secretEnv: ${cloudReferenceType('bindings.webhook.hmac.secretEnv')} }; auth?: { type: ${cloudReferenceType('bindings.webhook.auth.type')}; headerFamily: ${cloudReferenceType('bindings.webhook.auth.headerFamily')}; signingSecrets: readonly ${cloudReferenceType('bindings.webhook.auth.signingSecrets[]')}[]; toleranceSeconds?: ${cloudReferenceType('bindings.webhook.auth.toleranceSeconds')} } };`,
   `  cron?: { schedule: ${cloudReferenceType('bindings.cron.schedule')}; timezone?: ${cloudReferenceType('bindings.cron.timezone')} };`,
   '  sqlListeners?: readonly SqlListenerDeclaration[];',
   `  secrets?: readonly ${cloudReferenceType('bindings.secrets[]')}[];`,

package/dist/cli/index.js

@@ -1044,7 +1044,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.47",
+  version: "0.2.49",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3879,7 +3879,7 @@ var DeeplineClient = class {
       deploy: (definition, options2) => this.deployMonitor(definition, options2),
       list: (options2) => this.listMonitors(options2),
       get: (key) => this.getMonitor(key),
-      test: (key, payload) => this.testMonitorWebhook(key, payload),
+      test: (key, payload, options2) => this.testMonitorWebhook(key, payload, options2),
       validate: (key) => this.validateMonitor(key),
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
@@ -6048,10 +6048,16 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
-  async testMonitorWebhook(key, payload) {
+  async testMonitorWebhook(key, payload, options) {
     return this.http.request(
       `/api/v2/monitors/deployed/${encodeURIComponent(key)}/test`,
-      { method: "POST", body: { payload } }
+      {
+        method: "POST",
+        body: {
+          payload,
+          ...options?.validationOnly ? { mode: "validation_only" } : {}
+        }
+      }
     );
   }
   async setupMonitor(tool, payload) {
@@ -15021,6 +15027,76 @@ var PLAY_AUTHORING_FIELD_REGISTRY = {
     description: "HTTP header containing the webhook signature.",
     errorMessage: "bindings.webhook.hmac.header must be a non-empty static string."
   },
+  "bindings.webhook.auth.type": {
+    schema: Type.Literal("standard-webhooks"),
+    fixtures: {
+      valid: "standard-webhooks",
+      invalid: "svix",
+      absent: void 0,
+      unresolved: { expression: "type" },
+      edition1: void 0
+    },
+    referenceType: "'standard-webhooks'",
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with headerFamily and signingSecrets.
+    required: false,
+    resolution: "static-required",
+    issueCode: "play_authoring_standard_webhooks_invalid",
+    description: "Uses the Standard Webhooks v1 symmetric signing scheme.",
+    errorMessage: 'bindings.webhook.auth.type must be the static literal "standard-webhooks".'
+  },
+  "bindings.webhook.auth.headerFamily": {
+    schema: Type.Union([Type.Literal("standard"), Type.Literal("svix")]),
+    fixtures: {
+      valid: "svix",
+      invalid: "webhook",
+      absent: void 0,
+      unresolved: { expression: "headerFamily" },
+      edition1: void 0
+    },
+    referenceType: "'standard' | 'svix'",
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with type and signingSecrets.
+    required: false,
+    resolution: "static-required",
+    issueCode: "play_authoring_standard_webhooks_invalid",
+    description: "Header namespace expected from the webhook provider.",
+    errorMessage: 'bindings.webhook.auth.headerFamily must be the static literal "standard" or "svix".'
+  },
+  "bindings.webhook.auth.signingSecrets[]": {
+    schema: SecretEnvironmentNameSchema,
+    fixtures: {
+      valid: "VECTOR_WEBHOOK_SECRET",
+      invalid: "vector_webhook_secret",
+      absent: void 0,
+      unresolved: { expression: "secret" },
+      edition1: void 0
+    },
+    referenceType: "string",
+    // auth itself is optional; once present, the AST adapter requires this
+    // field together with type and headerFamily.
+    required: false,
+    resolution: "static-required",
+    issueCode: "play_authoring_standard_webhooks_invalid",
+    description: "Deepline Secret name used to verify Standard Webhooks.",
+    errorMessage: "bindings.webhook.auth.signingSecrets entries must be uppercase Deepline Secret names beginning with a letter."
+  },
+  "bindings.webhook.auth.toleranceSeconds": {
+    schema: Type.Integer({ minimum: 1, maximum: 3600 }),
+    fixtures: {
+      valid: 300,
+      invalid: 0,
+      absent: void 0,
+      unresolved: { expression: "toleranceSeconds" },
+      edition1: void 0
+    },
+    referenceType: "number",
+    required: false,
+    resolution: "static-required",
+    issueCode: "play_authoring_standard_webhooks_invalid",
+    description: "Accepted delivery timestamp skew in seconds, from 1 through 3600.",
+    errorMessage: "bindings.webhook.auth.toleranceSeconds must be a static whole number from 1 through 3600."
+  },
   "bindings.cron.schedule": {
     schema: Type.String({ minLength: 1 }),
     fixtures: {
@@ -16045,7 +16121,7 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `  inline?: ${cloudReferenceType("inline")};`,
   `  billing?: { maxCreditsPerRun?: ${cloudReferenceType("billing.maxCreditsPerRun")} };`,
   `  runtime?: { timeout?: ${cloudReferenceType("runtime.timeout")}; size?: ${cloudReferenceType("runtime.size")} };`,
-  `  webhook?: { hmac?: { algorithm?: ${cloudReferenceType("bindings.webhook.hmac.algorithm")}; header?: ${cloudReferenceType("bindings.webhook.hmac.header")}; secretEnv: ${cloudReferenceType("bindings.webhook.hmac.secretEnv")} } };`,
+  `  webhook?: { hmac?: { algorithm?: ${cloudReferenceType("bindings.webhook.hmac.algorithm")}; header?: ${cloudReferenceType("bindings.webhook.hmac.header")}; secretEnv: ${cloudReferenceType("bindings.webhook.hmac.secretEnv")} }; auth?: { type: ${cloudReferenceType("bindings.webhook.auth.type")}; headerFamily: ${cloudReferenceType("bindings.webhook.auth.headerFamily")}; signingSecrets: readonly ${cloudReferenceType("bindings.webhook.auth.signingSecrets[]")}[]; toleranceSeconds?: ${cloudReferenceType("bindings.webhook.auth.toleranceSeconds")} } };`,
   `  cron?: { schedule: ${cloudReferenceType("bindings.cron.schedule")}; timezone?: ${cloudReferenceType("bindings.cron.timezone")} };`,
   "  sqlListeners?: readonly SqlListenerDeclaration[];",
   `  secrets?: readonly ${cloudReferenceType("bindings.secrets[]")}[];`,
@@ -30757,6 +30833,31 @@ function readDeployOutputContract(payload) {
   });
   return { tool: asString(contract.tool), streams };
 }
+function renderDeployReplacementWarning(input2) {
+  const summary = asRecord2(input2.payload.change_summary);
+  const upstream = summary ? asRecord2(summary.upstream) : void 0;
+  if (!summary || !upstream || upstream.resource_replaced !== true) return [];
+  const definition = asRecord2(summary.definition);
+  const changed = definition && Array.isArray(definition.changed) ? definition.changed : [];
+  const lines = [
+    input2.completed ? "WARNING: this deploy replaced the existing upstream monitor." : "WARNING: this deploy replaces the existing upstream monitor.",
+    "Existing Customer DB rows are preserved. Provider backfill is not implied."
+  ];
+  for (const raw of changed) {
+    const item = asRecord2(raw);
+    const path = item ? asString(item.path) : void 0;
+    if (!item || !path) continue;
+    lines.push(
+      `  ${path}: ${JSON.stringify(item.before ?? null)} \u2192 ${JSON.stringify(
+        item.after ?? null
+      )}`
+    );
+  }
+  lines.push(
+    input2.monitorKey ? `Use \`deepline monitors update ${input2.monitorKey} <patch>\` for a patch-style change.` : "Use `deepline monitors update <key> <patch>` for a patch-style change."
+  );
+  return lines;
+}
 function renderMonitorDeployCompletion(payload) {
   const monitor = asRecord2(payload.monitor);
   const key = monitor ? asString(monitor.key) : void 0;
@@ -30784,6 +30885,12 @@ function renderMonitorDeployCompletion(payload) {
   if (pricingLine) {
     lines.push("", `Pricing: ${pricingLine}`);
   }
+  const replacementWarning = renderDeployReplacementWarning({
+    payload,
+    completed: true,
+    monitorKey: key
+  });
+  if (replacementWarning.length) lines.push("", ...replacementWarning);
   const guidance = asRecord2(payload.setup_guidance);
   if (guidance) {
     const callbackUrl = asString(guidance.callback_url);
@@ -30835,6 +30942,11 @@ function renderMonitorDeployPlan(payload) {
       if (message) lines.push(`  - ${path ? `${path}: ` : ""}${message}`);
     }
   }
+  const replacementWarning = renderDeployReplacementWarning({
+    payload,
+    completed: false
+  });
+  if (replacementWarning.length) lines.push("", ...replacementWarning);
   const estimate = asRecord2(payload.deploy_cost_estimate);
   const credits = estimate ? asFiniteNumber(estimate.credits) : void 0;
   if (credits !== void 0) {
@@ -31201,10 +31313,17 @@ async function handleMonitorsGet(key, options) {
 }
 async function handleMonitorsTest(key, payload, options) {
   const explicitPayload = parseJsonObjectArg(payload, "<payload>");
-  const result = await new DeeplineClient().monitors.test(key, explicitPayload);
-  const text = `Webhook test for ${key}: ${result.accepted === true ? "accepted" : "rejected"}
-  persisted rows: ${asFiniteNumber(result.persisted_rows) ?? 0}
-  bound Plays dispatched: ${asFiniteNumber(result.dispatched_bound_plays) ?? 0}
+  const result = await new DeeplineClient().monitors.test(
+    key,
+    explicitPayload,
+    {
+      validationOnly: options.dispatch !== true
+    }
+  );
+  const dispatch = options.dispatch === true;
+  const text = `Monitor diagnostic for ${key}: ${result.accepted === true ? "accepted" : "rejected"}
+` + (dispatch ? "  mode: dispatch (writes rows and may dispatch bound Plays)\n" : "  mode: validation_only (no rows written, credits spent, or Plays dispatched)\n") + `${dispatch ? "persisted" : "would persist"} rows: ${asFiniteNumber(result.persisted_rows) ?? 0}
+${dispatch ? "dispatched" : "would dispatch"} bound Plays: ${asFiniteNumber(result.dispatched_bound_plays) ?? 0}
 `;
   printCommandEnvelope(result, { json: options.json, text });
 }
@@ -31416,12 +31535,18 @@ Examples:
   withJsonOption(
     monitors.command("test <key> <payload>").description(
       "Send an explicit payload through a monitor\u2019s webhook ingestion path."
+    ).option(
+      "--dispatch",
+      "Inject the test event through normal ingestion (writes rows and may dispatch bound Plays)"
     ).addHelpText(
       "after",
       `
 Notes:
   <payload> must be an explicit JSON object. The command uses the deployed
-  monitor\u2019s real validation, persistence, and inline Play dispatch path; it does
+  monitor\u2019s real binding and payload validation, but is a side-effect-free
+  diagnostic: it does not persist rows, spend credits, dispatch Plays, or alter
+  monitor state. Pass --dispatch only when you deliberately need the historic
+  full-ingestion test event; it can write rows and trigger bound Plays. It does
   not synthesize a provider event or accept an omitted payload.
 
 Examples:
@@ -31442,7 +31567,9 @@ Notes:
   via --file <path>, or
   from stdin with --file -. Does not deploy or spend credits.
   For Deepline Native Company Radar monitors, check validates persona-filter enums and the
-  job_titles Boolean-expression grammar locally. Inspect the exact schema with
+  job_titles Boolean-expression grammar locally (parentheses are unsupported;
+  NOT > AND > OR).
+  Inspect the exact schema with
   \`deepline monitors available deepline_native.company_radar --json\`.
 
 Examples:
@@ -31466,6 +31593,9 @@ Notes:
   --dry-run validates the definition and shows the plan (deploy cost in Deepline
   credits when the server reports it, plus any existing monitors that may
   already cover this scope) WITHOUT deploying. Exits 0 when valid, 7 when not.
+  Deploy is a full desired definition for its key: omitting a previously stored
+  field removes it and can replace the upstream resource. Use \`monitors update\`
+  for a patch-style change.
 
 Examples:
   deepline monitors deploy '{"key":"job-openings","tool":"deepline_native.company_radar","payload":{"domain":"stripe.com","radar_type":"company_job_openings"}}'