deepline 0.3.197 → 0.3.199

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

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.197',
+  version: '0.3.199',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

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

@@ -13735,51 +13735,70 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         const suspendAfterTimeoutMs = timeoutPolicy
           ? timeoutPolicy.suspendAfterTimeoutMs
           : handler.suspendAfterTimeoutMs;
-        try {
-          await handler.onTimeout?.({
-            payload: input,
-            context: eventContext,
-            boundary: {
-              boundaryId: preparedBoundary.boundaryId,
-              eventKey: preparedBoundary.eventKey,
-              timeoutMs: preparedBoundary.timeoutMs,
-              provider: existing.provider ?? handler.provider,
-              toolId: existing.toolId ?? handler.toolId,
-              ...(existing.messageRef
-                ? { messageRef: existing.messageRef }
-                : {}),
-              ...(existing.requestKey
-                ? { requestKey: existing.requestKey }
-                : {}),
-              ...(existing.interactionId
-                ? { interactionId: existing.interactionId }
+        let timeoutFinalizedAt = existing.timeoutFinalizedAt;
+        // This is a replay acknowledgement, not exactly-once execution: a
+        // crash after the provider succeeds but before this checkpoint is
+        // durable can still repeat the finalizer on a later attempt.
+        if (timeoutFinalizedAt === undefined && handler.onTimeout) {
+          try {
+            await handler.onTimeout({
+              payload: input,
+              context: eventContext,
+              boundary: {
+                boundaryId: preparedBoundary.boundaryId,
+                eventKey: preparedBoundary.eventKey,
+                timeoutMs: preparedBoundary.timeoutMs,
+                provider: existing.provider ?? handler.provider,
+                toolId: existing.toolId ?? handler.toolId,
+                ...(existing.messageRef
+                  ? { messageRef: existing.messageRef }
+                  : {}),
+                ...(existing.requestKey
+                  ? { requestKey: existing.requestKey }
+                  : {}),
+                ...(existing.interactionId
+                  ? { interactionId: existing.interactionId }
+                  : {}),
+                ...(timeoutPolicy ? { timeoutPolicy } : {}),
+              },
+            });
+            timeoutFinalizedAt = Date.now();
+          } catch (error) {
+            this.recordSlackHitlTimeoutFailure(error);
+            throw error;
+          }
+        }
+        const persistTimeoutFinalization = (completedAt?: number) => {
+          if (
+            timeoutFinalizedAt === existing.timeoutFinalizedAt &&
+            completedAt === existing.completedAt
+          ) {
+            return;
+          }
+          this.checkpoint.resolvedBoundaries = {
+            ...(this.checkpoint.resolvedBoundaries ?? {}),
+            [preparedBoundary.boundaryId]: {
+              ...existing,
+              ...(completedAt !== undefined ? { completedAt } : {}),
+              ...(timeoutFinalizedAt !== undefined
+                ? { timeoutFinalizedAt }
                 : {}),
-              ...(timeoutPolicy ? { timeoutPolicy } : {}),
             },
-          });
-        } catch (error) {
-          this.recordSlackHitlTimeoutFailure(error);
-          throw error;
-        }
+          };
+          this.#options.onBatchComplete?.(this.checkpoint);
+        };
         if (timeoutPolicy?.timeoutOutcome === 'error') {
           // The provider finalizer above must complete first. That ordering
           // makes an expired Slack card and the terminal Play state agree,
           // while provider finalization failures stay retryable instead.
+          persistTimeoutFinalization();
           const error = new SlackHitlTimeoutError(timeoutPolicy.timeoutError);
           this.recordSlackHitlTimeoutFailure(error);
           throw error;
         }
         if (suspendAfterTimeoutMs !== undefined) {
           const finalizedAtMs = existing.completedAt ?? Date.now();
-          if (existing.completedAt === undefined) {
-            this.checkpoint.resolvedBoundaries = {
-              ...(this.checkpoint.resolvedBoundaries ?? {}),
-              [preparedBoundary.boundaryId]: {
-                ...existing,
-                completedAt: finalizedAtMs,
-              },
-            };
-          }
+          persistTimeoutFinalization(finalizedAtMs);
           this.runtimeLog(
             `Integration event ${preparedBoundary.boundaryId}: timeout finalized externally; keeping Play parked`,
           );
@@ -13792,6 +13811,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             postTimeoutPark: true,
             ...(existing.messageRef ? { messageRef: existing.messageRef } : {}),
           });
+        } else {
+          persistTimeoutFinalization();
         }
       }
       this.runtimeLog(

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

@@ -1210,6 +1210,8 @@ export interface PlayCheckpoint {
         timeoutPolicy?: IntegrationEventWaitBoundary['timeoutPolicy'];
         output?: unknown;
         completedAt?: number;
+        /** Timestamp of the successful provider timeout finalizer, if any. */
+        timeoutFinalizedAt?: number;
       }
     | {
         kind: 'fetch';

package/dist/bundling-sources/shared_libs/play-runtime/docflow-node-io.ts

@@ -78,19 +78,44 @@ type PreviewOptions = {
 
 const utf8Encoder = new TextEncoder();
 const PLAY_DATASET_BRAND = Symbol.for('deepline.play.dataset');
+const MAX_CONVEX_PREVIEW_KEY_LENGTH = 1_024;
 
 /**
  * Preview-map keys must be persistable everywhere the ledger lands, and Convex
- * reserves field names beginning with '$' (a terminal flush carrying one 500s,
- * dropping the WHOLE terminal event batch). `$output` is the wrapper's
- * whole-result path; strip the sigil so previews survive every store. Applied
- * at every build/normalize seam so live events, durable observations, and
- * replayed historical payloads all converge on the safe representation.
+ * reserves leading '$', non-ASCII/control characters, and keys over 1,024
+ * bytes. A rejected preview key poisons the whole ordered terminal batch, even
+ * when the terminal result is replaced by a scheduler reference. Keep already
+ * valid keys unchanged and encode only invalid bytes, so repeated normalization
+ * of durable observations converges on the same key. `$output` remains `output`.
  */
 export function ledgerSafeDocflowPreviewKey(key: string): string {
-  if (!key.startsWith('$')) return key;
-  const stripped = key.replace(/^\$+/, '');
-  return stripped || 'output';
+  const source = key.startsWith('$')
+    ? key.replace(/^\$+/, '') || 'output'
+    : key || 'output';
+  let encoded = '';
+  for (const character of source) {
+    const code = character.charCodeAt(0);
+    if (code >= 32 && code < 127) {
+      encoded += character;
+      continue;
+    }
+    for (const byte of utf8Encoder.encode(character)) {
+      encoded += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+  }
+  if (encoded.length <= MAX_CONVEX_PREVIEW_KEY_LENGTH) return encoded;
+
+  // Retain a readable prefix while making long, otherwise identical paths
+  // distinguishable. The suffix is stable across runtime and app deployments.
+  let hashA = 0x811c9dc5;
+  let hashB = 0x9e3779b9;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    hashA = Math.imul(hashA ^ code, 0x01000193);
+    hashB = Math.imul(hashB ^ code, 0x01000193);
+  }
+  const suffix = `~${(hashA >>> 0).toString(16).padStart(8, '0')}${(hashB >>> 0).toString(16).padStart(8, '0')}`;
+  return `${encoded.slice(0, MAX_CONVEX_PREVIEW_KEY_LENGTH - suffix.length)}${suffix}`;
 }
 
 function utf8Bytes(value: string): number {

package/dist/bundling-sources/shared_libs/play-runtime/fullenrich-batching.ts

@@ -226,4 +226,5 @@ const fullenrichBulkSelfBatchStrategy: BatchOperationStrategy<
 
 export const fullenrichBatchStrategies = defineBatchStrategyMap({
   fullenrich_bulk_enrich: fullenrichBulkSelfBatchStrategy,
+  fullenrich_enrich: fullenrichBulkSelfBatchStrategy,
 });

package/dist/bundling-sources/shared_libs/play-runtime/play-runtime-batching-registry.ts

@@ -26,7 +26,5 @@ export function getPlayRuntimeBatchStrategy(
   if (!operation) {
     return null;
   }
-  const canonicalOperation =
-    operation === 'fullenrich_enrich' ? 'fullenrich_bulk_enrich' : operation;
-  return PLAY_RUNTIME_BATCH_OPERATION_REGISTRY[canonicalOperation] ?? null;
+  return PLAY_RUNTIME_BATCH_OPERATION_REGISTRY[operation] ?? null;
 }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -12213,10 +12213,9 @@ export async function cancelPostgresSchedulerRun(
       engineTaskTable: string | null;
     };
     /**
-     * Optional control-plane ownership for the pending causal prefix. The
-     * caller resumes this same lease after commit to make cancellation visible
-     * synchronously in the canonical Run Ledger, even when a later predecessor
-     * was waiting on its retry schedule.
+     * Optional control-plane ownership for the oldest pending causal fact.
+     * Cancellation makes the remaining prefix due without sharing this lease
+     * across distinct append batches, then the caller drains it after commit.
      */
     outboxLease?: { leaseOwner: string; leaseSeconds: number };
   },
@@ -12349,11 +12348,15 @@ export async function cancelPostgresSchedulerRun(
           AND NULLIF(resource->>'sandboxId', '') IS NOT NULL
         ON CONFLICT (provider, sandbox_id, routing_domain_key) DO NOTHING
       ),
-      -- A head-only fence leaves a delayed successor between this request
-      -- and its terminal event. Own and make due the complete pending prefix;
-      -- the projector still claims it in causal order after commit.
+      -- Revoke any in-flight background lease and make the complete prefix
+      -- due, but reserve only its head. The app-side delivery validator treats
+      -- every row under one lease owner as one exact append batch. Leasing the
+      -- whole prefix here makes the first run.events append fail that check.
+      -- The head lease fences background claims until the direct projector
+      -- acknowledges it, then the next causal head can be claimed normally.
       cancellation_outbox_pending AS MATERIALIZED (
-        SELECT pending.event_id
+        SELECT pending.event_id,
+               row_number() OVER (ORDER BY ${runLedgerOrderSql('pending')}) AS position
         FROM ${tableName('outbox', options)} AS pending
         JOIN cancelled_run ON cancelled_run.run_id = pending.run_id
         WHERE pending.delivered_at IS NULL
@@ -12361,11 +12364,15 @@ export async function cancelPostgresSchedulerRun(
       ),
       cancellation_outbox_lease AS (
         UPDATE ${tableName('outbox', options)} AS pending
-        SET lease_owner = $6::text,
-            lease_expires_at = now() + make_interval(secs => $7::integer),
+        SET lease_owner = CASE WHEN prefix.position = 1 THEN $6::text ELSE NULL END,
+            lease_expires_at = CASE
+              WHEN prefix.position = 1 THEN now() + make_interval(secs => $7::integer)
+              ELSE NULL
+            END,
             next_attempt_at = NULL
+        FROM cancellation_outbox_pending AS prefix
         WHERE $6::text IS NOT NULL
-          AND pending.event_id IN (SELECT event_id FROM cancellation_outbox_pending)
+          AND pending.event_id = prefix.event_id
         RETURNING pending.event_id
       ),
       terminal_outbox AS (
@@ -12420,16 +12427,26 @@ export async function cancelPostgresSchedulerRun(
     // commits so the request can still project the winning terminal state
     // without waiting for a background lease.
     await client.query(
-      `UPDATE ${tableName('outbox', options)} AS pending
-          SET lease_owner = $2,
-              lease_expires_at = now() + make_interval(secs => $3::integer),
-              next_attempt_at = NULL
-        FROM ${tableName('runs', options)} AS terminal_run
-        WHERE pending.run_id = $1
-          AND terminal_run.run_id = pending.run_id
-          AND terminal_run.status IN ('completed', 'failed', 'cancelled')
-          AND pending.delivered_at IS NULL
-          AND pending.failed_at IS NULL`,
+      `WITH terminal_pending AS MATERIALIZED (
+         SELECT pending.event_id,
+                row_number() OVER (ORDER BY ${runLedgerOrderSql('pending')}) AS position
+         FROM ${tableName('outbox', options)} AS pending
+         JOIN ${tableName('runs', options)} AS terminal_run
+           ON terminal_run.run_id = pending.run_id
+         WHERE pending.run_id = $1
+           AND terminal_run.status IN ('completed', 'failed', 'cancelled')
+           AND pending.delivered_at IS NULL
+           AND pending.failed_at IS NULL
+       )
+       UPDATE ${tableName('outbox', options)} AS pending
+       SET lease_owner = CASE WHEN prefix.position = 1 THEN $2 ELSE NULL END,
+           lease_expires_at = CASE
+             WHEN prefix.position = 1 THEN now() + make_interval(secs => $3::integer)
+             ELSE NULL
+           END,
+           next_attempt_at = NULL
+       FROM terminal_pending AS prefix
+       WHERE pending.event_id = prefix.event_id`,
       [input.runId, outboxLeaseOwner, outboxLeaseSeconds],
     );
   }
@@ -15697,7 +15714,7 @@ export async function renewPostgresRunLedgerDelivery(
     throw new RunLedgerProjectionLeaseLostError();
 }
 
-/** Only a currently claimed outbox batch may use the projection write path. */
+/** Only the currently claimed causal prefix may use the projection write path. */
 export async function assertPostgresRunLedgerDelivery(
   client: PostgresSchedulerQueryClient,
   input: {
@@ -15711,64 +15728,106 @@ export async function assertPostgresRunLedgerDelivery(
   const result = await client.query<{
     delivery_key: string;
     event_type: string;
-    lease_owner: string;
+    lease_owner: string | null;
+    lease_live: boolean;
+    due: boolean;
+    blocked: boolean;
   }>(
     `
-    SELECT outbox.delivery_key, outbox.event_type, outbox.lease_owner
+    SELECT outbox.delivery_key,
+           outbox.event_type,
+           outbox.lease_owner,
+           outbox.lease_expires_at > now() AS lease_live,
+           coalesce(outbox.next_attempt_at, outbox.created_at) <= now() AS due,
+           outbox.failed_at IS NOT NULL AS blocked
     FROM ${tableName('outbox', options)} AS outbox
     JOIN ${tableName('runs', options)} AS runs ON runs.run_id = outbox.run_id
     WHERE outbox.run_id = $1 AND runs.org_id = $2
-      AND outbox.delivered_at IS NULL AND outbox.failed_at IS NULL
-      AND outbox.lease_owner IS NOT NULL AND outbox.lease_expires_at > now()
-      AND ($3::text IS NULL OR outbox.lease_owner = $3)
-    ORDER BY outbox.created_at, outbox.event_id
+      AND outbox.delivered_at IS NULL
+    ORDER BY ${runLedgerOrderSql('outbox')}
   `,
-    [input.runId, input.orgId, input.leaseOwner ?? null],
+    [input.runId, input.orgId],
   );
-  const groups = new Map<string, typeof result.rows>();
-  for (const row of result.rows) {
-    const group = groups.get(row.lease_owner) ?? [];
-    group.push(row);
-    groups.set(row.lease_owner, group);
+  const rows = result.rows;
+  const leaseOwner = input.leaseOwner?.trim() || rows[0]?.lease_owner;
+  if (!leaseOwner || rows[0]?.lease_owner !== leaseOwner) {
+    throw new RunLedgerProjectionLeaseLostError();
   }
-  for (const rows of groups.values()) {
-    const digest = createHash('sha256')
-      .update(rows.map((row) => row.delivery_key).join('\n'))
-      .digest('hex');
-    const batchKey = buildRunLedgerEventsIdempotencyKey({
-      runId: input.runId,
-      deliveryDigest: digest,
-    });
-    const terminal = [...rows]
-      .reverse()
-      .find((row) =>
-        ['run.completed', 'run.failed', 'run.cancelled'].includes(
-          row.event_type,
-        ),
-      );
-    // The old one-row dispatcher uses run-terminal for nonterminal facts too.
-    const single = rows.length === 1 ? rows[0] : terminal;
-    const terminalKey = single
-      ? buildRunLedgerTerminalIdempotencyKey({
+
+  // A normal projector leases only the batch it is about to send. Cancellation
+  // intentionally transfers the entire pending causal prefix to one stable
+  // owner before synchronously draining it, while run.events are still claimed
+  // one row at a time. Validate the submitted key against a *contiguous due
+  // prefix*, not every row carrying that owner; otherwise a valid cancellation
+  // head is rejected whenever later facts share the cancellation lease.
+  const prefix: typeof rows = [];
+  for (const row of rows) {
+    if (
+      row.lease_owner !== leaseOwner ||
+      row.lease_live !== true ||
+      row.due !== true ||
+      row.blocked === true
+    ) {
+      break;
+    }
+    if (prefix.length > 0 && row.event_type === 'run.events') break;
+    prefix.push(row);
+
+    const first = prefix[0]!;
+    const terminal = prefix.find((candidate) =>
+      ['run.completed', 'run.failed', 'run.cancelled'].includes(
+        candidate.event_type,
+      ),
+    );
+    let expectedKey: string;
+    if (terminal) {
+      expectedKey = buildRunLedgerTerminalIdempotencyKey({
+        runId: input.runId,
+        deliveryKey: terminal.delivery_key,
+      });
+    } else if (
+      prefix.length === 1 &&
+      ['run.created', 'run.started'].includes(first.event_type)
+    ) {
+      expectedKey = buildRunLedgerStartIdempotencyKey({
+        runId: input.runId,
+        deliveryKey: first.delivery_key,
+      });
+    } else {
+      const digest = createHash('sha256')
+        .update(prefix.map((candidate) => candidate.delivery_key).join('\n'))
+        .digest('hex');
+      expectedKey = buildRunLedgerEventsIdempotencyKey({
+        runId: input.runId,
+        deliveryDigest: digest,
+      });
+    }
+    if (input.idempotencyKey === expectedKey) return;
+
+    // The pre-batch projector used run-terminal:<delivery-key> for a single
+    // nonterminal fact. Retain that wire-compatibility key for the current
+    // singleton head, but never let it authorize a later row in the prefix.
+    if (
+      prefix.length === 1 &&
+      !['run.created', 'run.started'].includes(first.event_type) &&
+      input.idempotencyKey ===
+        buildRunLedgerTerminalIdempotencyKey({
           runId: input.runId,
-          deliveryKey: single.delivery_key,
+          deliveryKey: first.delivery_key,
         })
-      : null;
-    const startKey =
-      rows.length === 1 &&
-      single &&
-      ['run.created', 'run.started'].includes(single.event_type)
-        ? buildRunLedgerStartIdempotencyKey({
-            runId: input.runId,
-            deliveryKey: single.delivery_key,
-          })
-        : null;
-    if (
-      input.idempotencyKey === batchKey ||
-      input.idempotencyKey === terminalKey ||
-      input.idempotencyKey === startKey
-    )
+    ) {
       return;
+    }
+
+    if (
+      prefix.length === 1 &&
+      ['run.created', 'run.started', 'run.events'].includes(first.event_type)
+    ) {
+      break;
+    }
+    if (terminal || prefix.length >= 8) {
+      break;
+    }
   }
   throw new RunLedgerProjectionLeaseLostError();
 }
@@ -16948,6 +17007,7 @@ export async function dispatchRunLedgerOutboxToLedgerThroughEventWithClientScope
         withClient,
         {
           ...input,
+          waitForRunLock: true,
           limit:
             remaining === null ? batchSize : Math.min(batchSize, remaining),
         },
@@ -17022,7 +17082,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
   withClient: <T>(
     operation: (client: PostgresSchedulerQueryClient) => Promise<T>,
   ) => Promise<T>,
-  input: RunLedgerOutboxDispatchInput,
+  input: RunLedgerOutboxDispatchInput & { waitForRunLock?: boolean },
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<PostgresSchedulerOutboxProjectionResult> {
   const leaseOwner =
@@ -17035,6 +17095,26 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
     await client.query('BEGIN');
     try {
       const targetRunId = input.runId?.trim() || null;
+      if (input.waitForRunLock && targetRunId) {
+        // A synchronous drain must not mistake a busy run for an empty
+        // outbox. In particular, cancellation owns its pending prefix lease,
+        // so returning early also prevents background recovery from helping.
+        // Wait only for this run, under the existing cancellation SQL budget,
+        // then select the prefix using a fresh READ COMMITTED snapshot. The
+        // transaction still ends before HTTP; background claims keep SKIP LOCKED.
+        await client.query(
+          `SELECT set_config('lock_timeout', $1, true),
+                  set_config('statement_timeout', $2, true)`,
+          [
+            `${RUNTIME_SCHEDULER_CANCEL_LOCK_TIMEOUT_MS}ms`,
+            `${RUNTIME_SCHEDULER_CANCEL_STATEMENT_TIMEOUT_MS}ms`,
+          ],
+        );
+        await client.query(
+          `SELECT run_id FROM ${tableName('runs', options)} WHERE run_id = $1 FOR UPDATE`,
+          [targetRunId],
+        );
+      }
       // A worker fast path always names one run. Keep that lookup on the
       // run-scoped outbox prefix: combining it with global recovery through a
       // nullable predicate made PostgreSQL materialize every pending run head

package/dist/cli/index.js

@@ -3051,7 +3051,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -4699,10 +4699,30 @@ var DOCFLOW_NODE_IO_LIMITS = {
 };
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
+var MAX_CONVEX_PREVIEW_KEY_LENGTH = 1024;
 function ledgerSafeDocflowPreviewKey(key) {
-  if (!key.startsWith("$")) return key;
-  const stripped = key.replace(/^\$+/, "");
-  return stripped || "output";
+  const source = key.startsWith("$") ? key.replace(/^\$+/, "") || "output" : key || "output";
+  let encoded = "";
+  for (const character of source) {
+    const code = character.charCodeAt(0);
+    if (code >= 32 && code < 127) {
+      encoded += character;
+      continue;
+    }
+    for (const byte of utf8Encoder.encode(character)) {
+      encoded += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  if (encoded.length <= MAX_CONVEX_PREVIEW_KEY_LENGTH) return encoded;
+  let hashA = 2166136261;
+  let hashB = 2654435769;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    hashA = Math.imul(hashA ^ code, 16777619);
+    hashB = Math.imul(hashB ^ code, 16777619);
+  }
+  const suffix = `~${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+  return `${encoded.slice(0, MAX_CONVEX_PREVIEW_KEY_LENGTH - suffix.length)}${suffix}`;
 }
 function utf8Bytes(value) {
   return utf8Encoder.encode(value).byteLength;

package/dist/cli/index.mjs

@@ -3046,7 +3046,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -4694,10 +4694,30 @@ var DOCFLOW_NODE_IO_LIMITS = {
 };
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
+var MAX_CONVEX_PREVIEW_KEY_LENGTH = 1024;
 function ledgerSafeDocflowPreviewKey(key) {
-  if (!key.startsWith("$")) return key;
-  const stripped = key.replace(/^\$+/, "");
-  return stripped || "output";
+  const source = key.startsWith("$") ? key.replace(/^\$+/, "") || "output" : key || "output";
+  let encoded = "";
+  for (const character of source) {
+    const code = character.charCodeAt(0);
+    if (code >= 32 && code < 127) {
+      encoded += character;
+      continue;
+    }
+    for (const byte of utf8Encoder.encode(character)) {
+      encoded += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  if (encoded.length <= MAX_CONVEX_PREVIEW_KEY_LENGTH) return encoded;
+  let hashA = 2166136261;
+  let hashB = 2654435769;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    hashA = Math.imul(hashA ^ code, 16777619);
+    hashB = Math.imul(hashB ^ code, 16777619);
+  }
+  const suffix = `~${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+  return `${encoded.slice(0, MAX_CONVEX_PREVIEW_KEY_LENGTH - suffix.length)}${suffix}`;
 }
 function utf8Bytes(value) {
   return utf8Encoder.encode(value).byteLength;

package/dist/index.js

@@ -864,7 +864,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -2460,10 +2460,30 @@ var DOCFLOW_NODE_IO_LIMITS = {
 };
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
+var MAX_CONVEX_PREVIEW_KEY_LENGTH = 1024;
 function ledgerSafeDocflowPreviewKey(key) {
-  if (!key.startsWith("$")) return key;
-  const stripped = key.replace(/^\$+/, "");
-  return stripped || "output";
+  const source = key.startsWith("$") ? key.replace(/^\$+/, "") || "output" : key || "output";
+  let encoded = "";
+  for (const character of source) {
+    const code = character.charCodeAt(0);
+    if (code >= 32 && code < 127) {
+      encoded += character;
+      continue;
+    }
+    for (const byte of utf8Encoder.encode(character)) {
+      encoded += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  if (encoded.length <= MAX_CONVEX_PREVIEW_KEY_LENGTH) return encoded;
+  let hashA = 2166136261;
+  let hashB = 2654435769;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    hashA = Math.imul(hashA ^ code, 16777619);
+    hashB = Math.imul(hashB ^ code, 16777619);
+  }
+  const suffix = `~${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+  return `${encoded.slice(0, MAX_CONVEX_PREVIEW_KEY_LENGTH - suffix.length)}${suffix}`;
 }
 function utf8Bytes(value) {
   return utf8Encoder.encode(value).byteLength;

package/dist/index.mjs

@@ -768,7 +768,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -2364,10 +2364,30 @@ var DOCFLOW_NODE_IO_LIMITS = {
 };
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
+var MAX_CONVEX_PREVIEW_KEY_LENGTH = 1024;
 function ledgerSafeDocflowPreviewKey(key) {
-  if (!key.startsWith("$")) return key;
-  const stripped = key.replace(/^\$+/, "");
-  return stripped || "output";
+  const source = key.startsWith("$") ? key.replace(/^\$+/, "") || "output" : key || "output";
+  let encoded = "";
+  for (const character of source) {
+    const code = character.charCodeAt(0);
+    if (code >= 32 && code < 127) {
+      encoded += character;
+      continue;
+    }
+    for (const byte of utf8Encoder.encode(character)) {
+      encoded += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  if (encoded.length <= MAX_CONVEX_PREVIEW_KEY_LENGTH) return encoded;
+  let hashA = 2166136261;
+  let hashB = 2654435769;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    hashA = Math.imul(hashA ^ code, 16777619);
+    hashB = Math.imul(hashB ^ code, 16777619);
+  }
+  const suffix = `~${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+  return `${encoded.slice(0, MAX_CONVEX_PREVIEW_KEY_LENGTH - suffix.length)}${suffix}`;
 }
 function utf8Bytes(value) {
   return utf8Encoder.encode(value).byteLength;

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.197";
+    readonly version: "0.3.199";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.197";
+    readonly version: "0.3.199";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.197",
+  version: "0.3.199",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

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