@cueframe/kernel 0.0.1

package/dist/_members/errors/registry.d.ts

@@ -0,0 +1,708 @@
+/**
+ * @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 type ErrorStage = "auth" | "billing" | "import" | "validate" | "compose" | "render" | "export" | "system";
+export type ErrorCategory = "authoring" | "transient" | "internal";
+export interface ErrorSpec {
+    stage: ErrorStage;
+    category: ErrorCategory;
+    retryable: boolean;
+    httpStatus: number;
+}
+export declare const ERROR_CODES: {
+    readonly unauthorized: {
+        readonly stage: "auth";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 401;
+    };
+    readonly forbidden: {
+        readonly stage: "auth";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 403;
+    };
+    readonly not_found: {
+        readonly stage: "auth";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 404;
+    };
+    readonly billing_required: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly billing_unavailable: {
+        readonly stage: "billing";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly rate_limited: {
+        readonly stage: "billing";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 429;
+    };
+    readonly too_many_active_sessions: {
+        readonly stage: "billing";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 429;
+    };
+    readonly payment_required: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly payment_not_accepted: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly payment_verification_failed: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly payment_invalid: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly payment_replay: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 409;
+    };
+    readonly generation_budget_exceeded: {
+        readonly stage: "billing";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 402;
+    };
+    readonly capability_unavailable: {
+        readonly stage: "auth";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 403;
+    };
+    readonly import_unsupported_media: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly import_decode_failed: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly import_source_unreachable: {
+        readonly stage: "import";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 422;
+    };
+    readonly import_processing_failed: {
+        readonly stage: "import";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_not_ready: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly source_dims_unknown: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_no_audio: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_no_transcript: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly transcript_too_long: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_in_use: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_missing: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly invalid_import_url: {
+        readonly stage: "import";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 400;
+    };
+    readonly invalid_composition: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly validation_error: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 400;
+    };
+    readonly trim_out_of_bounds: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly timestamp_out_of_bounds: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly trim_inverted: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly reframe_coverage_gap: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly media_family_track_mismatch: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly aspect_change_requires_derive: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly delete_range_inverted: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly param_unwired: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly stale_etag: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 409;
+    };
+    readonly idempotency_conflict: {
+        readonly stage: "validate";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 409;
+    };
+    readonly idempotency_key_mismatch: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly invalid_cursor: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 400;
+    };
+    readonly invalid_query: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 400;
+    };
+    readonly precondition_required: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 428;
+    };
+    readonly conflict: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 409;
+    };
+    readonly candidate_mismatch: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly unknown_pack_sound: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly brand_audio_unresolvable: {
+        readonly stage: "compose";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly suggestions_already_complete: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 409;
+    };
+    readonly suggestions_already_running: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 409;
+    };
+    readonly suggestions_require_speech: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly clip_not_found: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly source_composition_not_found: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 404;
+    };
+    readonly clip_source_track_mismatch: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly anchor_requires_behind: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly unknown_primitive: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly disabled_primitive: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly invalid_primitive_params: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly overlapping_hero_overlays: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly custom_missing_sourcecode: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly invalid_prop_schema: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly component_does_not_compile: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly component_runtime_error: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly component_source_unavailable: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly motion_preset_unknown: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly motion_preset_target_invalid: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly grid_target_invalid: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly grid_unavailable: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly shot_grid_unavailable: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly grid_cap_exceeded: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly generation_moderation_blocked: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly session_version_timeout: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly resource_import_in_flight: {
+        readonly stage: "validate";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly trajectory_coverage_gap: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly trajectory_unresolved: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly subject_not_tracked: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly subject_detection_failed_on_generated: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly trajectory_internal_gap: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly subject_uncontainable: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly clip_trajectory_merge_conflict: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_signal_absent: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_override_conflict: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_timebase_undefined: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_group_unsynced: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_segment_out_of_media: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_speaking_double_count: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly selector_identity_detector_version_mismatch: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly variant_not_baked: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly behind_matte_unresolved: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly render_output_invalid: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly audio_sync_invalid: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly generation_output_invalid: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly bake_output_opaque: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly source_media_not_found: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly exemplar_key_not_org_owned: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly brand_kit_unresolved: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly unknown_format: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly render_not_cancellable: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly compose_not_cancellable: {
+        readonly stage: "system";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly job_not_cancellable: {
+        readonly stage: "system";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly export_not_cancellable: {
+        readonly stage: "export";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly render_not_complete: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly lambda_infra_failed: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly render_stalled: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 500;
+    };
+    readonly render_unknown_primitive: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly session_in_use: {
+        readonly stage: "export";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
+    readonly transcript_unavailable: {
+        readonly stage: "export";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly service_unavailable: {
+        readonly stage: "system";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly internal_error: {
+        readonly stage: "system";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+export interface Envelope {
+    code: ErrorCode;
+    stage: ErrorStage;
+    category: ErrorCategory;
+    retryable: boolean;
+    httpStatus: number;
+    message: string;
+    fix?: Record<string, unknown>;
+    locator?: Record<string, unknown>;
+}
+export declare class CueframeError extends Error {
+    readonly code: ErrorCode;
+    readonly fix?: Record<string, unknown> | undefined;
+    readonly locator?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, fix?: Record<string, unknown> | undefined, locator?: Record<string, unknown> | undefined);
+    toEnvelope(): Envelope;
+}
+export declare function encodeError(e: CueframeError): string;
+export declare function decodeError(msg: string): CueframeError | null;
+/** 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 declare function scrubSensitive(s: string): string;
+/**
+ * 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 declare function toWireEnvelope(e: Envelope, opts?: {
+    trusted?: boolean;
+}): Envelope;