deepline 0.1.252 → 0.1.254

package/dist/bundling-sources/shared_libs/play-runtime/ledger-safe-payload.ts

@@ -1,10 +1,14 @@
 import { createSecretRedactionContext } from './secret-redaction';
 import {
   assertRuntimeReceiptOutputWithinLimit,
-  TERMINAL_RUN_RESULT_MAX_BYTES,
+  jsonByteLengthUpTo,
+  LEDGER_TERMINAL_RESULT_MAX_BYTES,
 } from './output-size-limits';
 
-export const MAX_LEDGER_RESULT_PAYLOAD_BYTES = TERMINAL_RUN_RESULT_MAX_BYTES;
+// This is an inline Convex event limit, not the durable scheduler-terminal
+// envelope. A full terminal return is projected to an out-of-line reference
+// before it reaches here.
+export const MAX_LEDGER_RESULT_PAYLOAD_BYTES = LEDGER_TERMINAL_RESULT_MAX_BYTES;
 export const MAX_LEDGER_LOG_LINES_PER_EVENT = 500;
 export const MAX_LEDGER_LOG_LINE_LENGTH = 2_000;
 
@@ -17,8 +21,11 @@ export function redactLedgerString(value: unknown): string | null {
 
 export function sanitizeLedgerPayload(value: unknown): unknown {
   if (value === undefined) return undefined;
-  const serialized = JSON.stringify(value);
-  if (serialized && serialized.length > MAX_LEDGER_RESULT_PAYLOAD_BYTES) {
+  const measurement = jsonByteLengthUpTo(
+    value,
+    MAX_LEDGER_RESULT_PAYLOAD_BYTES,
+  );
+  if (measurement.exceeded) {
     throw new Error('run event result payload is too large');
   }
   return ledgerIngressRedactor.redact(value);
@@ -26,11 +33,19 @@ export function sanitizeLedgerPayload(value: unknown): unknown {
 
 /** Secret-redact a receipt payload without coupling its 10 MiB cell limit to the ledger. */
 export function sanitizeRuntimeReceiptPayload(value: unknown): unknown {
+  // Reject an obviously oversized source before doing redaction work, then
+  // validate the exact value that will be persisted. Redaction normally shrinks
+  // credential-shaped values but can expand short matched strings.
   assertRuntimeReceiptOutputWithinLimit({
     output: value,
     path: 'runtime receipt output',
   });
-  return ledgerIngressRedactor.redact(value);
+  const redacted = ledgerIngressRedactor.redact(value);
+  assertRuntimeReceiptOutputWithinLimit({
+    output: redacted,
+    path: 'runtime receipt output after secret redaction',
+  });
+  return redacted;
 }
 
 export function sanitizeLedgerLogLines(value: unknown): string[] {

package/dist/bundling-sources/shared_libs/play-runtime/output-size-limits.ts

@@ -1,6 +1,9 @@
-const encoder = typeof TextEncoder === 'undefined' ? null : new TextEncoder();
-
-export const TERMINAL_RUN_RESULT_MAX_BYTES = 2_500_000;
+/**
+ * The durable terminal envelope carries the complete 5 MiB authored return
+ * plus bounded scheduler-owned metadata (progress, warnings, and a log tail).
+ * It must not make a return that passed the customer contract fail later.
+ */
+export const TERMINAL_RUN_RESULT_MAX_BYTES = 6 * 1024 * 1024;
 /**
  * Convex hard-caps a single document at 1 MiB and rejects nesting deeper than
  * 16 levels. A run-ledger `run.completed` / `run.failed` event embeds its
@@ -23,40 +26,191 @@ export const LEDGER_TERMINAL_RESULT_MAX_DEPTH = 10;
 export const CONVEX_LEDGER_ARRAY_MAX_ITEMS = 8_192;
 export const CONVEX_LEDGER_OBJECT_MAX_FIELDS = 1_024;
 export const CONVEX_LEDGER_FIELD_NAME_MAX_LENGTH = 1_024;
-export const CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
-export const CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
+/** Customer-visible values and complete authored returns share one 5 MiB cap. */
+export const CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 5 * 1024 * 1024;
+export const CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 5 * 1024 * 1024;
 /** Inline Postgres receipt contract: one serialized output is at most 10 MiB. */
 export const RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;
 /** One completion request may contain multiple receipts up to 32 MiB total. */
 export const RUNTIME_RECEIPT_COMPLETION_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * The Fly receipt gateway accepts one runner-terminal control request up to
+ * this size. This is a transport ceiling, not a customer-output contract:
+ * settled customer returns remain capped at 5 MiB and the 6 MiB durable
+ * terminal envelope; a suspended checkpoint is retained separately because it
+ * is required to resume execution.
+ */
+export const RUNNER_TERMINAL_PUSH_MAX_BODY_BYTES = 16 * 1024 * 1024;
+/**
+ * The terminal `result` line is the crash-recovery record in Daytona stdout.
+ * Once that line is written, retries may still emit runner-owned diagnostics.
+ * Keep their aggregate UTF-8 footprint below this allowance so a gateway-size
+ * suspended checkpoint remains inside the crash pusher's bounded tail read.
+ */
+export const RUNNER_POST_TERMINAL_DIAGNOSTIC_MAX_BYTES = 64 * 1024;
 
 export class OutputTooLargeError extends Error {
   readonly code = 'OUTPUT_TOO_LARGE';
   readonly path: string;
   readonly bytes: number;
   readonly limitBytes: number;
+  readonly measuredExactly: boolean;
 
   constructor(input: {
     path: string;
     bytes: number;
     limitBytes: number;
     advice: string;
+    measuredExactly?: boolean;
   }) {
+    const sizeDescription = input.measuredExactly === false ? 'at least ' : '';
     super(
-      `OutputTooLarge: ${input.path} is ${formatBytes(input.bytes)}, above the ${formatBytes(input.limitBytes)} limit. ` +
+      `OUTPUT_TOO_LARGE: ${input.path} is ${sizeDescription}${formatBytes(input.bytes)}, above the ${formatBytes(input.limitBytes)} limit. ` +
         input.advice,
     );
     this.name = 'OutputTooLargeError';
     this.path = input.path;
     this.bytes = input.bytes;
     this.limitBytes = input.limitBytes;
+    this.measuredExactly = input.measuredExactly !== false;
   }
 }
 
 export function jsonByteLength(value: unknown): number {
   const serialized = JSON.stringify(value);
   if (serialized === undefined) return 0;
-  return encoder?.encode(serialized).byteLength ?? serialized.length;
+  return utf8ByteLength(serialized);
+}
+
+type BoundedJsonByteLength = {
+  bytes: number;
+  exceeded: boolean;
+  exact: boolean;
+};
+
+const JSON_SIZE_LIMIT_REACHED = Symbol('JSON_SIZE_LIMIT_REACHED');
+
+function utf8ByteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 3;
+      }
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+function jsonStringByteLength(value: string): number {
+  let bytes = 2;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 0x22 || code === 0x5c) {
+      bytes += 2;
+    } else if (code <= 0x1f) {
+      bytes +=
+        code === 0x08 ||
+        code === 0x09 ||
+        code === 0x0a ||
+        code === 0x0c ||
+        code === 0x0d
+          ? 2
+          : 6;
+    } else if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+/**
+ * Measure JSON only up to a caller-owned ceiling. The replacer accounts for a
+ * lower bound before JSON.stringify builds its result and aborts as soon as
+ * that bound crosses the limit. Oversized strings are scanned, never copied.
+ */
+export function jsonByteLengthUpTo(
+  value: unknown,
+  limitBytes: number,
+): BoundedJsonByteLength {
+  let observedBytes = 0;
+  const add = (bytes: number) => {
+    observedBytes += bytes;
+    if (observedBytes > limitBytes) throw JSON_SIZE_LIMIT_REACHED;
+  };
+
+  try {
+    const serialized = JSON.stringify(
+      value,
+      function (this: unknown, key, entry: unknown) {
+        const arrayParent = Array.isArray(this);
+        const omittedObjectEntry =
+          !arrayParent &&
+          (entry === undefined ||
+            typeof entry === 'function' ||
+            typeof entry === 'symbol');
+        if (key && !arrayParent && !omittedObjectEntry) {
+          add(jsonStringByteLength(key) + 1);
+        }
+        if (typeof entry === 'string') {
+          add(jsonStringByteLength(entry));
+        } else if (typeof entry === 'number') {
+          add(Number.isFinite(entry) ? String(entry).length : 4);
+        } else if (typeof entry === 'boolean') {
+          add(entry ? 4 : 5);
+        } else if (entry === null) {
+          add(4);
+        } else if (
+          arrayParent &&
+          (entry === undefined ||
+            typeof entry === 'function' ||
+            typeof entry === 'symbol')
+        ) {
+          add(4);
+        } else if (entry && typeof entry === 'object') {
+          // At least one opening delimiter. This makes deeply repeated empty
+          // containers advance the bound even before punctuation is counted.
+          add(1);
+        }
+        return entry;
+      },
+    );
+    if (serialized === undefined) {
+      return { bytes: 0, exceeded: false, exact: true };
+    }
+    const bytes = utf8ByteLength(serialized);
+    return { bytes, exceeded: bytes > limitBytes, exact: true };
+  } catch (error) {
+    if (error === JSON_SIZE_LIMIT_REACHED) {
+      return { bytes: observedBytes, exceeded: true, exact: false };
+    }
+    throw error;
+  }
 }
 
 function formatBytes(bytes: number): string {
@@ -75,9 +229,9 @@ function assertJsonSized(input: {
   limitBytes: number;
   advice: string;
 }): number {
-  let bytes: number;
+  let measurement: BoundedJsonByteLength;
   try {
-    bytes = jsonByteLength(input.value);
+    measurement = jsonByteLengthUpTo(input.value, input.limitBytes);
   } catch (error) {
     throw new Error(
       `${input.path} cannot be serialized as JSON: ${
@@ -85,22 +239,23 @@ function assertJsonSized(input: {
       }`,
     );
   }
-  if (bytes > input.limitBytes) {
+  if (measurement.exceeded) {
     throw new OutputTooLargeError({
       path: input.path,
-      bytes,
+      bytes: measurement.bytes,
       limitBytes: input.limitBytes,
       advice: input.advice,
+      measuredExactly: measurement.exact,
     });
   }
-  return bytes;
+  return measurement.bytes;
 }
 
 export function valueWithinJsonByteLimit(value: unknown, limitBytes: number) {
   if (value === undefined || value === null) {
     return value;
   }
-  return jsonByteLength(value) > limitBytes ? undefined : value;
+  return jsonByteLengthUpTo(value, limitBytes).exceeded ? undefined : value;
 }
 
 /** Shared terminal-result contract for every scheduler backend. */
@@ -108,6 +263,18 @@ export function persistableTerminalRunResult(value: unknown): unknown {
   return valueWithinJsonByteLimit(value, TERMINAL_RUN_RESULT_MAX_BYTES);
 }
 
+/** A completed run must never commit without its complete terminal value. */
+export function assertTerminalRunResultWithinLimit(value: unknown): unknown {
+  assertJsonSized({
+    value,
+    path: 'terminal run result',
+    limitBytes: TERMINAL_RUN_RESULT_MAX_BYTES,
+    advice:
+      'The complete terminal result cannot be persisted. Keep authored output within its documented limits and keep transport metadata bounded.',
+  });
+  return value;
+}
+
 /**
  * Replay-only keys a terminal `PlayRunnerResult` carries for the scheduler
  * (Postgres) data plane. These are NEVER read back from the Convex run ledger:
@@ -129,10 +296,26 @@ export type LedgerTerminalResultRef = {
   /** Column on the scheduler `work_runs` row that holds the full result. */
   key: 'terminal_result_json';
   /** Serialized byte size of the result that was elided from the ledger. */
-  bytes: number;
+  bytes?: number;
   reason: LedgerTerminalResultRefReason;
+  /** The live Convex projection was intentionally replaced, not lost. */
+  projection?: 'out_of_line';
+  /** New refs point only at a value that was actually persisted in full. */
+  content?: 'full';
+  /** Bounded customer-safe explanation; contains no payload paths or keys. */
+  warning?: string;
+  /**
+   * Compact, Convex-safe run-list projection captured while the terminal
+   * result is already in memory. List/live polling reads this instead of
+   * fetching the complete scheduler result.
+   */
+  preview?: BoundedRunListOutputPreview;
 };
 
+export const LEDGER_TERMINAL_RESULT_STORED_WARNING =
+  'The terminal result is stored outside the live run projection because it exceeded a bounded storage limit. The run status and persisted row data are unaffected.';
+export const LEDGER_TERMINAL_RESULT_OMITTED_WARNING =
+  'The terminal result was omitted from the live run projection because it exceeded a bounded storage limit. The run status and persisted row data are unaffected.';
 export type LedgerTerminalResultRefReason =
   | 'terminal_result_exceeds_ledger_limit'
   | 'terminal_result_exceeds_ledger_depth'
@@ -159,6 +342,7 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 
 function isConvexFieldName(value: string): boolean {
   if (
+    value.length === 0 ||
     value.length > CONVEX_LEDGER_FIELD_NAME_MAX_LENGTH ||
     value.startsWith('$')
   ) {
@@ -171,6 +355,201 @@ function isConvexFieldName(value: string): boolean {
   return true;
 }
 
+function isSafeRunListPreviewFieldName(value: string): boolean {
+  return (
+    isConvexFieldName(value) &&
+    value !== '__proto__' &&
+    value !== 'constructor' &&
+    value !== 'prototype'
+  );
+}
+
+/**
+ * The dashboard's historical run list is a polling surface. Keep its output
+ * projection tiny even when the authored return is the full 5 MiB allowed by
+ * the customer contract. These limits deliberately mirror the API response
+ * budget, but live here so the durable Convex summary can be written without
+ * importing a server-only route helper.
+ */
+export const RUN_LIST_OUTPUT_PREVIEW_LIMITS = {
+  maxFields: 40,
+  // The list endpoint returns multiple historical runs in one polling page.
+  // Reserve enough room for run state and legacy rows by keeping each preview
+  // at 4 KiB; the complete authored result remains separately readable up to
+  // the 5 MiB customer-output ceiling.
+  maxBytes: 4_000,
+  maxDepth: 4,
+  maxStringLength: 300,
+  maxArrayItems: 5,
+  maxObjectFields: 40,
+} as const;
+
+export type BoundedRunListOutputPreview = {
+  output: Record<string, unknown>;
+  truncated: boolean;
+};
+
+function compactRunListPreviewString(value: string): {
+  value: string;
+  truncated: boolean;
+} {
+  const compact = value.replace(/\s+/g, ' ').trim();
+  if (compact.length <= RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxStringLength) {
+    return { value: compact, truncated: compact !== value };
+  }
+  return {
+    value: `${compact.slice(0, RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxStringLength)}...`,
+    truncated: true,
+  };
+}
+
+/**
+ * Produce a small projection that satisfies Convex's field-name/depth rules.
+ * Recursion stops at a small, caller-owned depth so an unsafe result can never
+ * make its own preview projection exhaust the stack.
+ */
+function compactRunListPreviewValue(
+  value: unknown,
+  depth: number,
+): { value: unknown; truncated: boolean } {
+  if (
+    value == null ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return { value, truncated: false };
+  }
+  if (typeof value === 'string') {
+    return compactRunListPreviewString(value);
+  }
+  if (depth >= RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxDepth) {
+    return {
+      value: Array.isArray(value) ? '[Array]' : '[Object]',
+      truncated: true,
+    };
+  }
+  if (Array.isArray(value)) {
+    let truncated = value.length > RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxArrayItems;
+    const items: unknown[] = [];
+    for (const item of value.slice(
+      0,
+      RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxArrayItems,
+    )) {
+      const compacted = compactRunListPreviewValue(item, depth + 1);
+      truncated ||= compacted.truncated;
+      items.push(compacted.value);
+    }
+    return { value: items, truncated };
+  }
+  if (!isPlainObject(value)) {
+    return { value: String(value), truncated: true };
+  }
+
+  const output: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
+  let truncated = false;
+  const entries = Object.entries(value);
+  for (const [key, child] of entries.slice(
+    0,
+    RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxObjectFields,
+  )) {
+    if (!isSafeRunListPreviewFieldName(key)) {
+      truncated = true;
+      continue;
+    }
+    const compacted = compactRunListPreviewValue(child, depth + 1);
+    truncated ||= compacted.truncated;
+    output[key] = compacted.value;
+  }
+  return {
+    value: output,
+    truncated:
+      truncated ||
+      entries.length > RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxObjectFields,
+  };
+}
+
+function runListPreviewFieldBytes(
+  key: string,
+  value: unknown,
+  hasPreviousField: boolean,
+): number {
+  try {
+    return utf8ByteLength(
+      `${hasPreviousField ? ',' : ''}${JSON.stringify(key)}:${JSON.stringify(value)}`,
+    );
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+/**
+ * Build the durable run-list preview while the terminal result is already in
+ * memory. It never reads a full result from Postgres, and it does not copy
+ * invalid Convex field names into the summary projection.
+ */
+export function buildBoundedRunListOutputPreview(
+  value: Record<string, unknown>,
+): BoundedRunListOutputPreview {
+  const output: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
+  let outputBytes = 2;
+  let outputFields = 0;
+  let truncated = false;
+  for (const [key, child] of Object.entries(value)) {
+    if (outputFields >= RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxFields) {
+      truncated = true;
+      break;
+    }
+    if (!isSafeRunListPreviewFieldName(key)) {
+      truncated = true;
+      continue;
+    }
+    const compacted = compactRunListPreviewValue(child, 0);
+    truncated ||= compacted.truncated;
+    let previewValue = compacted.value;
+    let fieldBytes = runListPreviewFieldBytes(
+      key,
+      previewValue,
+      outputFields > 0,
+    );
+    if (outputBytes + fieldBytes > RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxBytes) {
+      truncated = true;
+      previewValue = '[Preview omitted; open the run for complete output]';
+      fieldBytes = runListPreviewFieldBytes(
+        key,
+        previewValue,
+        outputFields > 0,
+      );
+      if (outputBytes + fieldBytes > RUN_LIST_OUTPUT_PREVIEW_LIMITS.maxBytes) {
+        break;
+      }
+    }
+    output[key] = previewValue;
+    outputBytes += fieldBytes;
+    outputFields += 1;
+  }
+  return { output, truncated };
+}
+
+/**
+ * Read the preview that is safe to carry in Convex run summaries. Older refs
+ * did not persist a preview; mark those as truncated so callers can link to
+ * the explicit full-run read without falling back to an unbounded hydration.
+ */
+export function runListOutputPreviewForLedger(
+  value: unknown,
+): BoundedRunListOutputPreview | null {
+  if (isLedgerTerminalResultRef(value)) {
+    return value.preview ?? { output: {}, truncated: true };
+  }
+  return isPlainObject(value) ? buildBoundedRunListOutputPreview(value) : null;
+}
+
 /**
  * Validate the part of Convex's value contract that can permanently poison a
  * durable run-ledger append. The walk is iterative and stops at the depth
@@ -228,9 +607,12 @@ export function inspectConvexLedgerPayload(
   }
 
   try {
-    const bytes = jsonByteLength(value);
-    return bytes > LEDGER_TERMINAL_RESULT_MAX_BYTES
-      ? { reason: 'size_limit', bytes }
+    const measurement = jsonByteLengthUpTo(
+      value,
+      LEDGER_TERMINAL_RESULT_MAX_BYTES,
+    );
+    return measurement.exceeded
+      ? { reason: 'size_limit', bytes: measurement.bytes }
       : null;
   } catch {
     return { reason: 'not_json_serializable' };
@@ -281,24 +663,52 @@ function refReasonForIssue(
   }
 }
 
+function ledgerTerminalResultRef(
+  reason: LedgerTerminalResultRefReason,
+  options: {
+    content?: 'full';
+    bytes?: number;
+    preview?: BoundedRunListOutputPreview;
+  } = {},
+): LedgerTerminalResultRef {
+  return {
+    __kind: 'deepline.ledger_terminal_result_ref.v1',
+    store: 'scheduler_postgres',
+    key: 'terminal_result_json',
+    ...(options.bytes !== undefined ? { bytes: options.bytes } : {}),
+    reason,
+    projection: 'out_of_line',
+    ...(options.content ? { content: options.content } : {}),
+    ...(options.preview ? { preview: options.preview } : {}),
+    warning: options.content
+      ? LEDGER_TERMINAL_RESULT_STORED_WARNING
+      : LEDGER_TERMINAL_RESULT_OMITTED_WARNING,
+  };
+}
+
 export function ledgerTerminalResultRefForValue(
   value: unknown,
   reason: LedgerTerminalResultRefReason,
+  options: { content?: 'full' } = {},
 ): LedgerTerminalResultRef {
-  let bytes = 0;
+  let bytes: number | undefined;
   try {
-    bytes = jsonByteLength(value);
+    bytes = jsonByteLengthUpTo(value, LEDGER_TERMINAL_RESULT_MAX_BYTES).bytes;
   } catch {
     // The bounded reason is the useful diagnostic. Never serialize the
     // customer payload again merely to populate reference metadata.
   }
-  return {
-    __kind: 'deepline.ledger_terminal_result_ref.v1',
-    store: 'scheduler_postgres',
-    key: 'terminal_result_json',
-    bytes,
-    reason,
-  };
+  let preview: BoundedRunListOutputPreview | undefined;
+  if (options.content && isPlainObject(value)) {
+    try {
+      preview = buildBoundedRunListOutputPreview(value);
+    } catch {
+      // The terminal reference is the durable fallback. A hostile/non-JSON
+      // value must not turn optional list-preview derivation into a terminal
+      // persistence failure.
+    }
+  }
+  return ledgerTerminalResultRef(reason, { ...options, bytes, preview });
 }
 
 /** Optional derived summaries must never block the terminal lifecycle event. */
@@ -317,10 +727,14 @@ export function ledgerSummaryForLedger(value: unknown): unknown {
  *    the durable scheduler copy, so the ledger event stays small and the
  *    Convex append cannot wedge on an oversized/over-nested document.
  *
- * Any result accepted by the existing terminal persistence contract remains
- * durable in scheduler Postgres; this only governs what the ledger embeds.
+ * Results accepted by the terminal persistence contract remain durable in
+ * scheduler Postgres. Callers may set `content: "full"` only after that write
+ * succeeds; this function governs only what the ledger embeds.
  */
-export function terminalRunResultForLedger(value: unknown): unknown {
+export function terminalRunResultForLedger(
+  value: unknown,
+  options: { content?: 'full' } = {},
+): unknown {
   if (value === undefined || value === null) {
     return value;
   }
@@ -333,6 +747,7 @@ export function terminalRunResultForLedger(value: unknown): unknown {
   return ledgerTerminalResultRefForValue(
     candidate,
     refReasonForIssue(issue.reason),
+    options,
   );
 }
 
@@ -372,6 +787,24 @@ export function assertCustomerOutputObjectWithinLimit(input: {
   });
 }
 
+/**
+ * A play return is bounded by one serialized byte budget, never by row count.
+ * Ordinary arrays remain complete when the run succeeds.
+ */
+export function assertCustomerPlayReturnWithinLimit(input: {
+  value: Record<string, unknown>;
+  path?: string;
+  totalLimitBytes?: number;
+}): number {
+  return assertJsonSized({
+    value: input.value,
+    path: input.path ?? 'play return',
+    limitBytes: input.totalLimitBytes ?? CUSTOMER_OUTPUT_TOTAL_MAX_BYTES,
+    advice:
+      'Filter rows, select only the fields you need, or return a summary before retrying.',
+  });
+}
+
 export function assertRuntimeReceiptOutputWithinLimit(input: {
   output: unknown;
   path: string;