deepline 0.3.128 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-value.ts

@@ -0,0 +1,184 @@
+/**
+ * An immutable body stored outside a runtime receipt row.
+ *
+ * Receipt rows remain the authority for whether an outcome exists. A reference
+ * carries bytes only; it is never a cache miss, execution lease, or permission
+ * to run a provider operation again.
+ */
+/**
+ * R2 owns a referenced receipt's complete result body. These are the small,
+ * selected fields that may travel with its manifest for routing, presentation,
+ * and admission without redeeming that body.
+ */
+export const RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_BYTES = 16 * 1024;
+export const RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_KEYS = 32;
+const RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_DEPTH = 16;
+
+export type RuntimeReceiptValueInlineValue =
+  | string
+  | number
+  | boolean
+  | null
+  | RuntimeReceiptValueInlineValue[]
+  | { [key: string]: RuntimeReceiptValueInlineValue };
+
+export type RuntimeReceiptValueInlineFields = Record<
+  string,
+  RuntimeReceiptValueInlineValue
+>;
+
+export type RuntimeReceiptValueReference = {
+  storage: 'r2';
+  /**
+   * New manifests use the named JSON codec. The compatibility reader accepts
+   * the already-written legacy spelling without promoting a numeric protocol.
+   */
+  codec: 'json' | 'json-v1';
+  key: string;
+  digest: string;
+  byteLength: number;
+  /** SHA-256 binding for the authenticated organization, never its raw id. */
+  orgBinding: string;
+  /** SHA-256 binding for the receipt key that owns this value. */
+  receiptBinding: string;
+  /**
+   * Bounded selected fields beside an R2 body. Never a second full result.
+   * This field is additive so readers that predate it still use the reference.
+   */
+  inlineFields?: RuntimeReceiptValueInlineFields;
+};
+
+/**
+ * Canonicalize the small manifest payload before it crosses a receipt boundary.
+ * It is intentionally stricter than JSON.stringify: undefined values, Dates,
+ * non-finite numbers, and custom objects fail rather than changing meaning.
+ */
+export function normalizeRuntimeReceiptValueInlineFields(
+  value: unknown,
+): RuntimeReceiptValueInlineFields {
+  if (!isPlainRecord(value)) {
+    throw new Error('Runtime receipt inline fields must be a plain object.');
+  }
+  const keys = Object.keys(value);
+  if (keys.length > RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_KEYS) {
+    throw new Error(
+      `Runtime receipt inline fields exceed ${RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_KEYS} keys.`,
+    );
+  }
+  const copied = copyInlineValue(value, '$', new Set<object>(), 0);
+  if (!isPlainRecord(copied)) {
+    throw new Error('Runtime receipt inline fields must normalize to an object.');
+  }
+  const serialized = JSON.stringify(copied);
+  const bytes = new TextEncoder().encode(serialized).byteLength;
+  if (bytes > RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_BYTES) {
+    throw new Error(
+      `Runtime receipt inline fields exceed ${RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_BYTES} bytes.`,
+    );
+  }
+  return copied;
+}
+
+export function isRuntimeReceiptValueReference(
+  value: unknown,
+): value is RuntimeReceiptValueReference {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    candidate.storage === 'r2' &&
+    (candidate.codec === 'json' || candidate.codec === 'json-v1') &&
+    typeof candidate.key === 'string' &&
+    candidate.key.length > 0 &&
+    /^[a-f0-9]{64}$/i.test(String(candidate.digest ?? '')) &&
+    Number.isSafeInteger(candidate.byteLength) &&
+    Number(candidate.byteLength) >= 0 &&
+    /^[a-f0-9]{64}$/i.test(String(candidate.orgBinding ?? '')) &&
+    /^[a-f0-9]{64}$/i.test(String(candidate.receiptBinding ?? '')) &&
+    (candidate.inlineFields === undefined ||
+      isRuntimeReceiptValueInlineFields(candidate.inlineFields))
+  );
+}
+
+function isRuntimeReceiptValueInlineFields(
+  value: unknown,
+): value is RuntimeReceiptValueInlineFields {
+  try {
+    normalizeRuntimeReceiptValueInlineFields(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function copyInlineValue(
+  value: unknown,
+  path: string,
+  ancestors: Set<object>,
+  depth: number,
+): RuntimeReceiptValueInlineValue {
+  if (depth > RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_DEPTH) {
+    throw new Error(
+      `Runtime receipt inline field ${path} exceeds ${RUNTIME_RECEIPT_VALUE_INLINE_FIELDS_MAX_DEPTH} nested levels.`,
+    );
+  }
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return value;
+    throw new Error(`Runtime receipt inline field ${path} must be finite.`);
+  }
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) {
+      throw new Error(`Runtime receipt inline field ${path} cannot be cyclic.`);
+    }
+    ancestors.add(value);
+    try {
+      return value.map((entry, index) =>
+        copyInlineValue(entry, `${path}[${index}]`, ancestors, depth + 1),
+      );
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  if (isPlainRecord(value)) {
+    if (ancestors.has(value)) {
+      throw new Error(`Runtime receipt inline field ${path} cannot be cyclic.`);
+    }
+    ancestors.add(value);
+    try {
+      const copied: Record<string, RuntimeReceiptValueInlineValue> = {};
+      for (const [key, entry] of Object.entries(value)) {
+        copied[key] = copyInlineValue(
+          entry,
+          `${path}.${key}`,
+          ancestors,
+          depth + 1,
+        );
+      }
+      return copied;
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  throw new Error(
+    `Runtime receipt inline field ${path} must be JSON data, not ${
+      value === undefined ? 'undefined' : typeof value
+    }.`,
+  );
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export class RuntimeReceiptValueReadError extends Error {
+  constructor(
+    readonly code: 'missing' | 'corrupt' | 'unavailable' | 'scope_mismatch',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'RuntimeReceiptValueReadError';
+  }
+}