@skyphusion-labs/vivijure-core 0.9.0

package/dist/modules/types.d.ts

@@ -0,0 +1,544 @@
+/** The contract version a module targets. Bumped only on a breaking change to these shapes. */
+export declare const MODULE_API: "vivijure-module/2";
+export type ModuleApi = "vivijure-module/1" | "vivijure-module/2";
+export declare const SUPPORTED_MODULE_APIS: ReadonlySet<ModuleApi>;
+/** The pipeline extension points. `pick one` hooks resolve to a single module; `chain` hooks run
+ *  every installed module in `ui.order`, each consuming the previous output. */
+export type HookName = "keyframe" | "motion.backend" | "finish" | "score" | "dialogue" | "speech" | "plan.enhance" | "cast.image" | "notify" | "master" | "film.finish";
+export declare const HOOK_NAMES: readonly HookName[];
+/** Whether a hook resolves to one module or folds every installed module. */
+export declare const HOOK_CARDINALITY: Record<HookName, "pick_one" | "chain">;
+/** One-line description of each hook, for the self-assembling UI. Single source of truth: the
+ *  frontend renders the hook panel from this (served via GET /api/modules), not a hardcoded copy. */
+export declare const HOOK_BLURBS: Record<HookName, string>;
+/** Where a config field's value is sourced from.
+ *  - "render"  (default when omitted): per-render config, chosen at submit time (e.g. quality_tier).
+ *  - "install": operator-set-once, instance-wide config, persisted in the operator-config store and
+ *    injected at invoke time (e.g. notify-email's recipient address). The UI surfaces these on a
+ *    studio settings page, not the per-render panel. ADDITIVE: a field with no `scope` is "render",
+ *    so this marker narrows nothing -- every existing module + vendored /1 contract stays valid. */
+export type ConfigScope = "render" | "install";
+/** One configurable knob a module exposes. The UI renders the control from this; the core clamps
+ *  the user's value against it before invoking. One declaration, one hop, same words down. */
+export type ConfigField = {
+    type: "int" | "float";
+    default: number;
+    min?: number;
+    max?: number;
+    label?: string;
+    enum_labels?: Record<string, string>;
+    scope?: ConfigScope;
+} | {
+    type: "bool";
+    default: boolean;
+    label?: string;
+    scope?: ConfigScope;
+} | {
+    type: "enum";
+    values: string[];
+    default: string;
+    label?: string;
+    scope?: ConfigScope;
+} | {
+    type: "string";
+    default: string;
+    label?: string;
+    scope?: ConfigScope;
+};
+export type ConfigSchema = Record<string, ConfigField>;
+/** A user-facing capability a module offers (a module may offer several). */
+export interface Provides {
+    id: string;
+    label: string;
+}
+/** Hints for the self-assembling studio UI. The honest-framing fields below (locality / cost / blurb /
+ *  limits) are OPTIONAL + additive (NO MODULE_API bump): the planner two-door backend selector (#379)
+ *  reads them and OMITS each when absent (never fabricated). `locality` is the load-bearing one -- it
+ *  drives the door tag AND the core's local-vs-cloud classification (cloudMotionModules /
+ *  gpuDoorMotionModules in the registry; an undeclared locality classifies as cloud), so every
+ *  motion.backend module SHOULD declare it. The rest are display-only (and `limits`, when absent,
+ *  falls back to the module config_schema knob ranges). */
+export interface ModuleUi {
+    section?: string;
+    icon?: string;
+    order?: number;
+    locality?: "local" | "byo" | "cloud";
+    cost?: string;
+    blurb?: string;
+    limits?: string[];
+}
+/** OPTIONAL, additive (no MODULE_API bump, same pattern as `cancelable`): a finish module's declared
+ *  artifact conventions, so the core's R2-authoritative mid-chain recovery (#141/#166) can predict the
+ *  module's output key and reconstruct its `applied` marker from the manifest instead of
+ *  reverse-engineering module internals by binding-name regex. A finish module SHOULD declare this;
+ *  one that does not gets NO R2 shortcut (its GC'd/frozen steps pend to the deadline honestly). */
+export interface FinishArtifactsDecl {
+    /** How the module names its output clip in R2:
+     *  - `shot_named`: `renders/<project>/clips/<shot_id><filename>` (the module names off the shot id;
+     *    e.g. finish-rife's `filename: "_finished.mp4"`).
+     *  - `append_suffix`: insert `suffix` into the INPUT clip key before its extension (the
+     *    append-convention modules; e.g. lip-sync `_ls`, upscale `_up`). */
+    output_key: {
+        kind: "shot_named";
+        filename: string;
+    } | {
+        kind: "append_suffix";
+        suffix: string;
+    };
+    /** Rules reconstructing the `applied` marker from the step's validated config; FIRST match wins.
+     *  `when` (optional) gates a rule on a config knob equaling a literal; `tag` is a template where
+     *  `{knob}` reads the knob and `{knob|default}` supplies the value when the knob is absent
+     *  (e.g. `"lipsync:{version|v15}"`, `"interpolate:{interpolation_factor|2}x"`). No rules / no
+     *  match -> the core marks the adopted step `<binding>:r2-adopted` so the adoption is never silent. */
+    applied?: Array<{
+        when?: {
+            knob: string;
+            equals: string | number | boolean;
+        };
+        tag: string;
+    }>;
+}
+/** A module's self-description, served at GET /module.json. */
+export interface ModuleManifest {
+    name: string;
+    version: string;
+    api: ModuleApi;
+    hooks: HookName[];
+    provides?: Provides[];
+    config_schema?: ConfigSchema;
+    ui?: ModuleUi;
+    /** Async modules SHOULD set this true and implement POST /cancel so the core can STOP an in-flight
+     *  job (cancel a render, recover an adopted keyframe phase) instead of orphaning GPU. OPTIONAL and
+     *  additive (no MODULE_API bump, same as the #318 jobId field). Absent/false => the core cannot
+     *  cancel this module's jobs and will HONESTLY degrade-log any orphan rather than hide it. */
+    cancelable?: boolean;
+    /** Finish modules SHOULD declare their artifact conventions (see FinishArtifactsDecl) so the core's
+     *  R2-authoritative recovery works from the manifest, not from binding-name pattern-matching. */
+    finish_artifacts?: FinishArtifactsDecl;
+    /** OPTIONAL, additive (no MODULE_API bump, same pattern as `cancelable`). A keyframe module's
+     *  compact display token for the keyframe-stage backend/model (e.g. "SDXL"), which the planner UI
+     *  projects inline instead of hardcoding a model name. Distinct from provides[].label, which is
+     *  the section-title-length label ("GPU Keyframe (SDXL on RunPod)"); this is the short inline noun. */
+    keyframe_label?: string;
+    /** OPTIONAL, additive (no MODULE_API bump, same pattern as `cancelable`). A finish module sets this
+     *  true when it drives its output from the shot dialogue audio (`FinishInput.audio_key`), i.e. it
+     *  lip-syncs. It carries TWO facts the core needs: (a) this finish step CONSUMES the shot dialogue
+     *  audio, and (b) it MUST therefore run on the NATIVE-fps clip, before any finish step that resamples
+     *  time (interpolation). A lip-sync model maps audio to mouth shapes calibrated to the source frame
+     *  rate, so lip-syncing already-interpolated footage smears the mouth shapes across the doubled
+     *  frames (vivijure #584). The core uses this to run audio-consuming finish modules FIRST in the
+     *  chain for a shot that HAS a dialogue line, preserving `ui.order` among the rest; a shot with no
+     *  line keeps the plain `ui.order` (such a module no-ops there, having no `audio_key`). Absent/false
+     *  means ordered purely by `ui.order` (the legacy behavior). The module declares only its OWN nature;
+     *  the cross-module ordering policy stays in the core. */
+    finish_consumes_audio?: boolean;
+    /** OPTIONAL, additive (no MODULE_API bump, same pattern as `cancelable`). A motion.backend module
+     *  whose engine renders on a FIXED duration grid (pinned fps + per-tier frame caps, e.g. CogVideoX:
+     *  8fps, draft <= 25 frames) declares the grid so the core can warn AT STORYBOARD TIME that a shot's
+     *  planned seconds will be clamped, instead of the clamp staying silent until the clip lands (#707).
+     *  The module RELAYS what its backend declares (best-effort; e.g. from the backend's /health);
+     *  ABSENT means no declared constraint -- the module must never fabricate a grid. Tier keys match
+     *  the render quality tiers the module accepts (e.g. draft/standard/final). */
+    duration_grid?: DurationGridDecl;
+}
+/** A fixed duration grid for a motion backend (#707): the pinned output fps and the per-quality-tier
+ *  frame ceilings. A tier's maximum deliverable seconds = max_frames / fps. */
+export interface DurationGridDecl {
+    fps: number;
+    tiers: Record<string, {
+        max_frames: number;
+    }>;
+}
+/** Per-job context the core passes to every invoke (never secrets). */
+export interface InvokeContext {
+    project: string;
+    job_id: string;
+}
+/** The single entry point the core calls on a module: POST /invoke. */
+export interface InvokeRequest<I = unknown> {
+    hook: HookName;
+    input: I;
+    config: Record<string, unknown>;
+    context: InvokeContext;
+}
+/** A module failure is data, never an exception across the wire: the core degrades, it does not
+ *  crash, when a module returns `ok: false`. */
+export type InvokeResponse<O = unknown> = {
+    ok: true;
+    output: O;
+} | {
+    ok: true;
+    pending: true;
+    poll: string;
+    jobId?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Body POSTed to a long-running module's `/poll` to check an async job. */
+export interface PollRequest {
+    poll: string;
+}
+/** A module's `/poll` response: still running, finished, or failed. The caller polls until it is no
+ *  longer pending, so a Worker never holds one long-running `/invoke` request open. */
+export type PollResponse<O = unknown> = {
+    ok: true;
+    pending: true;
+} | {
+    ok: true;
+    output: O;
+} | {
+    ok: false;
+    error: string;
+};
+/** Body POSTed to a long-running module's `/cancel` to STOP an in-flight async job. The token is the
+ *  same one `/invoke` returned (and `/poll` consumes); the module decodes it to ITS backend job id and
+ *  cancels with ITS OWN backend creds, because the core never holds them. This is the contract's only
+ *  honest way to stop GPU work: without it, a cancelled render or an adopted keyframe phase orphans the
+ *  job and bleeds money after the work it was for is already satisfied (#327 / #328). */
+export interface CancelRequest {
+    poll: string;
+}
+/** A module's `/cancel` response. BEST-EFFORT + idempotent: cancelling an already-terminal or unknown
+ *  job is a success (`ok: true`), so the core can read `ok: true` as "this job will not keep running on
+ *  our account". A module that cannot cancel returns `ok: false` with a reason, and the core
+ *  degrade-LOGS the orphan rather than hiding it (a silent orphan is the bug). */
+export type CancelResponse = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** What the core hands a `finish` module: a rendered clip and what is known about it. The clip is
+ *  self-describing (a finish backend probes it), so the shape hints below are OPTIONAL -- the core
+ *  passes them when it has them, but a finish module must not require them. */
+export interface FinishInput {
+    shot_id: string;
+    clip_key: string;
+    audio_key?: string;
+    src_fps?: number;
+    frames?: number;
+    width?: number;
+    height?: number;
+    output_hash?: string;
+}
+/** What a `finish` module returns: the processed clip plus what it did. Duration is invariant
+ *  (interpolation changes fps + frame count, never length). */
+export interface FinishOutput {
+    shot_id: string;
+    clip_key: string;
+    out_fps: number;
+    frames: number;
+    applied: string[];
+    degraded?: string;
+}
+/** One spoken line for one shot. `voice_id` is resolved by the core (slot -> cast member -> voice),
+ *  so the module just synthesizes; absent/unknown falls back to a default speaker at synth time. */
+export interface DialogueLine {
+    shot_id: string;
+    text: string;
+    voice_id?: string;
+}
+/** What the core hands a `dialogue` module: every speaking shot in ONE batch (so a film's dialogue is
+ *  a single submit+poll, not N round-trips). `project` is the R2 key prefix the audio lands under. */
+export interface DialogueInput {
+    project: string;
+    lines: DialogueLine[];
+}
+/** One synthesized line: the R2 key of its audio and the voice actually used. The core attaches
+ *  `audio_key` to that shot's FinishInput so a lip-sync finish module can drive the mouth from it. */
+export interface DialogueShotAudio {
+    shot_id: string;
+    audio_key: string;
+    voice_id: string;
+}
+export interface DialogueOutput {
+    project: string;
+    audio: DialogueShotAudio[];
+    applied: string[];
+}
+/** What the core hands a `speech` module: ONE shot's dialogue audio to enhance / clean. The audio is
+ *  self-describing (a speech backend probes it), so this is deliberately minimal. The speech chain runs
+ *  AFTER the dialogue phase (the audio exists) and BEFORE finish (so a lip-sync finish module drives the
+ *  mouth from the cleaned audio). */
+export interface SpeechInput {
+    shot_id: string;
+    audio_key: string;
+}
+/** What a `speech` module returns: the (maybe enhanced) dialogue audio plus what it did. On a real
+ *  enhancement `audio_key` is the NEW cleaned key; on an honest soft-degrade it is the input key passed
+ *  through unchanged, `applied` carries no fake tag, and `degraded` carries the reason. A speech step is
+ *  a POLISH step: it NEVER fails the render on a miss -- only malformed I/O fails loud (cf #249/#77). */
+export interface SpeechOutput {
+    shot_id: string;
+    audio_key: string;
+    applied: string[];
+    degraded?: string;
+}
+/** What the core hands a `plan.enhance` module: the storyboard to enrich (its scenes carry the shot
+ *  prompts the module rewrites) plus the original brief for context. Structural passthrough -- a
+ *  module rewrites scenes[].prompt and preserves every other field on the storyboard and scenes. */
+export interface PlanEnhanceScene {
+    prompt: string;
+    [k: string]: unknown;
+}
+export interface PlanEnhanceStoryboard {
+    scenes: PlanEnhanceScene[];
+    [k: string]: unknown;
+}
+export interface PlanEnhanceInput {
+    storyboard: PlanEnhanceStoryboard;
+    brief?: string;
+}
+/** What a `plan.enhance` module returns: the enriched storyboard plus optional human-readable notes
+ *  on what it did (or why it passed through unchanged). */
+export interface PlanEnhanceOutput {
+    storyboard: PlanEnhanceStoryboard;
+    notes?: string[];
+}
+/** What the core hands a `keyframe` module: a project bundle to render START keyframes from. This
+ *  is a PROJECT-level pass, not per-shot -- the GPU backend trains/reuses cast LoRAs once and emits
+ *  every shot's keyframe in one job. A per-shot module would re-submit (and risk re-training the
+ *  LoRA) on every shot = GPU waste; the project pass keeps GPU spend to genuinely GPU-bound work.
+ *  The clip orchestrator (motion.backend) then animates each keyframe per shot. */
+export interface KeyframeInput {
+    project: string;
+    bundle_key: string;
+    shot_ids?: string[];
+    /** slot -> R2 key of pretrained cast LoRAs; scatter shards reuse adapters trained once up front. */
+    pretrained_loras?: Record<string, string>;
+}
+/** One generated start keyframe, already stored in R2 by the backend. */
+export interface KeyframeShot {
+    shot_id: string;
+    keyframe_key: string;
+}
+/** What a `keyframe` module returns: every keyframe it generated, by shot. The core presigns each
+ *  key into a fetchable keyframe_url when it hands them on to the motion.backend orchestrator. */
+export interface KeyframeOutput {
+    project: string;
+    keyframes: KeyframeShot[];
+    /** slot -> R2 key of the cast LoRA this render trained or reused. The core records a freshly
+     *  trained adapter back onto the cast member (lora_status=ready) so it is reused across every
+     *  project instead of retrained each render. Optional + additive: a module that does no LoRA
+     *  work omits it. */
+    trained_loras?: Record<string, string>;
+}
+/** What the core hands a `motion.backend` module for ONE shot: a start keyframe and the motion
+ *  intent. The module turns it into a clip (on GPU or via a cloud i2v API). */
+export interface MotionBackendInput {
+    shot_id: string;
+    keyframe_url: string;
+    keyframe_key?: string;
+    prompt: string;
+    seconds: number;
+}
+/** What a `motion.backend` module returns: the rendered shot clip. */
+export interface MotionBackendOutput {
+    shot_id: string;
+    clip_key: string;
+    fps: number;
+    frames: number;
+    /** OPTIONAL, additive (no MODULE_API bump): tier-honesty signal from the backend -- true when the
+     *  clip was rendered with a DISTILLED variant of the model (e.g. the 12gb door's final-tier 13B
+     *  distilled), false when the full model ran. The module relays what its backend reports and OMITS
+     *  the field when the backend says nothing (#705); the core retains it per shot and surfaces it on
+     *  the film summary's clip_deliveries. Absence is honest, never a fabricated false. */
+    distilled?: boolean;
+}
+/** What the core hands a `score` module: the assembled (silent) film and its shape, plus optional
+ *  storyboard context for mood/tempo. */
+export interface ScoreInput {
+    film_key: string;
+    seconds: number;
+    storyboard?: PlanEnhanceStoryboard;
+}
+/** What a `score` module returns: the film with audio applied (or muxed), and what it added. */
+export interface ScoreOutput {
+    film_key: string;
+    applied: string[];
+    degraded?: string;
+}
+/** What the core hands a `cast.image` module: one cast member's seed material to generate LoRA
+ *  TRAINING reference images from -- a portrait (the identity seed), optional human-uploaded source
+ *  photos for extra conditioning, and the bible/style that shape the prompts. A CAST-PREP pass,
+ *  upstream of keyframe: the generated images become the cast member's training refs. The portrait /
+ *  source URLs are presigned + fetchable (the core presigns the private R2 objects so a cloud image
+ *  model can pull them), mirroring how motion.backend gets keyframe_url. */
+export interface CastImageInput {
+    cast_id: number;
+    portrait_url: string;
+    portrait_key?: string;
+    source_urls?: string[];
+    bible?: string;
+    art_style?: string;
+}
+/** What a `cast.image` module returns: the generated training reference images (already stored in
+ *  R2), ready to feed LoRA training, plus what it did. The core appends these to the cast member's
+ *  ref set. */
+export interface CastImageOutput {
+    cast_id: number;
+    images: {
+        key: string;
+        mime: string;
+    }[];
+    applied: string[];
+}
+/** What the core hands a `notify` module when a film reaches "done": the completion event + the facts
+ *  a notifier needs to deliver (a presigned download_url, the project name, the owner address). A
+ *  TERMINAL side-effect hook -- fired once on the done-transition, `chain` (every installed notifier
+ *  delivers independently: email AND webhook AND ...). A notifier with nothing to do for its channel
+ *  (e.g. no recipient address) returns an empty `delivered`, never an error. */
+export interface NotifyInput {
+    event: "render.complete";
+    film_id: string;
+    project: string;
+    download_url?: string;
+    seconds?: number;
+}
+/** What a `notify` module returns: the channels it delivered on (for the core's log / summary). */
+export interface NotifyOutput {
+    delivered: string[];
+}
+/** What the core hands a `master` module: the assembled film's AUDIO BED (the mixed score / narration
+ *  track), to polish at FILM level before the final mux. This is the audio sibling of `finish` (which
+ *  polishes a clip) and the dialogue/`speech` lane (which polishes per-shot voice): `master` operates
+ *  once, on the whole film's audio, AFTER the mix is built (score + narration) and BEFORE the audio is
+ *  muxed onto the silent film. `audio_key` is the R2 key of that bed; the core presigns a GET of it
+ *  (`audio_url`) and a PUT for the mastered output (`output_url` / `output_key`) so the module stays
+ *  CREDENTIALLESS and forwards them to its CPU container -- exactly as the subtitle / film.finish modules
+ *  get a presigned video_url + output_url. A music-video maker reaches for `master` as cleanly as a
+ *  dialogue maker reaches for the voice lane. */
+export interface MasterInput {
+    film_id: string;
+    audio_key: string;
+    audio_url: string;
+    output_url: string;
+    output_key: string;
+    seconds?: number;
+}
+/** What a `master` module returns: the mastered audio bed plus what it did. Length is invariant
+ *  (mastering changes level / sample rate, never duration). HONEST soft-degrade, exactly as a `finish`
+ *  module: when the master cannot run (misconfig / backend down) the module passes the INPUT bed
+ *  through (`audio_key` unchanged) and sets `degraded` with the reason -- never a fake `applied` tag,
+ *  never a dropped bed. A real degrade is therefore never silent (#249 / #77). */
+export interface MasterOutput {
+    audio_key: string;
+    applied: string[];
+    degraded?: string;
+}
+/** One time-synced caption cue handed to a `film.finish` subtitle module, in seconds from the
+ *  assembled film's 0-based start. Structurally mirrors src/captions.ts CaptionCue; declared here so
+ *  the contract stays self-contained -- a module in another repo vendoring this file gets the caption
+ *  shape too, without importing a core-only module. */
+export interface FilmFinishCaption {
+    start: number;
+    end: number;
+    text: string;
+}
+/** What the core hands a `film.finish` module: the assembled+muxed film to put title / credit cards
+ *  (and/or burned-or-sidecar subtitles) on, by R2 transport. The module reads `video_url` (a presigned
+ *  GET of the input film) and writes its result to `output_url` (a presigned PUT at `output_key`),
+ *  exactly as a finish backend reads/writes a clip. `title` / `credits` carry the card text (absent =>
+ *  no cards, the module passes the film through); `captions` carries the time-synced dialogue cues for a
+ *  subtitle module (empty => it no-ops); `sidecar_url` / `sidecar_key` are a presigned PUT for an
+ *  optional .srt sidecar. This runs POST-mux, before done, as a `chain`: every installed film.finish
+ *  module folds in `ui.order`, and the core presigns a FRESH GET (of the PRIOR step's film) + PUT (to a
+ *  new key) per step, so step N+1 reads what step N wrote rather than the original (#14). */
+export interface FilmFinishInput {
+    film_key: string;
+    video_url: string;
+    output_url: string;
+    output_key: string;
+    title?: {
+        text: string;
+        subtitle?: string;
+    };
+    credits?: {
+        lines: string[];
+    };
+    captions: FilmFinishCaption[];
+    sidecar_url: string;
+    sidecar_key: string;
+}
+/** What a `film.finish` module returns: the (maybe new) film key plus what it did. The chain is
+ *  FAIL-SAFE -- a module that cannot run passes the film through with `film_key` UNCHANGED (the input
+ *  film key, never omitted) and reports it via the soft-degrade convention, never dropping a
+ *  fully-rendered film (#190). `applied` carries the module name on success, or a "passthrough:<reason>"
+ *  / "noop:no-cards" tag on a soft-degrade; `degraded` (the shared chain convention, as on FinishOutput
+ *  / MasterOutput / SpeechOutput) is set ONLY when the film shipped UNCARDED, carrying the reason -- the
+ *  one signal that requested cards were NOT applied (#207). The core records the chain outcome on the
+ *  job rather than dropping it. */
+export interface FilmFinishOutput {
+    film_key: string;
+    applied?: string[];
+    degraded?: string;
+    prepend_seconds?: number;
+}
+/** One registered module, INTERNAL to the core: the manifest plus a `binding` REF telling the core how
+ *  to reach it. The ref is transport-encoded (resolved by registry.resolveFetcher):
+ *   - `MODULE_<NAME>` -> a service binding on env (the legacy, in-tree, deploy-wired path), or
+ *   - `dispatch:<script>` -> a user-Worker script uploaded into the Workers-for-Platforms dispatch
+ *     namespace, reached via env.MODULE_DISPATCH.get(<script>) at request time (installed without a core
+ *     redeploy; see docs/module-dispatch.md). The `dispatch:` prefix cannot collide with a real
+ *     `MODULE_*` env key, so a single string persists a module's transport through job state and both
+ *     kinds re-resolve uniformly across requests.
+ *  The ref is internal topology and NEVER leaves the core -- toPublic strips it (see PublicModule). */
+export interface RegisteredModule extends ModuleManifest {
+    binding: string;
+}
+/** One registered module as the core exposes it to the frontend over GET /api/modules: the manifest
+ *  ONLY, with the internal `binding` ref stripped. The unauthenticated registry route must not leak
+ *  which env binding OR namespace script serves a hook (internal module-host topology); the studio UI
+ *  never needs it -- it renders from the manifest, and the core resolves the transport itself. (Info
+ *  disclosure, #18.) */
+export type PublicModule = ModuleManifest;
+/** One hook in the catalog the frontend renders the pipeline panel from, so the panel is a
+ *  projection of the contract rather than a hardcoded list. */
+export interface HookCatalogEntry {
+    name: HookName;
+    blurb: string;
+    cardinality: "pick_one" | "chain";
+}
+/** Core-owned render config the frontend projects (so the planner stops hand-authoring it in markup).
+ *  Distinct from module config_schema: these are cross-cutting choices the HOST owns (e.g. the quality
+ *  tier the core injects into the keyframe + motion modules), not knobs a single module declares.
+ *  Sourced from the one core constant (QUALITY_TIERS / DEFAULT_QUALITY_TIER in render-module-config). */
+export interface RenderConfigProjection {
+    quality_tiers: {
+        value: string;
+        label: string;
+        blurb: string;
+    }[];
+    default_tier: string;
+}
+/** GET /api/modules: the merged registry the studio UI renders itself from. Carries the PUBLIC
+ *  module view (no internal `binding`); the hook index maps each hook to the module NAMES serving
+ *  it, so the frontend has everything it needs to project the pipeline without seeing topology. */
+export interface ModulesResponse {
+    api: ModuleApi;
+    modules: PublicModule[];
+    hooks: Partial<Record<HookName, string[]>>;
+    catalog: HookCatalogEntry[];
+    render: RenderConfigProjection;
+    /** What TRANSPORTS this host offers, the CORE describing ITSELF -- orthogonal to `api` (which is the
+     *  module contract version, unchanged by dispatch). `dispatch: true` means this deployment speaks
+     *  Workers-for-Platforms dynamic dispatch (a module can be installed without a core redeploy).
+     *  `readonly: true` (#625) means this deployment accepts no mutations (the public demo studio,
+     *  AUTH_MODE=demo): the frontend disables mutation affordances off this ONE projected capability
+     *  instead of growing per-feature demo branches; omitted everywhere else. A module never reads
+     *  this; an operator / the studio UI / a health probe does. OPTIONAL + additive:
+     *  a deploy without WfP omits it, and NO MODULE_API bump (docs/module-dispatch.md section 5.3). */
+    host?: {
+        dispatch: boolean;
+        readonly?: boolean;
+        render?: {
+            available: boolean;
+        };
+        assistant?: {
+            model: string;
+            note: string;
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/modules/types.ts"],"names":[],"mappings":"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"}

package/dist/modules/types.js

@@ -0,0 +1,57 @@
+// The Vivijure module contract (vivijure-module/2).
+//
+// This is the typed boundary between the studio CORE and the opt-in MODULE workers that plug into
+// it. The core invokes hooks; it does not know who answers. A module declares which hooks it serves
+// (its manifest) and implements one invoke entry point. See docs/module-api.md for the full design.
+//
+// Keep this file dependency-free: it is the shared shape both the core and every module import, so
+// it must stay portable (a module in another repo vendors this exact contract).
+/** The contract version a module targets. Bumped only on a breaking change to these shapes. */
+export const MODULE_API = "vivijure-module/2";
+// A SET of currently-supported contract epochs, not a brittle exact-match. The /1 deprecation
+// window from #293 is CLOSED (#294): every first-party module is /2 and /1 manifests are rejected.
+// The ModuleApi union above keeps /1 nameable as a historical epoch; this Set is the policy.
+export const SUPPORTED_MODULE_APIS = new Set(["vivijure-module/2"]);
+export const HOOK_NAMES = [
+    "keyframe",
+    "motion.backend",
+    "finish",
+    "score",
+    "dialogue",
+    "speech",
+    "plan.enhance",
+    "cast.image",
+    "notify",
+    "master",
+    "film.finish",
+];
+/** Whether a hook resolves to one module or folds every installed module. */
+export const HOOK_CARDINALITY = {
+    keyframe: "pick_one",
+    "motion.backend": "pick_one",
+    finish: "chain",
+    score: "chain",
+    dialogue: "pick_one",
+    speech: "chain",
+    "plan.enhance": "chain",
+    "cast.image": "pick_one",
+    notify: "chain",
+    master: "chain",
+    "film.finish": "chain",
+};
+/** One-line description of each hook, for the self-assembling UI. Single source of truth: the
+ *  frontend renders the hook panel from this (served via GET /api/modules), not a hardcoded copy. */
+export const HOOK_BLURBS = {
+    keyframe: "storyboard -> start keyframes (SDXL)",
+    "motion.backend": "keyframe -> shot clip (GPU or cloud)",
+    finish: "interpolation / upscale / face restore",
+    score: "music / narration / beat-sync",
+    dialogue: "spoken lines -> per-character voice (TTS)",
+    speech: "clean / enhance dialogue audio",
+    "plan.enhance": "LLM auto-direction",
+    "cast.image": "character refs from a portrait + bible",
+    notify: "render-complete notification (email / webhook)",
+    master: "film-level audio mastering: music upscale + loudness",
+    "film.finish": "title / credit cards on the finished film",
+};
+//# sourceMappingURL=types.js.map

package/dist/modules/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/modules/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,oGAAoG;AACpG,EAAE;AACF,mGAAmG;AACnG,gFAAgF;AAEhF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,UAAU,GAAG,mBAA4B,CAAC;AAOvD,8FAA8F;AAC9F,mGAAmG;AACnG,6FAA6F;AAC7F,MAAM,CAAC,MAAM,qBAAqB,GAA2B,IAAI,GAAG,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;AAiB5F,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C,UAAU;IACV,gBAAgB;IAChB,QAAQ;IACR,OAAO;IACP,UAAU;IACV,QAAQ;IACR,cAAc;IACd,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,aAAa;CACd,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAA2C;IACtE,QAAQ,EAAE,UAAU;IACpB,gBAAgB,EAAE,UAAU;IAC5B,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,OAAO;IACf,cAAc,EAAE,OAAO;IACvB,YAAY,EAAE,UAAU;IACxB,MAAM,EAAE,OAAO;IACf,MAAM,EAAE,OAAO;IACf,aAAa,EAAE,OAAO;CACvB,CAAC;AAEF;qGACqG;AACrG,MAAM,CAAC,MAAM,WAAW,GAA6B;IACnD,QAAQ,EAAE,sCAAsC;IAChD,gBAAgB,EAAE,sCAAsC;IACxD,MAAM,EAAE,wCAAwC;IAChD,KAAK,EAAE,+BAA+B;IACtC,QAAQ,EAAE,2CAA2C;IACrD,MAAM,EAAE,gCAAgC;IACxC,cAAc,EAAE,oBAAoB;IACpC,YAAY,EAAE,wCAAwC;IACtD,MAAM,EAAE,gDAAgD;IACxD,MAAM,EAAE,sDAAsD;IAC9D,aAAa,EAAE,2CAA2C;CAC3D,CAAC"}

package/dist/operator-config.d.ts

@@ -0,0 +1,20 @@
+import type { Env } from "./platform/orchestrator-context.js";
+import type { ConfigSchema } from "./modules/types.js";
+/** Project a module's config_schema down to ONLY its install-scope fields. A field with no `scope`
+ *  (or scope "render") is a per-render knob and is excluded -- so this store never owns render config. */
+export declare function installSubschema(schema: ConfigSchema | undefined): ConfigSchema;
+/** Does this module expose any install-scope config at all? */
+export declare function hasInstallConfig(schema: ConfigSchema | undefined): boolean;
+/** The set of writable install field keys for a module (what PATCH is allowed to set). */
+export declare function installFieldKeys(schema: ConfigSchema | undefined): string[];
+/** Clamp an incoming patch to the module's install subschema, dropping unknown / render-scope keys.
+ *  Reuses the SAME validateConfig clamp the invoke path uses, so a stored value can never violate the
+ *  contract. Returns the full install-config (every install field, missing ones at their default). */
+export declare function clampInstallPatch(schema: ConfigSchema | undefined, current: Record<string, unknown>, patch: Record<string, unknown> | undefined): Record<string, unknown>;
+/** The module's install-config as the INVOKE path consumes it: every install field present, missing
+ *  ones at their schema default, clamped to the contract. Empty schema -> {} (a clean no-op). */
+export declare function loadInstallConfig(env: Env, moduleName: string, schema: ConfigSchema | undefined): Promise<Record<string, unknown>>;
+/** Persist an operator PATCH: clamp to the install subschema (unknown / render keys dropped), then
+ *  upsert each field. Returns the resulting full install-config view. */
+export declare function setInstallConfig(env: Env, moduleName: string, schema: ConfigSchema | undefined, patch: Record<string, unknown> | undefined): Promise<Record<string, unknown>>;
+//# sourceMappingURL=operator-config.d.ts.map

package/dist/operator-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-config.d.ts","sourceRoot":"","sources":["../src/operator-config.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oCAAoC,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;0GAC0G;AAC1G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,CAO/E;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAE1E;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,EAAE,CAE3E;AAED;;sGAEsG;AACtG,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAuBD;iGACiG;AACjG,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,GAAG,EACR,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GAAG,SAAS,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKlC;AAED;yEACyE;AACzE,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,GAAG,EACR,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgBlC"}