@xemahq/dsl 0.1.1

package/src/payload-codec/lib/codec.ts

@@ -0,0 +1,593 @@
+import type { Payload, PayloadCodec } from '@temporalio/common';
+
+import { type BlobRef, type BlobStore, sha256Hex } from './blob-store';
+import {
+  BlobStoreKind,
+  DEFAULT_CACHE_CAPACITY_BYTES,
+  DEFAULT_SPILL_THRESHOLD_BYTES,
+  SPILL_ENCODING_V1,
+  SPILL_ENVELOPE_VERSION,
+  SpillMetadataKey,
+} from './enums';
+import { PayloadCodecError, PayloadCodecErrorCode } from './errors';
+import { BytesLruCache } from './lru-cache';
+
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder('utf-8', { fatal: true });
+
+/**
+ * Spill envelope written as the Payload.data of a spilled payload. Mirrors
+ * the fields the frontend + debugger render; the {@link SpillPayloadCodec}
+ * serializes this as JSON.
+ *
+ * `orgId` is part of the envelope — not just side-band metadata — because
+ * the underlying blob store is multi-tenant and the decoder needs the
+ * orgId to fetch the same row back without ambient context.
+ */
+interface SpillEnvelope {
+  readonly $xemaSpill: typeof SPILL_ENVELOPE_VERSION;
+  readonly store: BlobStoreKind;
+  readonly uri: string;
+  readonly sha256: string;
+  readonly orgId: string;
+  readonly sizeBytes: number;
+  readonly contentType: string;
+  readonly createdAt: string;
+}
+
+/**
+ * Lifecycle event fired by the codec for every payload it inspects.
+ * Consumers wire structured logging or metrics by passing an
+ * {@link CodecObserver} at construction time.
+ *
+ * `outcome` lets ops answer the question "is the spill threshold tuned
+ * correctly?" empirically — if the bulk of encodes are 'inline' the
+ * threshold is too high; if decodes consistently miss the cache the
+ * decode-cache capacity is too small.
+ */
+export type CodecLifecycleEvent =
+  | { readonly kind: 'encode'; readonly outcome: 'spilled' | 'inline' | 'already-spilled'; readonly sizeBytes: number; readonly orgId?: string }
+  | { readonly kind: 'decode'; readonly outcome: 'rehydrated' | 'cache-hit' | 'inline-passthrough'; readonly sizeBytes: number; readonly orgId?: string };
+
+/**
+ * Pluggable observer for codec lifecycle events. The codec calls this
+ * synchronously after each encode/decode; consumers MUST NOT throw from
+ * the observer (the codec catches and ignores observer exceptions to
+ * avoid corrupting Temporal payload flow). Use for logging, Prometheus,
+ * OpenTelemetry, etc.
+ */
+export type CodecObserver = (event: CodecLifecycleEvent) => void;
+
+export interface SpillPayloadCodecOptions {
+  /**
+   * Map of {@link BlobStoreKind} → backing {@link BlobStore}. The codec
+   * uses this as a registry, not a single store:
+   *
+   *   - **Encode** always writes to `stores[primaryStoreKind]`. There is
+   *     exactly one primary; it is the only store that gets new spills.
+   *   - **Decode** reads via `stores[envelope.store]`. Any envelope whose
+   *     store kind is not registered fails fast with `UNKNOWN_STORE_KIND`
+   *     — that signals a real config error, not a recoverable miss.
+   *
+   * The registry shape is what makes store migrations safe: keep the old
+   * store registered for read-back while the new one becomes primary,
+   * drain in-flight workflows, then drop the old store. Without this,
+   * flipping `WORKFLOW_PAYLOAD_CODEC_STORE` strands every running
+   * workflow whose history references the old store.
+   */
+  readonly stores: Partial<Record<BlobStoreKind, BlobStore>>;
+  /**
+   * Which registered store new spills go to. MUST be a key in `stores`
+   * — the constructor validates this. `WORKFLOW_PAYLOAD_CODEC_STORE` in
+   * the engine + worker maps directly to this field.
+   */
+  readonly primaryStoreKind: BlobStoreKind;
+  /**
+   * Resolves the tenant orgId for an encode call. The codec calls this
+   * once per spilled payload. Throwing or returning empty raises
+   * {@link PayloadCodecErrorCode.ORG_ID_REQUIRED} — there is no silent
+   * fallback. Decode does NOT consult this provider; it reads orgId from
+   * the envelope so historical payloads always rehydrate against the
+   * tenant they were written under.
+   */
+  readonly orgIdProvider: () => string | Promise<string>;
+  /**
+   * Threshold (bytes) at or above which payloads spill. Defaults to
+   * {@link DEFAULT_SPILL_THRESHOLD_BYTES}.
+   */
+  readonly thresholdBytes?: number;
+  /**
+   * LRU decode cache capacity (bytes). Defaults to
+   * {@link DEFAULT_CACHE_CAPACITY_BYTES}. Set to `0` to disable caching.
+   */
+  readonly decodeCacheCapacityBytes?: number;
+  /**
+   * Content-Type stamped on spilled blobs. The codec doesn't need to
+   * interpret it; artifact-store-api reflects it in `GET /blobs/:sha256`.
+   */
+  readonly contentType?: string;
+  /**
+   * Optional lifecycle observer. Called synchronously after each
+   * encode/decode with a structured event so ops can wire logging,
+   * Prometheus, OpenTelemetry, etc. Observer exceptions are swallowed
+   * so a faulty metrics emitter cannot break workflow payload flow.
+   */
+  readonly observer?: CodecObserver;
+}
+
+/**
+ * Temporal PayloadCodec that transparently spills any payload whose
+ * `data.byteLength` exceeds the configured threshold to a BlobStore. The
+ * resulting on-wire payload carries a small JSON envelope plus metadata
+ * markers; `decode` rehydrates by fetching the blob and restoring the
+ * original Payload.
+ *
+ * Determinism + safety invariants:
+ *   - Same bytes ⇒ same sha256 ⇒ same uri (content-addressed).
+ *   - Encode is idempotent at the (bytes, contentType) level.
+ *   - Decode verifies sha256 on fetch; mismatches raise SHA256_MISMATCH.
+ *   - Unknown store kinds in an incoming envelope fail fast with
+ *     UNKNOWN_STORE_KIND; no silent "best-effort" lookup.
+ *   - Payloads without `data` or below threshold pass through untouched.
+ */
+export class SpillPayloadCodec implements PayloadCodec {
+  private readonly stores: ReadonlyMap<BlobStoreKind, BlobStore>;
+  private readonly primaryStore: BlobStore;
+  private readonly thresholdBytes: number;
+  private readonly contentType: string;
+  private readonly cache: BytesLruCache;
+  private readonly orgIdProvider: () => string | Promise<string>;
+  private readonly observer: CodecObserver | null;
+
+  constructor(options: SpillPayloadCodecOptions) {
+    if (typeof options.orgIdProvider !== 'function') {
+      throw new Error('SpillPayloadCodec: orgIdProvider is required.');
+    }
+    if (!options.stores || Object.keys(options.stores).length === 0) {
+      throw new Error('SpillPayloadCodec: stores registry must contain at least one entry.');
+    }
+    const registry = new Map<BlobStoreKind, BlobStore>();
+    for (const [kind, store] of Object.entries(options.stores)) {
+      if (!store) {
+        continue;
+      }
+      if (store.kind !== kind) {
+        throw new Error(
+          `SpillPayloadCodec: stores['${kind}'] reports kind '${store.kind}'; the key must match the BlobStore.kind field.`,
+        );
+      }
+      registry.set(kind as BlobStoreKind, store);
+    }
+    const primary = registry.get(options.primaryStoreKind);
+    if (!primary) {
+      throw new Error(
+        `SpillPayloadCodec: primaryStoreKind='${options.primaryStoreKind}' is not present in stores registry. Register it before naming it primary.`,
+      );
+    }
+    this.stores = registry;
+    this.primaryStore = primary;
+    this.orgIdProvider = options.orgIdProvider;
+    this.thresholdBytes = options.thresholdBytes ?? DEFAULT_SPILL_THRESHOLD_BYTES;
+    if (!Number.isFinite(this.thresholdBytes) || this.thresholdBytes < 0) {
+      throw new Error(`SpillPayloadCodec: thresholdBytes must be a non-negative number.`);
+    }
+    this.contentType = options.contentType ?? 'application/x-temporal-payload';
+    const cacheCapacity = options.decodeCacheCapacityBytes ?? DEFAULT_CACHE_CAPACITY_BYTES;
+    this.cache = new BytesLruCache(cacheCapacity);
+    this.observer = options.observer ?? null;
+  }
+
+  private emit(event: CodecLifecycleEvent): void {
+    if (!this.observer) {
+      return;
+    }
+    try {
+      this.observer(event);
+    } catch {
+      // Observer exceptions are swallowed by contract — a broken metrics
+      // emitter must not corrupt Temporal payload flow.
+    }
+  }
+
+  /** Registered store kinds (read-only). Useful for diagnostic logs. */
+  get registeredStoreKinds(): readonly BlobStoreKind[] {
+    return [...this.stores.keys()];
+  }
+
+  /** Primary store kind — where new spills go. */
+  get primaryStoreKind(): BlobStoreKind {
+    return this.primaryStore.kind;
+  }
+
+  async encode(payloads: Payload[]): Promise<Payload[]> {
+    const result: Payload[] = [];
+    for (const payload of payloads) {
+      result.push(await this.encodeOne(payload));
+    }
+    return result;
+  }
+
+  async decode(payloads: Payload[]): Promise<Payload[]> {
+    const result: Payload[] = [];
+    for (const payload of payloads) {
+      result.push(await this.decodeOne(payload));
+    }
+    return result;
+  }
+
+  private async encodeOne(payload: Payload): Promise<Payload> {
+    const data = payload.data;
+    if (!data || data.byteLength < this.thresholdBytes) {
+      this.emit({ kind: 'encode', outcome: 'inline', sizeBytes: data?.byteLength ?? 0 });
+      return payload;
+    }
+    // If the payload is already a spill envelope (rare — means encode was
+    // called twice on the same payload), don't double-spill. Pass through.
+    if (this.isAlreadySpilled(payload)) {
+      this.emit({ kind: 'encode', outcome: 'already-spilled', sizeBytes: data.byteLength });
+      return payload;
+    }
+
+    const orgId = await this.resolveOrgId();
+
+    let stored;
+    try {
+      stored = await this.primaryStore.put(data, this.contentType, orgId);
+    } catch (err) {
+      if (err instanceof PayloadCodecError) {
+        throw err;
+      }
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.BLOB_PUT_FAILED,
+        `BlobStore.put failed: ${(err as Error).message}`,
+        { kind: this.primaryStore.kind, sizeBytes: data.byteLength, orgId },
+      );
+    }
+
+    const envelope: SpillEnvelope = {
+      $xemaSpill: SPILL_ENVELOPE_VERSION,
+      store: stored.store,
+      uri: stored.uri,
+      sha256: stored.sha256,
+      orgId: stored.orgId,
+      sizeBytes: stored.sizeBytes,
+      contentType: stored.contentType,
+      createdAt: stored.createdAt,
+    };
+    const envelopeBytes = TEXT_ENCODER.encode(JSON.stringify(envelope));
+    const originalMetadata = serializeOriginalMetadata(payload.metadata ?? null);
+
+    const metadata: Record<string, Uint8Array> = {
+      [SpillMetadataKey.ENCODING]: TEXT_ENCODER.encode(SPILL_ENCODING_V1),
+      [SpillMetadataKey.VERSION]: TEXT_ENCODER.encode(SPILL_ENVELOPE_VERSION),
+      [SpillMetadataKey.SHA256]: TEXT_ENCODER.encode(stored.sha256),
+      [SpillMetadataKey.SIZE]: TEXT_ENCODER.encode(String(stored.sizeBytes)),
+      [SpillMetadataKey.STORE]: TEXT_ENCODER.encode(stored.store),
+      [SpillMetadataKey.ORG_ID]: TEXT_ENCODER.encode(stored.orgId),
+      [SpillMetadataKey.ORIGINAL_METADATA]: TEXT_ENCODER.encode(originalMetadata),
+    };
+
+    this.emit({ kind: 'encode', outcome: 'spilled', sizeBytes: data.byteLength, orgId });
+    return { metadata, data: envelopeBytes };
+  }
+
+  private async resolveOrgId(): Promise<string> {
+    let raw: string;
+    try {
+      raw = await this.orgIdProvider();
+    } catch (err) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.ORG_ID_REQUIRED,
+        `orgIdProvider threw: ${(err as Error).message}`,
+      );
+    }
+    if (typeof raw !== 'string' || raw.length === 0) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.ORG_ID_REQUIRED,
+        'orgIdProvider returned no orgId; cannot spill payload to a multi-tenant blob store.',
+      );
+    }
+    return raw;
+  }
+
+  private async decodeOne(payload: Payload): Promise<Payload> {
+    if (!this.isAlreadySpilled(payload)) {
+      this.emit({
+        kind: 'decode',
+        outcome: 'inline-passthrough',
+        sizeBytes: payload.data?.byteLength ?? 0,
+      });
+      return payload;
+    }
+    const metadata = payload.metadata ?? {};
+    const { sha256, store } = readSpillMarkers(metadata);
+    const resolvedStore = this.resolveStoreOrThrow(store);
+    const envelope = this.parseEnvelope(payload.data, sha256);
+
+    const bytes = await this.rehydrateBlob(
+      envelope,
+      resolvedStore,
+      store,
+      sha256,
+      envelope.orgId,
+    );
+
+    const originalMetadataEncoded =
+      decodeUtf8(metadata[SpillMetadataKey.ORIGINAL_METADATA]) ?? '{}';
+    const restoredMetadata = deserializeOriginalMetadata(originalMetadataEncoded);
+
+    const out: Payload = { data: bytes };
+    if (Object.keys(restoredMetadata).length > 0) {
+      out.metadata = restoredMetadata;
+    }
+    return out;
+  }
+
+  private resolveStoreOrThrow(kind: BlobStoreKind): BlobStore {
+    const store = this.stores.get(kind);
+    if (!store) {
+      const registered = [...this.stores.keys()].join(', ') || '<none>';
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.UNKNOWN_STORE_KIND,
+        `Spilled payload references store '${kind}' which is not in the codec registry [${registered}]. ` +
+          `If this is a store-migration scenario, register the legacy store via WORKFLOW_PAYLOAD_CODEC_READ_STORES until in-flight workflows drain.`,
+        { received: kind, registered: [...this.stores.keys()] },
+      );
+    }
+    return store;
+  }
+
+  private parseEnvelope(data: Uint8Array | null | undefined, sha256: string): SpillEnvelope {
+    if (!data || data.byteLength === 0) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+        'Spilled payload has empty data (envelope JSON expected).',
+      );
+    }
+    let envelope: SpillEnvelope;
+    try {
+      const parsed = JSON.parse(decodeUtf8Strict(data)) as unknown;
+      envelope = assertEnvelope(parsed);
+    } catch (err) {
+      if (err instanceof PayloadCodecError) {
+        throw err;
+      }
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+        `Failed to parse spill envelope: ${(err as Error).message}`,
+      );
+    }
+    if (envelope.sha256 !== sha256) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+        'Envelope sha256 does not match metadata sha256.',
+        { metadataSha256: sha256, envelopeSha256: envelope.sha256 },
+      );
+    }
+    return envelope;
+  }
+
+  private async rehydrateBlob(
+    envelope: SpillEnvelope,
+    store: BlobStore,
+    storeKind: BlobStoreKind,
+    sha256: string,
+    orgId: string,
+  ): Promise<Uint8Array> {
+    // Cache key includes the store kind too — the same sha256 can exist
+    // in two registered stores during a migration, and we do not want a
+    // hit from one to mask a real read against the other.
+    const cacheKey = `${storeKind}:${orgId}:${sha256}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+    const ref: BlobRef = { store: storeKind, uri: envelope.uri, sha256, orgId };
+    let bytes: Uint8Array;
+    try {
+      bytes = await store.get(ref);
+    } catch (err) {
+      if (err instanceof PayloadCodecError) {
+        throw err;
+      }
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.BLOB_GET_FAILED,
+        `BlobStore.get failed: ${(err as Error).message}`,
+        { sha256 },
+      );
+    }
+    const actualSha = sha256Hex(bytes);
+    if (actualSha !== sha256) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.SHA256_MISMATCH,
+        'Fetched blob sha256 does not match the envelope.',
+        { expected: sha256, actual: actualSha },
+      );
+    }
+    this.cache.put(cacheKey, bytes);
+    return bytes;
+  }
+
+  private isAlreadySpilled(payload: Payload): boolean {
+    const encoding = decodeUtf8(payload.metadata?.[SpillMetadataKey.ENCODING]);
+    return encoding === SPILL_ENCODING_V1;
+  }
+
+  /** Exposed for tests + instrumentation. */
+  get cacheStats(): { count: number; bytes: number } {
+    return { count: this.cache.count, bytes: this.cache.size };
+  }
+}
+
+/**
+ * Keys the serializer strips when capturing the ORIGINAL metadata — the
+ * `xema-spill-*` markers are regenerated on every encode and must not
+ * round-trip. `SpillMetadataKey.ENCODING` is deliberately NOT in this set:
+ * it holds the payload's original encoding (e.g. `binary/plain`) which
+ * the consumer needs to decode the rehydrated bytes. The new (wire)
+ * payload's encoding is overwritten separately with `xema/spill-v1`.
+ */
+const SPILL_ONLY_METADATA_KEYS: ReadonlySet<string> = new Set([
+  SpillMetadataKey.VERSION,
+  SpillMetadataKey.SHA256,
+  SpillMetadataKey.SIZE,
+  SpillMetadataKey.STORE,
+  SpillMetadataKey.ORG_ID,
+  SpillMetadataKey.ORIGINAL_METADATA,
+]);
+
+/**
+ * Serialize a payload metadata map (`Record<string, Uint8Array>`) as a
+ * JSON object of base64-encoded values. Excludes ONLY the spill markers
+ * the codec itself writes; the payload's own `encoding` is preserved so
+ * the decoder can restore it bit-for-bit.
+ */
+function serializeOriginalMetadata(
+  metadata: Readonly<Record<string, Uint8Array>> | null,
+): string {
+  if (!metadata) {
+    return '{}';
+  }
+  const object: Record<string, string> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (SPILL_ONLY_METADATA_KEYS.has(key)) {
+      continue;
+    }
+    object[key] = Buffer.from(value).toString('base64');
+  }
+  return JSON.stringify(object);
+}
+
+function deserializeOriginalMetadata(raw: string): Record<string, Uint8Array> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      `Failed to parse original metadata JSON: ${(err as Error).message}`,
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      'Original metadata must be a JSON object.',
+    );
+  }
+  const result: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof value !== 'string') {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+        `Original metadata value for '${key}' is not a base64 string.`,
+      );
+    }
+    result[key] = new Uint8Array(Buffer.from(value, 'base64'));
+  }
+  return result;
+}
+
+function decodeUtf8(bytes: Uint8Array | undefined | null): string | null {
+  if (!bytes) {
+    return null;
+  }
+  try {
+    return TEXT_DECODER.decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+function decodeUtf8Strict(bytes: Uint8Array): string {
+  return TEXT_DECODER.decode(bytes);
+}
+
+function parseBlobStoreKind(raw: string): BlobStoreKind {
+  const known: readonly string[] = Object.values(BlobStoreKind);
+  if (!known.includes(raw)) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.UNKNOWN_STORE_KIND,
+      `Unknown spill store kind '${raw}'. Allowed: ${known.join(', ')}.`,
+      { raw },
+    );
+  }
+  return raw as BlobStoreKind;
+}
+
+function assertEnvelope(raw: unknown): SpillEnvelope {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      'Spill envelope must be a JSON object.',
+    );
+  }
+  const o = raw as Record<string, unknown>;
+  if (o['$xemaSpill'] !== SPILL_ENVELOPE_VERSION) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      `Spill envelope $xemaSpill field must equal '${SPILL_ENVELOPE_VERSION}'.`,
+    );
+  }
+  // Typed field reads: each helper asserts the JSON value is actually a
+  // string/number before we trust it. Without this, `String(o['uri'])`
+  // would silently coerce `{...}` or `[...]` to `'[object Object]'` and
+  // we'd ship garbage refs to the BlobStore.
+  return {
+    $xemaSpill: SPILL_ENVELOPE_VERSION,
+    store: parseBlobStoreKind(readRequiredString(o, 'store')),
+    uri: readRequiredString(o, 'uri'),
+    sha256: readRequiredString(o, 'sha256'),
+    orgId: readRequiredString(o, 'orgId'),
+    sizeBytes: readRequiredInteger(o, 'sizeBytes'),
+    contentType: readRequiredString(o, 'contentType'),
+    createdAt: readRequiredString(o, 'createdAt'),
+  };
+}
+
+function readRequiredString(obj: Record<string, unknown>, key: string): string {
+  const value = obj[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      `Spill envelope field '${key}' must be a non-empty string.`,
+      { key, kind: value === null ? 'null' : typeof value },
+    );
+  }
+  return value;
+}
+
+function readRequiredInteger(obj: Record<string, unknown>, key: string): number {
+  const value = obj[key];
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      `Spill envelope field '${key}' must be a non-negative integer.`,
+      { key, kind: typeof value },
+    );
+  }
+  return value;
+}
+
+function readSpillMarkers(metadata: Readonly<Record<string, Uint8Array>>): {
+  sha256: string;
+  store: BlobStoreKind;
+} {
+  const version = decodeUtf8(metadata[SpillMetadataKey.VERSION]);
+  if (version !== SPILL_ENVELOPE_VERSION) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      `Unknown spill envelope version: got '${version ?? '<missing>'}', expected '${SPILL_ENVELOPE_VERSION}'.`,
+      { version },
+    );
+  }
+  const sha256 = decodeUtf8(metadata[SpillMetadataKey.SHA256]);
+  const storeRaw = decodeUtf8(metadata[SpillMetadataKey.STORE]);
+  if (!sha256 || !storeRaw) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.MALFORMED_ENVELOPE,
+      'Spilled payload is missing required metadata (sha256 or store).',
+      { hasSha256: Boolean(sha256), hasStore: Boolean(storeRaw) },
+    );
+  }
+  return { sha256, store: parseBlobStoreKind(storeRaw) };
+}

package/src/payload-codec/lib/enums.ts

@@ -0,0 +1,58 @@
+/**
+ * Metadata keys the codec writes/reads on Temporal payloads. All keys are
+ * prefixed `xema-spill-` so they don't collide with Temporal's own
+ * encoding/messageType metadata.
+ */
+export enum SpillMetadataKey {
+  /** Signals that this payload was produced by the Xema spill codec. */
+  ENCODING = 'encoding',
+  /** Codec version — bumped if the envelope shape changes. */
+  VERSION = 'xema-spill-version',
+  /** Content-addressed id of the spilled blob in the backing store. */
+  SHA256 = 'xema-spill-sha256',
+  /** Size in bytes of the original (un-spilled) payload.data. */
+  SIZE = 'xema-spill-size',
+  /** Identifier of the backing store (e.g. `artifact-store`, `in-memory`). */
+  STORE = 'xema-spill-store',
+  /**
+   * Tenant id (orgId) the blob was written under. Required because the
+   * artifact-store-api scopes blobs by `(orgId, sha256)`; decoders read
+   * this back to fetch the same blob without ambient context.
+   */
+  ORG_ID = 'xema-spill-org-id',
+  /** Base64-encoded JSON of the original payload.metadata (sans the spill keys themselves). */
+  ORIGINAL_METADATA = 'xema-spill-original-metadata',
+}
+
+/** Value written to `metadata.encoding` when a payload is spilled. */
+export const SPILL_ENCODING_V1 = 'xema/spill-v1';
+
+/** Spill envelope version. Incoming payloads with a higher version fail fast. */
+export const SPILL_ENVELOPE_VERSION = '1';
+
+/**
+ * Default threshold in bytes — payloads smaller than this stay inline.
+ *
+ * Set to 64 KiB (was 128 KiB) so virtually every production CompiledRun
+ * dispatch exercises the spill path. Reasoning: typical CompiledRun JSON
+ * sits in the 40–110 KiB band; matrix expansions and reusable workflows
+ * push higher. A threshold straddling that band means some dispatches
+ * spill and others don't, which forces every consumer to handle both
+ * shapes. Lowering the threshold makes the spill path the only path,
+ * eliminates "passes locally, fails in prod near the boundary" bugs,
+ * and keeps Temporal payload size bounded regardless of workflow shape.
+ *
+ * Override via WORKFLOW_PAYLOAD_CODEC_THRESHOLD_BYTES on engine + worker.
+ */
+export const DEFAULT_SPILL_THRESHOLD_BYTES = 64 * 1024;
+
+/** Default LRU cache capacity in bytes. */
+export const DEFAULT_CACHE_CAPACITY_BYTES = 16 * 1024 * 1024;
+
+/** Known blob-store kinds. The codec refuses to read a blob from an unknown store. */
+export enum BlobStoreKind {
+  /** Production backing: artifact-store-api blob endpoints. */
+  ARTIFACT_STORE = 'artifact-store',
+  /** In-process map used by tests and dev harnesses. */
+  IN_MEMORY = 'in-memory',
+}

package/src/payload-codec/lib/errors.ts

@@ -0,0 +1,54 @@
+/**
+ * Typed error codes emitted by the spill codec. Callers MUST branch on
+ * `.code` — free-form message matching is forbidden, because these errors
+ * travel across process + network boundaries (Temporal workflow ↔ engine)
+ * and need a stable identity.
+ */
+export enum PayloadCodecErrorCode {
+  /** Input payload shape is invalid (e.g. missing data). */
+  INVALID_PAYLOAD = 'INVALID_PAYLOAD',
+  /** BlobStore.put failed during encode. */
+  BLOB_PUT_FAILED = 'BLOB_PUT_FAILED',
+  /** BlobStore.get failed during decode. */
+  BLOB_GET_FAILED = 'BLOB_GET_FAILED',
+  /** Received a spilled payload but no BlobStore is configured. */
+  NO_BLOB_STORE_CONFIGURED = 'NO_BLOB_STORE_CONFIGURED',
+  /** Spill envelope is malformed or uses an unknown version. */
+  MALFORMED_ENVELOPE = 'MALFORMED_ENVELOPE',
+  /** Envelope declares a store kind this codec doesn't know. */
+  UNKNOWN_STORE_KIND = 'UNKNOWN_STORE_KIND',
+  /** sha256 mismatch between envelope declaration and fetched blob. */
+  SHA256_MISMATCH = 'SHA256_MISMATCH',
+  /** orgIdProvider returned no orgId at encode time (fail-fast — no silent fallback). */
+  ORG_ID_REQUIRED = 'ORG_ID_REQUIRED',
+}
+
+export class PayloadCodecError extends Error {
+  readonly code: PayloadCodecErrorCode;
+  readonly details: Readonly<Record<string, unknown>>;
+
+  constructor(
+    code: PayloadCodecErrorCode,
+    message: string,
+    details: Readonly<Record<string, unknown>> = {},
+  ) {
+    super(message);
+    this.name = 'PayloadCodecError';
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  toJSON(): Readonly<Record<string, unknown>> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+export function isPayloadCodecError(err: unknown): err is PayloadCodecError {
+  return err instanceof PayloadCodecError;
+}