@cueframe/kernel 0.0.1

package/dist/brand-derivation/constants.d.ts

@@ -0,0 +1 @@
+export * from "../_members/brand-derivation/constants.js";

package/dist/brand-derivation/constants.js

@@ -0,0 +1,11 @@
+import {
+  DERIVATION_VERSION,
+  FLOORS,
+  NEUTRAL_RAMP
+} from "../chunk-JF4JJAFP.js";
+import "../chunk-2ESYSVXG.js";
+export {
+  DERIVATION_VERSION,
+  FLOORS,
+  NEUTRAL_RAMP
+};

package/dist/brand-derivation.d.ts

@@ -0,0 +1 @@
+export * from "./_members/brand-derivation/index.js";

package/dist/brand-derivation.js

@@ -0,0 +1,23 @@
+import {
+  apcaLc,
+  apcaLcFromLuminance,
+  clampToFloor,
+  deriveContrastSafe,
+  relativeLuminance
+} from "./chunk-V43Y7IE4.js";
+import {
+  DERIVATION_VERSION,
+  FLOORS,
+  NEUTRAL_RAMP
+} from "./chunk-JF4JJAFP.js";
+import "./chunk-2ESYSVXG.js";
+export {
+  DERIVATION_VERSION,
+  FLOORS,
+  NEUTRAL_RAMP,
+  apcaLc,
+  apcaLcFromLuminance,
+  clampToFloor,
+  deriveContrastSafe,
+  relativeLuminance
+};

package/dist/chunk-2ESYSVXG.js

@@ -0,0 +1,48 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+export {
+  __require,
+  __esm,
+  __commonJS,
+  __export,
+  __toESM,
+  __toCommonJS
+};

package/dist/chunk-37NJ27UU.js

@@ -0,0 +1,501 @@
+// ../errors/src/registry.ts
+var 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 the server capability registry).
+  // 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 }
+};
+var CueframeError = class extends Error {
+  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
+    };
+  }
+};
+var CFERR_PREFIX = "CFERR::";
+function b64encode(s) {
+  return btoa(unescape(encodeURIComponent(s)));
+}
+function b64decode(s) {
+  return decodeURIComponent(escape(atob(s)));
+}
+function encodeError(e) {
+  const json = JSON.stringify({ code: e.code, message: e.message, fix: e.fix, locator: e.locator });
+  return CFERR_PREFIX + b64encode(json);
+}
+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;
+  }
+}
+var 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
+];
+var 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"
+];
+var LOCATOR_ALLOW = ["projectId", "renderId", "requestId", "clipId", "trackId", "compositionPath"];
+var 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;
+}
+function scrubSensitive(s) {
+  return scrubStr(s);
+}
+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;
+}
+function pickScrub(obj, allow) {
+  if (!obj) return void 0;
+  const out = {};
+  for (const k of allow) if (k in obj) out[k] = scrubVal(obj[k]);
+  return Object.keys(out).length ? out : void 0;
+}
+function scrubAll(obj) {
+  if (!obj) return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = scrubVal(v);
+  return Object.keys(out).length ? out : void 0;
+}
+function toWireEnvelope(e, opts) {
+  const trusted = opts?.trusted ?? false;
+  let message;
+  let fix;
+  if (e.category === "internal") {
+    message = GENERIC.internal;
+    fix = void 0;
+  } 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 };
+}
+
+export {
+  ERROR_CODES,
+  CueframeError,
+  encodeError,
+  decodeError,
+  scrubSensitive,
+  toWireEnvelope
+};