@cueframe/kernel 0.0.1

package/dist/_members/errors/registry.js

@@ -0,0 +1,560 @@
+/**
+ * @cueframe/errors — the cross-cutting error contract SSOT.
+ *
+ * Zero `@cueframe/*` dependencies (enforced by the `errors-is-a-pure-leaf`
+ * dependency-cruiser rule) so it can be imported by every framework leaf
+ * (incl. perception + composition) and every service without a cycle.
+ *
+ * One vocabulary (`ERROR_CODES`), one carrier (`CueframeError`), one wire
+ * shape (`Envelope`), one Lambda-boundary codec (`encodeError`/`decodeError`),
+ * and one sanitization chokepoint (`toWireEnvelope`) that EVERY emit channel
+ * routes through before anything reaches an agent.
+ */
+export const ERROR_CODES = {
+    // auth / identity
+    unauthorized: { stage: "auth", category: "authoring", retryable: false, httpStatus: 401 },
+    forbidden: { stage: "auth", category: "authoring", retryable: false, httpStatus: 403 },
+    not_found: { stage: "auth", category: "authoring", retryable: false, httpStatus: 404 },
+    // billing / payment / x402
+    billing_required: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    billing_unavailable: { stage: "billing", category: "transient", retryable: true, httpStatus: 503 },
+    rate_limited: { stage: "billing", category: "transient", retryable: true, httpStatus: 429 },
+    // Per-handle concurrency guard: an x402 (anonymous payer) org is capped at
+    // X402_MAX_CONCURRENT_SESSIONS open warm compose boxes at once — one payer must
+    // not spin up unbounded expensive sandboxes. Transient/retryable (close a
+    // session, or wait for an idle one to auto-close, then retry) → 429.
+    too_many_active_sessions: { stage: "billing", category: "transient", retryable: true, httpStatus: 429 },
+    payment_required: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    payment_not_accepted: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    payment_verification_failed: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    payment_invalid: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    payment_replay: { stage: "billing", category: "authoring", retryable: false, httpStatus: 409 },
+    generation_budget_exceeded: { stage: "billing", category: "authoring", retryable: false, httpStatus: 402 },
+    // Capability maturity gate (spec 2026-07-20-client-lane-v1-launch §2.0): the
+    // capability exists but is not available on this surface (held/experimental —
+    // the server-side CAPABILITIES map in services/convex/api/capabilities.ts).
+    // Author-fixable (the error's details.pointer names the supported lane), so
+    // 403 non-retryable — mirrors `forbidden`, distinct code so an agent can
+    // route on it instead of misreading a permissions problem.
+    capability_unavailable: { stage: "auth", category: "authoring", retryable: false, httpStatus: 403 },
+    // import / media
+    import_unsupported_media: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    import_decode_failed: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    import_source_unreachable: { stage: "import", category: "transient", retryable: true, httpStatus: 422 },
+    import_processing_failed: { stage: "import", category: "internal", retryable: false, httpStatus: 422 },
+    media_not_ready: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    // A render mint's reframe needs the SOURCE's real width/height and the
+    // pipeline has not recorded them — probe unfinished OR probe failed, and the
+    // caller cannot tell which, so this is deliberately NOT `media_not_ready`
+    // (whose documented remedy is "wait for processing", a wait that never ends
+    // for a failed probe). The shipped agent skill documents this code with its
+    // own remedy (drop or defer the reframe intent); it was briefly aliased to
+    // media_not_ready, which made that documented vocabulary unreachable wire
+    // fiction — registered instead (2026-08-22 review).
+    source_dims_unknown: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    media_no_audio: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    // captions.fromTranscript (spec 2026-07-20 §2.2.6): the referenced media has
+    // no cached transcript (or no words in the requested window) — captions
+    // cannot be attached from it. Author-fixable (pick a speech-bearing media /
+    // widen the window / wait for processing to finish), so 422. Distinct from
+    // `transcript_unavailable` (503 — the transcript EXISTS but R2 retrieval
+    // failed transiently).
+    media_no_transcript: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    // POST /v1/media/{id}/transcript/analyze: the transcript is TOO BIG to analyse
+    // in one LLM pass. Deliberately NOT folded into `media_no_transcript` — that
+    // code sends an agent off to reprocess media that is perfectly fine, when the
+    // fix is entirely in the request (pass a narrower `window`). Author-fixable and
+    // deterministic, so 422 non-retryable: retrying the identical call cannot help.
+    // `details` carries chars/maxChars/startSec/endSec so the window can be chosen
+    // rather than guessed.
+    transcript_too_long: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    media_in_use: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    // A pool row whose BYTES ARE GONE — no local file, no cloud copy. Distinct
+    // from `media_not_ready` (bytes present, processing unfinished) and from
+    // `not_found` (no such row at all): the item is listed, the user can see it,
+    // and the remedy is re-import or removing the clips that use it. Not
+    // retryable — nothing changes by asking again.
+    media_missing: { stage: "import", category: "authoring", retryable: false, httpStatus: 422 },
+    invalid_import_url: { stage: "import", category: "authoring", retryable: false, httpStatus: 400 },
+    // validate / compose authoring
+    invalid_composition: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    validation_error: { stage: "validate", category: "authoring", retryable: false, httpStatus: 400 },
+    trim_out_of_bounds: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    timestamp_out_of_bounds: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    trim_inverted: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    reframe_coverage_gap: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Renamed from `image_media_on_video_track` 2026-08-17. The guard now derives
+    // the family from `mediaItems.mimeType` (schema-required, byte-detected)
+    // instead of the unmaintained `mediaItems.kind`, so it covers audio as well as
+    // stills — and it no longer fails open on media whose `kind` was never set.
+    // No alias for the old code: clean rename over a compat shim (CLAUDE.md).
+    media_family_track_mismatch: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Format-SSOT mint guard (resolveRenderTarget, P2.4): a render requests an
+    // aspect ratio that differs from the composition's authored format. Aspect is
+    // a property of the composition, not the render — changing it must go through a
+    // derive (a new composition), never a one-off render override. Author-fixable
+    // (derive a new composition at the target aspect, then render that), so 422.
+    aspect_change_requires_derive: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    delete_range_inverted: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    param_unwired: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    stale_etag: { stage: "validate", category: "authoring", retryable: false, httpStatus: 409 },
+    idempotency_conflict: { stage: "validate", category: "transient", retryable: true, httpStatus: 409 },
+    idempotency_key_mismatch: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    invalid_cursor: { stage: "validate", category: "authoring", retryable: false, httpStatus: 400 },
+    invalid_query: { stage: "validate", category: "authoring", retryable: false, httpStatus: 400 },
+    precondition_required: { stage: "validate", category: "authoring", retryable: false, httpStatus: 428 },
+    conflict: { stage: "validate", category: "authoring", retryable: false, httpStatus: 409 },
+    candidate_mismatch: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // import_resource { kind:"sfx-pack" } referenced a soundId the closed CC0 SFX
+    // pack doesn't carry (a typo, or a stale catalog). Fail loud rather than mint a
+    // row over non-existent bytes — the client author re-picks from list_catalog's
+    // sfx[]. Author-fixable, deterministic → authoring / non-retryable / 422.
+    unknown_pack_sound: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // A brand kit's audio ref (sonicLogo.ref — a palette reference) no longer
+    // resolves to a placeable sound: not a known pack soundId/bedId and not an
+    // org-owned media row (deleted, or drifted after the kit was authored). Fail
+    // loud at compose rather than silently dropping the brand signature — the
+    // author re-points the ref (list_catalog audio[]) or clears the sonic logo.
+    brand_audio_unresolvable: { stage: "compose", category: "authoring", retryable: false, httpStatus: 422 },
+    suggestions_already_complete: { stage: "validate", category: "authoring", retryable: false, httpStatus: 409 },
+    suggestions_already_running: { stage: "validate", category: "authoring", retryable: false, httpStatus: 409 },
+    // Clip-suggestion analysis is transcript-anchored — it scans spoken moments.
+    // A media item that processed cleanly but carries no speech (music beds,
+    // silent b-roll, screen-caps with no voiceover) has an empty transcript and
+    // can never yield clips. Distinct from `media_no_audio` (no audio STREAM at
+    // all): this fires when the source HAS audio but no detected speech, so the
+    // workflow would die in `fetchTranscriptData` after 3 wasted retries. Reject
+    // up front with a typed 422 so the agent learns to skip non-speech media.
+    suggestions_require_speech: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    clip_not_found: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // derive_composition (P5): the source composition a derive references doesn't
+    // exist OR isn't this project's / org's (deriveSibling collapses all three to one
+    // code so it can't leak cross-org composition existence). A referenced resource
+    // that isn't there is a 404 — mirrors the generic `not_found` (auth/404). The
+    // derive route catches it and re-throws as `not_found`; registering it here keeps
+    // a direct throw from falling through to internal_error → 500 (the
+    // clip_source_track_mismatch landmine).
+    source_composition_not_found: { stage: "validate", category: "authoring", retryable: false, httpStatus: 404 },
+    // Composition wire-boundary projection guards (saveComposition). These fire on
+    // a track/source-kind mismatch or a primitive pick the catalog can't satisfy —
+    // all author-fixable, so they map to 422. Registered here so they surface as
+    // typed envelopes (and so composition.apply + composition.apply?dry_run can
+    // report them) instead of falling through to internal_error → 500.
+    clip_source_track_mismatch: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // A FRONT overlay carrying a scene-space `anchor` (spec 2026-07-20 §2.1.1):
+    // anchor's only render semantics is world-lock through the crop-transformed
+    // source plane, which exists only on the behind plane (BehindOverlayHost's
+    // mount). On a front overlay it was a silent no-op — the agent authored an
+    // anchor and the render ignored it. Author-fixable (set zPlane
+    // 'behind-subject', or place with position/region), so 422.
+    anchor_requires_behind: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    unknown_primitive: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // A KNOWN primitive retired via the disabled denylist (e.g. heroText) — rejected
+    // at the write boundary, distinct from unknown_primitive so the fix is "pick a
+    // different primitive", not "fix the typo / update the submodule".
+    disabled_primitive: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    invalid_primitive_params: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Two behind-subject heroText overlays with overlapping time windows —
+    // stacked hero phrases render over each other; one hero at a time.
+    overlapping_hero_overlays: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    custom_missing_sourcecode: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Component-authoring write path (internalInstall / internalUpsertComponent):
+    // the stored propSchema must be a parseable plain JSON object. A non-JSON or
+    // non-object schema is author-fixable, so 422 — registered here so it surfaces
+    // as a typed envelope instead of falling through to internal_error → 500.
+    invalid_prop_schema: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Component preview compile gate (component.preview → per-tenant box transpile):
+    // a tenant's tsxSource that fails to transpile/bundle is author-fixable, so 422
+    // (never a red-box / 500). The director box throws ComponentDoesNotCompile; the
+    // route maps it here so the authoring agent gets a typed envelope + the
+    // sanitized compiler message to self-correct.
+    component_does_not_compile: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    component_runtime_error: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // Component materialize (Phase B): a composition's alpha-layer clip references a
+    // component whose authored tsxSource is absent OR null for the org (legacy rows
+    // can carry a null source). Author-fixable (POST/PUT /v1/components first), so
+    // 422 — registered here so the debug-session render/verify routes surface a
+    // typed envelope instead of an opaque bake-side exit-3 / internal_error → 500.
+    component_source_unavailable: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // applyMotionPreset op (public card-shelling): the requested preset is not in
+    // the MOTION_PRESETS vocabulary. Author-fixable (pick a listed preset), so 422
+    // — registered so the op route surfaces a typed envelope + the valid list
+    // instead of falling through to internal_error → 500.
+    motion_preset_unknown: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // applyMotionPreset op: the target clip is missing OR is not a STATIC card (a
+    // preset can only shell an un-animated card). Author-fixable (target a card
+    // clip id), so 422 — one code, the message distinguishes missing vs wrong-kind.
+    motion_preset_target_invalid: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // materializeGrid op (temporal-grid → markers): the referenced clip is missing
+    // or is not a MEDIA clip (a grid is a property of source media). Author-fixable
+    // (target a media clip id), so 422 — the message distinguishes missing vs kind.
+    grid_target_invalid: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // materializeGrid op: the requested grid (beat/word) evidence is absent on the
+    // clip's source media — a beat grid needs a MUSIC-role analyzed bed, a word
+    // grid needs a transcript. Author-fixable (declare audioRole:"music" at ingest
+    // / transcribe), so 422 — the message names which evidence is missing and how
+    // to get it, never a silent empty materialization.
+    grid_unavailable: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // materializeGrid op with grid:"shot": shot-boundary evidence is computed by
+    // the perception lane but not yet exposed per-media on get_media_context (it
+    // lives only inside the R2 subject-track artifact); exposure rides a later
+    // perception arc. Fail loud (422) rather than materialize nothing.
+    shot_grid_unavailable: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // materializeGrid op: the grid produces MORE markers than the cap (default 500,
+    // ceiling 2000). Author-fixable (raise maxMarkers ≤2000 or narrow the clip's
+    // visible window), so 422 — fail loud with the count, never a silent truncation.
+    grid_cap_exceeded: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // render
+    // Generation moderation gate (P5 4a): a fal generation whose output carries a
+    // truthy NSFW/moderation flag (e.g. flux/dev `has_nsfw_concepts`) is blocked at
+    // falClient.result() BEFORE download/R2-put/finalize. Author-fixable (re-prompt),
+    // so 422 + retryable:false — the same moderated prompt re-runs to the same flag,
+    // and the workflow's catch → markGenerationFailed clears the genHash so a
+    // moderated result is never cached as a dedup target ("never cache a black frame
+    // as success").
+    generation_moderation_blocked: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // Session box version-gate timeout: the in-box daemon/subscription is dead —
+    // INFRA, not author-fixable (a NEW session may work, hence transient/503).
+    // The MCP adapter classifies this InfraToolError → agent loop halts.
+    session_version_timeout: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+    resource_import_in_flight: { stage: "validate", category: "transient", retryable: true, httpStatus: 503 },
+    trajectory_coverage_gap: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    trajectory_unresolved: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    subject_not_tracked: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // D10 (P5 4b): a SUBJECT-mode reframe (face / active-speaker / all-faces) on
+    // AI-GENERATED media (`mediaItems.mediaSource === "generated"`) whose subject
+    // resolves in < MIN_SUBJECT_RESOLUTION of the segment. Distinct from
+    // `subject_not_tracked` so the driving agent learns the corrective action is a
+    // GEOMETRIC reframe (frame-center / point) on faceless b-roll — not a re-detect.
+    // Author-fixable → 422, retryable:false (mirrors subject_not_tracked).
+    subject_detection_failed_on_generated: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // virtual-camera (vcam) reframe — registered in Phase 1 so an unregistered
+    // code can never fall back to internal_error → 500 when the throwing phase
+    // lands (the clip_source_track_mismatch landmine). See the vcam spec's
+    // "Fail-loud invariants & determinism" / "Registry wiring is Phase 1" section.
+    // `trajectory_internal_gap` is a derive-side tiling assertion (sub-shots must
+    // tile the segment) → internal, not author-facing. `subject_uncontainable` and
+    // `clip_trajectory_merge_conflict` are authoring 422s the agent can act on.
+    trajectory_internal_gap: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+    subject_uncontainable: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    clip_trajectory_merge_conflict: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // Selector core / adapters (selector-abstraction spec §8 fail-loud invariants).
+    // Registered in Phase 1 so an unregistered code can never fall back to
+    // internal_error → 500 when the throwing phase lands (the
+    // clip_source_track_mismatch landmine). The CORE throws `selector_signal_absent`
+    // (a weight over an all-null signal) and `selector_override_conflict` (a same-
+    // tier override/force collision — the Gap.strict() fail-loud lesson). The
+    // ADAPTER/LOWERING throw the timebase/sync/out-of-media codes (Phase 2 switch),
+    // registered now. All are authoring 422s the agent can act on except the
+    // override conflict which is also authoring (two pins collide → the agent fixes
+    // the policy).
+    selector_signal_absent: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    selector_override_conflict: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    selector_timebase_undefined: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    selector_group_unsynced: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    selector_segment_out_of_media: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // Phase 3 (active-speaker): the STRUCTURAL double-count guard (§11-L5). When the
+    // agent weights `activeSpeaker`, the within-source `speaking` sub-term MUST be
+    // zeroed in the SAME weight vector (the double-count is fixed by the WEIGHT, not
+    // by a provider reading siblings). Weighting BOTH > 0 double-counts the speaker —
+    // fail loud with the fix (set weights.speaking = 0) rather than silently inflate.
+    selector_speaking_double_count: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // Phase 6 (cross-source identity): a `lockPersonId` match over an embedding whose
+    // `DETECTOR_VERSION` differs from the reference is meaningless (the 3-stamp lesson)
+    // — fail loud (re-detect at the current version) rather than guess across versions.
+    selector_identity_detector_version_mismatch: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    variant_not_baked: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+    behind_matte_unresolved: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+    // C1 delivered-artifact floor: the rendered/mastered OUTPUT mp4 failed a
+    // pre-delivery integrity check — a truncated container (duration mismatch) or a
+    // blank film (every sampled frame near-uniform). Three real incidents shipped
+    // GREEN before this gate (two cache-poisoned blank films + a v22-clamp
+    // truncation), so the check runs on the final bytes and REFUSES to hand back the
+    // URL. An internal pipeline defect, not author-fixable → category internal. The
+    // failure reproduces deterministically (same snapshot → same truncation/blank),
+    // so retry would loop → retryable:false. 422 mirrors the sibling render-integrity
+    // codes (variant_not_baked / behind_matte_unresolved).
+    render_output_invalid: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+    // Phase 4 AV-sync floor (audio-substrate P0): the delivered mix drifted off the
+    // authored sfx hits — a MAJORITY of placed sfx-role transients landed >100ms from
+    // any detected onset in the mastered output. Detected after loudnorm on Modal's
+    // /master route (librosa onset_detect vs the composition's sfx clip startTimes) and
+    // decided in the director (advisory-first: a minority draws a non-fatal advisory;
+    // only systemic drift fails). Author-adjacent — the offending clipIds are named so
+    // the placement can be re-timed → category authoring. Deterministic (same mastered
+    // bytes reproduce the onset set) → retryable:false. Fails OPEN on absent evidence
+    // (no onsets at all), so this code only fires on real, measured drift.
+    audio_sync_invalid: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // SFX pack-first Task 4 envelope floor: a GENERATED sound effect
+    // (text-to-sfx) failed a delivery integrity check — provably silent output, a
+    // clipping peak, or a duration mismatch vs the pinned durationSec. Probed on
+    // Modal's /probe-audio route (the director box has no ffmpeg) BEFORE the media
+    // row flips ready; the typed 422 is decoded into a non-retryable failure so a
+    // bad output never caches as success and never re-bills fal. Author-adjacent
+    // (a different/looser prompt may generate a usable effect) → category
+    // authoring, mirroring generation_moderation_blocked. Deterministic (same
+    // bytes reproduce it) → retryable:false. 422 mirrors the sibling generation +
+    // render-integrity codes.
+    generation_output_invalid: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // C2 bake-opacity sanity floor: an element-class component's alpha bake
+    // (text/effects/ui-blocks — elements OVER a base layer) came out ~fully opaque
+    // on EVERY sampled frame, which occludes the whole frame and is provably
+    // wrong. This is the caption-spine-holds-the-world-layer poisoning signature
+    // (2026-07-21: a concurrent bake cross-baked the opaque world layer under the
+    // transparent caption key, and every downstream render composited a blank film
+    // delivered green). The bake activity samples the alpha BEFORE R2 upload and
+    // REFUSES the artifact, naming the clip. Every frame-filling category is
+    // exempt — backgrounds/layouts (opaque by definition), scenes (a full-screen
+    // scene legitimately fills the frame opaquely), transitions (dip-to-black is
+    // opaque by design). Deterministic reproduction (same bytes → same opacity) →
+    // retryable:false. Internal pipeline defect → internal.
+    bake_output_opaque: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+    source_media_not_found: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // A brand-kit create supplied an exemplar/contact-sheet R2 key outside the
+    // org's `brand-inspiration/{orgId}/` prefix. Those keys get presigned
+    // downstream (vision tool + judge), so an unvalidated key is a cross-org R2
+    // read primitive — refuse it, naming the field (spec D2 security).
+    exemplar_key_not_org_owned: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+    // The render's resolved brand kit does not resolve for this org at render-create
+    // (no kit row, deleted, or cross-org). The brand SSOT is the PROJECT (P1.1):
+    // render resolves from project.brandKitId (or a per-render override), never the
+    // composition. Fail loud instead of silently rendering UNBRANDED (the agent
+    // referenced a brand and would get nothing, with zero signal) — author-fixable
+    // (bind a valid kit via project.brandKitId / PATCH /projects/:id, or clear it),
+    // so 422 + retryable:false. Reserved here as the SSOT code; the render-create
+    // fail-loud that throws it is (re-)wired against the project-resolved brand
+    // post-merge. A render with NO brand kit is NOT this error — unbranded is a
+    // valid, if unthemed, render (a non-fatal `warnings[]` advisory instead).
+    brand_kit_unresolved: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    unknown_format: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    render_not_cancellable: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    compose_not_cancellable: { stage: "system", category: "authoring", retryable: false, httpStatus: 422 },
+    job_not_cancellable: { stage: "system", category: "authoring", retryable: false, httpStatus: 422 },
+    export_not_cancellable: { stage: "export", category: "authoring", retryable: false, httpStatus: 422 },
+    render_not_complete: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    lambda_infra_failed: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+    // A render reached `rendering` (or was dispatched with a temporalRunId) and
+    // then lost its terminal write — the Temporal workflow died / the isolate that
+    // would have flipped the row never ran — so the heartbeat (`updatedAt`) goes
+    // stale and wait_job / the advised render.complete webhook dead-end forever
+    // with no terminal. The stall watchdog (rendersAction.sweepStalledRenderJobs)
+    // reaps such a row into status=error with THIS code so the surface terminalizes
+    // and a render.failed webhook fires. A stalled render is SAFE TO RETRY (the
+    // input is fine; the pipeline dropped it) → transient + retryable:true (500),
+    // so retry_render is the correct recovery. NOTE: a deeper Temporal-authority
+    // reconcile (ask Temporal what the workflow is actually doing, à la the
+    // exports-watchdog) is tracked separately in the render-engine plan
+    // (2026-06-29-render-engine-dogfood-fixes.md); this is the surface-completing
+    // heartbeat-timeout terminal only.
+    render_stalled: { stage: "render", category: "transient", retryable: true, httpStatus: 500 },
+    // A primitive id reached the RENDER boundary that the live render registry
+    // (@cueframe/compose `resolvePrimitive`) cannot resolve — a typo'd / drifted
+    // / pre-guard-snapshot primitiveId. Previously the renderer silently dropped
+    // it (return null / fall through to DynamicOverlay) and shipped a broken MP4
+    // with zero agent signal. Fail loud instead so it surfaces as the render job's
+    // errorCode (RenderResponse.errorCode + category/retryable). Author-fixable
+    // (fix the primitiveId) → 422, retryable:false. DEFENSE-IN-DEPTH: the write
+    // boundary (validatePrimitiveMembership at save/apply) already rejects unknown
+    // ids; this catches anything that slipped through (e.g. a snapshot authored
+    // before the guard, or version-map drift ahead of the render registry).
+    render_unknown_primitive: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+    // export
+    session_in_use: { stage: "export", category: "authoring", retryable: false, httpStatus: 422 },
+    transcript_unavailable: { stage: "export", category: "transient", retryable: true, httpStatus: 503 },
+    // system
+    service_unavailable: { stage: "system", category: "transient", retryable: true, httpStatus: 503 },
+    internal_error: { stage: "system", category: "internal", retryable: false, httpStatus: 500 },
+};
+export class CueframeError extends Error {
+    code;
+    fix;
+    locator;
+    constructor(code, message, fix, locator) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.locator = locator;
+        this.name = "CueframeError";
+    }
+    toEnvelope() {
+        const s = ERROR_CODES[this.code];
+        return {
+            code: this.code,
+            stage: s.stage,
+            category: s.category,
+            retryable: s.retryable,
+            httpStatus: s.httpStatus,
+            message: this.message,
+            fix: this.fix,
+            locator: this.locator,
+        };
+    }
+}
+// ── Lambda-boundary codec ─────────────────────────────────────────────────
+// Remotion/Temporal forward only standard Error props (name/message/stack), so
+// a CueframeError's `code`/`fix` are dropped across a process boundary. We
+// serialize the envelope into the MESSAGE behind a sentinel prefix; the director
+// (and the Convex route) detect the prefix and reconstruct the typed error.
+//
+// The payload is BASE64, not raw JSON: the message gets re-serialized multiple
+// times across the boundary (Remotion JSON-encodes the Error, the activity wraps
+// it again as `Lambda render failed: {…}`), which would escape the quotes in raw
+// JSON and break a naive parse. Base64 contains no quotes/backslashes/newlines,
+// so it survives arbitrary nesting and is extracted by a simple charset match.
+const CFERR_PREFIX = "CFERR::";
+function b64encode(s) {
+    // Unicode-safe and works in both the Remotion (browser-like) bundle and Node.
+    return btoa(unescape(encodeURIComponent(s)));
+}
+function b64decode(s) {
+    return decodeURIComponent(escape(atob(s)));
+}
+export function encodeError(e) {
+    const json = JSON.stringify({ code: e.code, message: e.message, fix: e.fix, locator: e.locator });
+    return CFERR_PREFIX + b64encode(json);
+}
+export function decodeError(msg) {
+    const m = msg.match(/CFERR::([A-Za-z0-9+/=]+)/);
+    if (!m)
+        return null;
+    try {
+        const o = JSON.parse(b64decode(m[1]));
+        if (!o || typeof o.code !== "string" || !(o.code in ERROR_CODES))
+            return null;
+        return new CueframeError(o.code, String(o.message ?? ""), o.fix, o.locator);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Sanitization chokepoint ───────────────────────────────────────────────
+// EVERY emit channel (HTTP body, renderJobs/mediaItems row writes, SSE,
+// webhook) MUST serialize through toWireEnvelope before emitting. Default-deny:
+// internal/transient errors get a generic message and NO fix; authoring errors
+// get an allow-listed, scrubbed fix. The full raw error goes to logs only.
+// Global so scrubStr can REDACT each occurrence (substring), not nuke the whole
+// string. Each pattern consumes the full sensitive token so the replacement
+// removes it cleanly while leaving surrounding human-readable text intact.
+const SENSITIVE = [
+    /https?:\/\/\S+/gi, // URLs (presigned R2/S3, Lambda sites, etc.)
+    /\b[\w.-]*\.r2\.cloudflarestorage\.[\w./-]*/gi, // R2 hosts/keys (scheme-less)
+    /\bremotionlambda[\w.-]*/gi, // Lambda render host
+    /\bs3[.-][\w.-]*/gi, // s3 host (scheme-less)
+    /\b[\w.-]*\.internal\b/gi, // internal domains
+    /\/(?:Users|home|var|tmp|root)\/\S*/gi, // absolute fs paths
+    /\b\d{1,3}(?:\.\d{1,3}){3}\b/g, // IPv4 literals
+];
+const FIX_ALLOW = [
+    "issues",
+    "uncovered",
+    "gapFrames",
+    "clipId",
+    "trackId",
+    "brandKitId",
+    "srcFrame",
+    "firstSegmentStart",
+    "mediaId",
+    "aspect",
+    "intentHash",
+    "remedies",
+    "retryAfter",
+    "compositionPath",
+    "nearest",
+    // invalid_primitive_params closed-key/typed param-shape detail. Flat unions
+    // surfacing the common single-overlay case; per-issue detail rides in `issues`.
+    "unknownKeys",
+    "allowedKeys",
+    "typeMismatches",
+    "constraintViolations",
+];
+const LOCATOR_ALLOW = ["projectId", "renderId", "requestId", "clipId", "trackId", "compositionPath"];
+const GENERIC = {
+    transient: "A temporary error occurred; retry.",
+    internal: "An unexpected error occurred.",
+};
+function scrubStr(v) {
+    if (typeof v !== "string")
+        return v;
+    let s = v;
+    for (const r of SENSITIVE)
+        s = s.replace(r, "(redacted)");
+    return s;
+}
+/** Scrub SENSITIVE tokens from a raw message that will be PERSISTED or shipped
+ *  over a webhook without passing through toWireEnvelope — e.g. failRenderJob's
+ *  non-CFERR fallback, where the deep root cause can carry fs paths, presigned
+ *  URLs, or Lambda hosts verbatim. */
+export function scrubSensitive(s) {
+    return scrubStr(s);
+}
+// Recurse into objects AND arrays so a sensitive string nested inside a fix
+// value (e.g. an issue object holding a private IP) can't slip past — every
+// leaf string is scrubbed regardless of depth.
+function scrubVal(v) {
+    if (typeof v === "string")
+        return scrubStr(v);
+    if (Array.isArray(v))
+        return v.map(scrubVal);
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = scrubVal(val);
+        return out;
+    }
+    return v;
+}
+/** Keep only allow-listed keys, scrubbing each value. For UNTRUSTED payloads. */
+function pickScrub(obj, allow) {
+    if (!obj)
+        return undefined;
+    const out = {};
+    for (const k of allow)
+        if (k in obj)
+            out[k] = scrubVal(obj[k]);
+    return Object.keys(out).length ? out : undefined;
+}
+/** Keep ALL keys, scrubbing each value. For TRUSTED (author-built) payloads. */
+function scrubAll(obj) {
+    if (!obj)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        out[k] = scrubVal(v);
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * The single sanitization chokepoint. EVERY emit channel routes through it.
+ *
+ * `opts.trusted` marks an author-curated envelope (a route-built `ApiError`) whose
+ * `message` and `fix` we wrote ourselves — vs an UNtrusted envelope translated from a
+ * raw/deep error (Lambda/processing/unmapped `ConvexError`) whose text/fields may carry a
+ * stack or infra detail. Never set `trusted` for a translated error.
+ *
+ * - TRUSTED: keep the message (scrubbed defensively) and all `fix` keys (values scrubbed),
+ *   so curated fields like `currentEtag`/`projectIds`/`name`/`reason`/`retryAfter` survive
+ *   on errors of ANY category — except `internal`, where `fix` is always dropped.
+ * - UNTRUSTED: `internal`/`transient` get a generic message; `authoring` keeps a scrubbed
+ *   message. `fix` is dropped for `internal` and otherwise reduced to the allow-list +
+ *   scrubbed (so `retryAfter` survives but a raw `filePath`/URL cannot).
+ * - `locator`: always reduced to the safe key set.
+ */
+export function toWireEnvelope(e, opts) {
+    const trusted = opts?.trusted ?? false;
+    let message;
+    let fix;
+    if (e.category === "internal") {
+        // Always opaque — never surface an author- or stack-derived internal message/fix.
+        message = GENERIC.internal;
+        fix = undefined;
+    }
+    else if (trusted) {
+        message = scrubStr(e.message);
+        fix = scrubAll(e.fix);
+    }
+    else {
+        message = e.category === "authoring" ? scrubStr(e.message) : GENERIC[e.category];
+        fix = pickScrub(e.fix, FIX_ALLOW);
+    }
+    const locator = pickScrub(e.locator, LOCATOR_ALLOW);
+    return { ...e, message, fix, locator };
+}

package/dist/_members/foundation/codes/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-cutting invariant code registry.
+ *
+ * Each domain package declares its own typed code union and constructs
+ * `InvariantError` for failures. The shared `InvariantViolation` /
+ * `InvariantError` shape gives every domain a uniform error contract
+ * (HTTP error mapping, log shape, projection-failure reporting) without
+ * forcing all codes into one enum.
+ *
+ * Usage from a domain package:
+ *
+ *   import { InvariantError, type InvariantViolation } from "./index.js";
+ *
+ *   export type CompositionInvariantCode =
+ *     | "track_clips_overlap"
+ *     | "transition_no_predecessor";
+ *
+ *   export function trackClipsOverlap(details: { trackId: string }): InvariantViolation<CompositionInvariantCode> {
+ *     return { code: "track_clips_overlap", message: "...", details };
+ *   }
+ */
+export interface InvariantViolation<TCode extends string = string> {
+    code: TCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare class InvariantError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly details?: Record<string, unknown>;
+    constructor(violation: InvariantViolation<TCode>);
+}

package/dist/_members/foundation/codes/index.js

@@ -0,0 +1,31 @@
+/**
+ * Cross-cutting invariant code registry.
+ *
+ * Each domain package declares its own typed code union and constructs
+ * `InvariantError` for failures. The shared `InvariantViolation` /
+ * `InvariantError` shape gives every domain a uniform error contract
+ * (HTTP error mapping, log shape, projection-failure reporting) without
+ * forcing all codes into one enum.
+ *
+ * Usage from a domain package:
+ *
+ *   import { InvariantError, type InvariantViolation } from "@cueframe/foundation/codes";
+ *
+ *   export type CompositionInvariantCode =
+ *     | "track_clips_overlap"
+ *     | "transition_no_predecessor";
+ *
+ *   export function trackClipsOverlap(details: { trackId: string }): InvariantViolation<CompositionInvariantCode> {
+ *     return { code: "track_clips_overlap", message: "...", details };
+ *   }
+ */
+export class InvariantError extends Error {
+    code;
+    details;
+    constructor(violation) {
+        super(`${violation.code}: ${violation.message}`);
+        this.code = violation.code;
+        this.details = violation.details;
+        this.name = "InvariantError";
+    }
+}

package/dist/_members/foundation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./primitives/index.js";
+export * from "./codes/index.js";

package/dist/_members/foundation/index.js

@@ -0,0 +1,2 @@
+export * from "./primitives/index.js";
+export * from "./codes/index.js";