deepline 0.3.196 → 0.3.198

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.196',
+  version: '0.3.198',
   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/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/scheduler-backends/postgres.ts

@@ -62,6 +62,7 @@ import {
   type RuntimeReceiptValueReference,
 } from '../runtime-receipt-value';
 import { PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS } from '../lease-policy';
+import { RUNTIME_CAPACITY_POLICY } from '../runtime-capacity-policy';
 import { RUNTIME_RELIABILITY_POLICY } from '../runtime-reliability-policy';
 import { COMPLETED_RECEIPT_CACHE_INSERT_LEASE_ID } from '../durable-receipt-execution';
 import {
@@ -159,6 +160,7 @@ import { requireRuntimeAuthorityDescriptor } from '../execution-capabilities';
 import { stringifyPostgresJson } from '../postgres-json';
 import {
   buildPlayLaunchIdentity,
+  PLAY_LAUNCH_ENVELOPE_FIELD_ROLES,
   withPlayLaunchIdentityDigest,
 } from '../launch-identity';
 import { PlayRunLaunchConflictError } from '../play-runs/admission/contracts';
@@ -173,7 +175,10 @@ import {
   recordSchedulerLaunchRead,
   type SchedulerLaunchReadCaller,
 } from './scheduler-launch-read-observability';
-import { emitPlayTelemetry } from '../runtime-telemetry';
+import {
+  emitPlayRunLaunchConflictTelemetry,
+  emitPlayTelemetry,
+} from '../runtime-telemetry';
 import { buildAbsurdPlayRunTask } from './absurd-play-run-task';
 import {
   buildAbsurdCronFireTask,
@@ -4509,6 +4514,38 @@ export async function submitPostgresAbsurdPlayRun(
   };
 }
 
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Reasons this build cannot prove a stored launch has the incoming named
+ * intent. Empty only when the stored envelope is readable, contains no field
+ * this build does not know (a newer writer may have added identity), and
+ * every named intent field matches.
+ */
+function launchIntentRematchBlockers(
+  existingLaunchJson: unknown,
+  incomingLaunch: PlaySchedulerSubmitInput,
+): string[] {
+  if (!isJsonObject(existingLaunchJson)) return ['launch'];
+  const unknownFields = Object.keys(existingLaunchJson).filter(
+    (field) =>
+      !Object.prototype.hasOwnProperty.call(
+        PLAY_LAUNCH_ENVELOPE_FIELD_ROLES,
+        field,
+      ),
+  );
+  if (unknownFields.length > 0) return unknownFields.sort();
+  return launchIdentityConflictFields(existingLaunchJson, incomingLaunch);
+}
+
+function launchIdentityDigestOf(launchJson: unknown): string | null {
+  if (!isJsonObject(launchJson)) return null;
+  const digest = launchJson.launchIdentityDigest;
+  return typeof digest === 'string' && digest.trim() ? digest.trim() : null;
+}
+
 function launchIdentityConflictFields(
   existingLaunchJson: unknown,
   incomingLaunch: PlaySchedulerSubmitInput,
@@ -4559,12 +4596,18 @@ async function submitPostgresSchedulerRunTransaction(
     options: unknown;
     recoverExistingTask?: boolean;
   },
+  /**
+   * Set only on the single re-admission after the current build proved the
+   * existing Run has the same named launch intent (see the conflict branch).
+   */
+  existingLaunchIntentMatches = false,
 ): Promise<{
   absurdTaskId: string | null;
   runCreated: boolean;
   taskCreated: boolean;
   taskRecoveryRequired: boolean;
 }> {
+  const requestedInput = input;
   // Persist the ABI with every new launch. Null is reserved for genuinely
   // historic rows already in storage, where readers interpret it as legacy.
   input = {
@@ -4591,6 +4634,9 @@ async function submitPostgresSchedulerRunTransaction(
   // fields are removed so they can never change the durable launch identity.
   input = withPlayLaunchIdentityDigest(durableInput);
   const existingOnlySql = requestedExistingOnly === true ? 'true' : 'false';
+  const existingLaunchIntentMatchesSql = existingLaunchIntentMatches
+    ? 'true'
+    : 'false';
   const releaseId = input.absurdReleaseId?.trim() || null;
   const legacyPreviewRelease =
     releaseId === 'dev' || releaseId?.startsWith('dev-') === true;
@@ -4717,9 +4763,12 @@ async function submitPostgresSchedulerRunTransaction(
         FOR UPDATE
       ), existing_run AS (
         SELECT
-          ${quoteIdent(schemaName(options))}.runtime_launch_admission_matches(
-            coalesce(runs.admission_json, runs.launch_json),
-            $8::jsonb
+          (
+            ${existingLaunchIntentMatchesSql}
+            OR ${quoteIdent(schemaName(options))}.runtime_launch_admission_matches(
+              coalesce(runs.admission_json, runs.launch_json),
+              $8::jsonb
+            )
           ) AS matches_launch,
           coalesce(runs.admission_json, runs.launch_json) AS launch_json,
           runs.absurd_task_id,
@@ -4985,13 +5034,42 @@ async function submitPostgresSchedulerRunTransaction(
     );
   }
   if (row?.accepted === false && row.existing_run && !row.matching_existing) {
-    throw new PlayRunLaunchConflictError(input.runId, {
-      conflictReason: 'launch_identity_mismatch',
-      conflictingFields: launchIdentityConflictFields(
-        row.existing_launch_json,
-        input,
-      ),
+    const rematchBlockers = launchIntentRematchBlockers(
+      row.existing_launch_json,
+      input,
+    );
+    if (existingLaunchIntentMatches || rematchBlockers.length > 0) {
+      throw new PlayRunLaunchConflictError(input.runId, {
+        conflictReason: 'launch_identity_mismatch',
+        conflictingFields: rematchBlockers,
+      });
+    }
+    // The stored envelope was written by another build (no digest, or a
+    // digest this build cannot reproduce), but every named intent field
+    // matches. Re-admit once as a match so the Run's normal matched path,
+    // including task recovery, runs instead of failing an at-least-once retry.
+    emitPlayTelemetry({
+      level: 'warn',
+      event: 'play.run.admission_intent_rematch',
+      tag: '[play.run.admission_intent_rematch]',
+      fields: {
+        runId: input.runId,
+        orgId: input.orgId,
+        playName: input.playName,
+        triggerSource: input.triggerSource ?? null,
+        existingLaunchIdentityDigest: launchIdentityDigestOf(
+          row.existing_launch_json,
+        ),
+        launchIdentityDigest: input.launchIdentityDigest ?? null,
+      },
     });
+    return submitPostgresSchedulerRunTransaction(
+      client,
+      requestedInput,
+      options,
+      absurdTask,
+      true,
+    );
   }
   if (row?.accepted === false && !row?.existing_run && requestedExistingOnly) {
     throw new Error(
@@ -5683,10 +5761,11 @@ export type FirePostgresSchedulerCronScheduleInput = {
  * cursor and is a harmless `superseded` no-op.
  *
  * A re-fire of the same occurrence whose deterministic Run already exists is
- * an idempotent re-fire, not a no-op. The cursor advances when the existing
- * launch identity matches, even if this statement did not create the Run.
- * A genuine identity mismatch is returned as `stalled` so it cannot silently
- * freeze the schedule behind an indistinguishable replay.
+ * an idempotent re-fire, not a no-op. The cursor advances over any existing
+ * Run, even when a mixed-version or competing launch makes the named identity
+ * comparator disagree. The persisted Run is authoritative for this
+ * deterministic occurrence; a conflict is emitted for owner-visible
+ * diagnosis, never converted into a permanent blocked cursor.
  */
 export async function firePostgresSchedulerCronSchedule(
   client: PostgresSchedulerQueryClient,
@@ -5698,6 +5777,7 @@ export async function firePostgresSchedulerCronSchedule(
       runId: string;
       successorDueAtMs: number;
       reused: boolean;
+      conflictingFields?: string[];
     }
   | { status: 'superseded' }
   | { status: 'stalled'; runId: string; reason: string }
@@ -5772,6 +5852,7 @@ export async function firePostgresSchedulerCronSchedule(
     schedule_current: boolean;
     existing_run: boolean;
     matching_existing: boolean;
+    existing_launch_json: unknown | null;
     release_accepting: boolean;
   }>(
     `
@@ -5797,6 +5878,7 @@ export async function firePostgresSchedulerCronSchedule(
         FOR UPDATE
       ), existing_run AS MATERIALIZED (
         SELECT runs.run_id,
+               coalesce(runs.admission_json, runs.launch_json) AS launch_json,
                ${quoteIdent(schemaName(options))}.runtime_launch_admission_matches(
                  coalesce(runs.admission_json, runs.launch_json),
                  $6::jsonb
@@ -5864,7 +5946,6 @@ export async function firePostgresSchedulerCronSchedule(
            OR (
              occurrence.schedule_current
              AND occurrence.existing_run
-             AND occurrence.matching_existing
            )
       ), successor_task_request AS (
         SELECT $11::text AS queue_name,
@@ -5953,6 +6034,7 @@ export async function firePostgresSchedulerCronSchedule(
              (SELECT schedule_current FROM occurrence) AS schedule_current,
              (SELECT existing_run FROM occurrence) AS existing_run,
              (SELECT matching_existing FROM occurrence) AS matching_existing,
+             (SELECT launch_json FROM existing_run) AS existing_launch_json,
              coalesce(
                (SELECT accepting
                   FROM ${tableName('runtime_release_admission', options)}
@@ -5986,24 +6068,53 @@ export async function firePostgresSchedulerCronSchedule(
     );
   }
   if (fired.advanced === true) {
+    const conflictingFields =
+      fired.existing_run === true && fired.matching_existing !== true
+        ? launchIntentRematchBlockers(fired.existing_launch_json, launch)
+        : [];
+    if (conflictingFields.length === 0 && fired.existing_run === true) {
+      emitPlayTelemetry({
+        level: 'warn',
+        event: 'play.run.admission_intent_rematch',
+        tag: '[play.run.admission_intent_rematch]',
+        fields: {
+          runId: launch.runId,
+          orgId: launch.orgId,
+          playName: launch.playName,
+          triggerSource: 'cron',
+          scheduleId: schedule.scheduleId,
+          existingLaunchIdentityDigest: launchIdentityDigestOf(
+            fired.existing_launch_json,
+          ),
+          launchIdentityDigest: launch.launchIdentityDigest ?? null,
+        },
+      });
+    } else if (conflictingFields.length > 0) {
+      const conflict = new Error(
+        `Cron occurrence "${launch.runId}" already exists with a different launch identity: ${conflictingFields.join(', ')}`,
+      );
+      emitPlayRunLaunchConflictTelemetry({
+        orgId: launch.orgId,
+        runId: launch.runId,
+        playName: launch.playName,
+        triggerSource: 'cron',
+        workflowFamilyKey: launch.workflowFamilyKey,
+        revisionId: launch.revisionId,
+        artifactHash: launch.artifactHash,
+        graphHash: launch.graphHash,
+        inputSha256: launch.inputSha256,
+        launchIdentityDigest: launch.launchIdentityDigest,
+        conflictReason: 'launch_identity_mismatch',
+        conflictingFields,
+        error: conflict,
+      });
+    }
     return {
       status: 'admitted',
       runId: launch.runId,
       successorDueAtMs,
       reused: fired.run_created !== true,
-    };
-  }
-  if (
-    fired.schedule_current === true &&
-    fired.existing_run === true &&
-    fired.matching_existing !== true
-  ) {
-    return {
-      status: 'stalled',
-      runId: launch.runId,
-      reason:
-        `Cron schedule "${schedule.scheduleId}" generation ${schedule.generation} cannot advance past ` +
-        `occurrence ${schedule.dueAtMs}: Run "${launch.runId}" already exists with a different launch identity.`,
+      ...(conflictingFields.length > 0 ? { conflictingFields } : {}),
     };
   }
   return { status: 'superseded' };
@@ -12102,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 };
   },
@@ -12238,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
@@ -12250,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 (
@@ -12309,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],
     );
   }
@@ -16711,7 +16839,12 @@ export async function listPostgresSchedulerOutboxMaterializationPlans(
  */
 export type RunLedgerOutboxTokenAuthority = 'local_mint' | 'gateway';
 
-const POSTGRES_SCHEDULER_CANCELLATION_OUTBOX_LEASE_SECONDS = 15;
+const POSTGRES_SCHEDULER_CANCELLATION_OUTBOX_LEASE_SECONDS =
+  // The direct projection can run for the full app-runtime request deadline.
+  // Keep another 30 seconds for dispatch setup and acknowledgement so a
+  // background projector cannot reclaim an append that is still in flight.
+  Math.ceil(RUNTIME_CAPACITY_POLICY.receiptGateway.requestTimeoutMs / 1_000) +
+  30;
 
 /**
  * Stable lease identity shared by the atomic scheduler cancellation and the

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.196",
+  version: "0.3.198",
   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.196",
+  version: "0.3.198",
   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.196",
+  version: "0.3.198",
   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.196",
+  version: "0.3.198",
   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.196";
+    readonly version: "0.3.198";
     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.196";
+    readonly version: "0.3.198";
     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.196",
+  version: "0.3.198",
   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.196",
+  version: "0.3.198",
   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.196",
+  "version": "0.3.198",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",