@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/errors/registry.js

@@ -1,560 +0,0 @@
-/**
- * @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.js

@@ -1,31 +0,0 @@
-/**
- * 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.js

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

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

@@ -1,5 +0,0 @@
-import { z } from "zod";
-export const NonEmptyString = z.string().min(1);
-export const ISODateTime = z.string().datetime({ offset: true });
-export const EntityId = (_table) => z.string().min(1).brand();
-export const ParamsBag = z.record(z.string(), z.unknown());