@melite/models-music3 0.1.5-pre-alpha → 0.2.2-alpha

package/README.md

@@ -1,8 +1,3 @@
----
-description: MiniMax Music 3 text-to-music — caption and lyrics conditioning over INT8 ConvRot weights, mp3 output under the run directory.
-kind: package-library
----
-
 # music3
 
 music3 registers the MiniMax Music 3 family (form `form_music`, label "MiniMax Music 3", genre `audio`, engine `comfyui`): text-to-music with lyrics. Weights: three INT8 ConvRot provisions from Comfy-Org/MiniMax-Music-3 — the DiT (`minimax_music3_dit_int8_convrot.safetensors`, about 2.5 GB), the pruned text encoder (about 9.2 GB), and the DAV VAE (about 0.22 GB). The `lane_inputs` pin `clip_type: minimax` and the three file names.

package/lib/actions.js

@@ -1,4 +1,6 @@
 import { requireText } from "@melite/comfyui-card-kit/facts";
+import { assertMusic3StepsInTier, music3StepTier } from "./tier.js";
+import { TILED_DECODE_SEATS, deriveDecodeTier } from "./decode.js";
 /** The compose facts door: the resolved lane_inputs parsed into the
  * closed shape — a missing weight refuses field-named here, never
  * composes with an empty filename.
@@ -27,10 +29,43 @@ export const compose = {
         { name: "lm_cfg_scale", type: "number", bounds: [0.1, 10] },
         { name: "n_diffusion_steps", type: "number", bounds: [1, 200] },
         { name: "seed", type: "number", rule: "seed-sentinel" },
+        // THE DECODE TIER KNOB (audit 014 C3): NO default row — absence
+        // IS the derivation's seat. A stamped literal here would be the
+        // second default home the seed cure died killing; the derivation
+        // (decode.ts deriveDecodeTier) owns the unstated compose.
+        { name: "tiled_decode", type: "boolean" },
     ],
     facts: parseMusicFacts,
-    build({ p, facts, g, runId }) {
+    build({ p, facts, model, g, runId }) {
+        
+        // YuE2 ABC-planning vocabulary (card.ts mode tooltip; the YuE2
+        // nodes read it) — the MiniMax lane plans no symbolic score and
+        // MiniMaxMusic3TextEncode declares no mode input (the engine
+        // node's schema: clip, caption, lyrics, seed, max_duration,
+        
+        // every gate and die unread at compose — the silent drop the
+        // value arms pre-registered. Refuse loud in the knob's own
+        // voice; "full" rides because the card schema's walk fills it as
+        // the stated default (the stated default IS the unstated
+        // compose), and an absent mode (direct action callers) rides.
+        const mode = p.mode;
+        if (mode !== undefined && mode !== "full") {
+            throw new Error(`music3 compose: mode '${String(mode)}' fires nothing on this lane — ` +
+                "mode is the YuE2 ABC-planning vocabulary (full/melody drive YuE2's symbolic score); " +
+                "the MiniMax lane's engine node reads caption+lyrics only, no mode input. " +
+                "Drop mode, or switch lane (model=yue2) to plan a score");
+        }
         const seed = p.seed;
+        // THE STEP↔CHECKPOINT TIER (audit 014 C4): the steps and the
+        // checkpoint share ONE derivation — the resolved unet derives the
+        // tier, a stated steps must sit inside its domain (outside
+        // refuses loud, naming the pairing), and an unstated steps rides
+        // the tier's own default. The card schema's served default is the
+        // full tier's default (one home, tier.ts).
+        const statedSteps = p.n_diffusion_steps;
+        const steps = typeof statedSteps === "number"
+            ? (assertMusic3StepsInTier(facts.unet, statedSteps), statedSteps)
+            : music3StepTier(facts.unet).default;
         const unet = g.node("UNETLoader", { unet_name: facts.unet, weight_dtype: "default" }).out();
         const clip = g.node("CLIPLoader", { clip_name: facts.text_encoder, model_options: "default", type: facts.clip_type }).out();
         const vae = g.node("VAELoader", { vae_name: facts.vae }).out();
@@ -44,10 +79,17 @@ export const compose = {
             top_k: 50,
         });
         const zeroed = g.node("ConditioningZeroOut", { conditioning: cond.out(0) });
-        const latent = g.node("EmptyMiniMaxMusic3LatentAudio", { batch_size: 1, seconds: p.duration });
+        // The latent's length is DERIVED from the AR, never addressed twice: slot 1
+        // of MiniMaxMusic3TextEncode is the realized AR length in seconds, and the
+        // official template wires exactly this link. Stamping the duration literal
+        // here lets the seats diverge when the AR ends the song early — the DiT
+        // zero-pads the conditioning (dit.py:197-198) and the latent tail generates
+        // unconditioned noise (audit 014, D1). max_duration above is the user's
+        // only duration seat.
+        const latent = g.node("EmptyMiniMaxMusic3LatentAudio", { batch_size: 1, seconds: cond.out(1) });
         const sampled = g.node("KSampler", {
             seed,
-            steps: p.n_diffusion_steps,
+            steps,
             cfg: p.guidance_scale,
             sampler_name: "euler",
             scheduler: "simple",
@@ -57,8 +99,48 @@ export const compose = {
             positive: cond.out(0),
             negative: zeroed.out(),
         });
-        const audio = g.node("VAEDecodeAudio", { samples: sampled.out(), vae });
+        // THE VRAM-AWARE DECODE TIER (audit 014 C3): the strategy derives
+        // from the lane's own signal — the resolved variant cell's
+        // DECL-declared vram_peak_gb (the resolver's coordinate law: the
+        // address's own cell claim, else the matrix's default cell) and
+        // the track's duration cap. A stated knob overrides; absent, the
+        // derivation decides. The tiled seats are the template's own
+        // (1536/64).
+        const decodeTier = p.tiled_decode === undefined
+            ? deriveDecodeTier(resolvedCellVramPeakGb(model), typeof p.duration === "number" ? p.duration : 0)
+            : p.tiled_decode
+                ? "tiled"
+                : "plain";
+        const audio = decodeTier === "tiled"
+            ? g.node("VAEDecodeAudioTiled", { samples: sampled.out(), vae, ...TILED_DECODE_SEATS })
+            : g.node("VAEDecodeAudio", { samples: sampled.out(), vae });
         return g.node("SaveAudioAdvanced", { audio: audio.out(), filename_prefix: `${runId}/music`, format: "mp3", "format.quality": "V0" }).out();
     },
 };
+/** The resolved variant cell's DECL-declared VRAM peak — the mirror
+ *  of the resolver's own coordinate law (resolveCellRow: the
+ *  address's own cell claim wins, else the first offered cell of the
+ *  first offered Variant row). Reads the facts row the action build
+ *  receives; a matrix-less facts row (hand fixtures) reads null —
+ *  unmeasured, never called low-VRAM.
+ *  @param model the resolved model facts row (id, family, variants)
+ *  @returns the resolved cell's declared peak, or null */
+function resolvedCellVramPeakGb(model) {
+    const rows = model.variants ?? [];
+    const address = model.id;
+    for (const v of rows) {
+        for (const c of v.cells ?? []) {
+            if (c.route === address)
+                return c.vram_peak_gb;
+        }
+    }
+    for (const v of rows) {
+        if (v.group !== "Variant" || v.hide_from_dropdown === true)
+            continue;
+        const cell = (v.cells ?? []).find((c) => c.hide_from_dropdown !== true);
+        if (cell !== undefined)
+            return cell.vram_peak_gb;
+    }
+    return null;
+}
 //# sourceMappingURL=actions.js.map

package/lib/decode.d.ts

@@ -0,0 +1,28 @@
+/** The VRAM floor under which a cell's declared peak tiles the
+ *  decode. The audit's box cut: a lane whose DECL-declared peak sits
+ *  at or above the floor decodes plain. */
+export declare const TILED_VRAM_FLOOR_GB = 16;
+/** The track length past which the decode tiles regardless of the
+ *  declared peak — VAE decode memory scales with the latent's
+ *  length, and the AR's duration cap is the compose-time size
+ *  signal (the realized length is the AR's own output, unknowable
+ *  here). */
+export declare const TILED_DURATION_CEIL_S = 90;
+/** The closed decode vocabulary. */
+export type DecodeTier = "plain" | "tiled";
+/** Derive the decode tier from the lane's VRAM/size signal.
+ *  @param vramPeakGb the resolved cell's DECL-declared peak (null =
+ *   unmeasured — an unmeasured body is never called low-VRAM; the
+ *   audition-gated peak class, ROADMAP)
+ *  @param seconds the track's duration cap (the size signal)
+ *  @returns "tiled" past the size ceiling or under the VRAM floor,
+ *   "plain" otherwise */
+export declare function deriveDecodeTier(vramPeakGb: number | null, seconds: number): DecodeTier;
+/** The tiled decode's segment seats, verbatim from the official
+ *  template's VAEDecodeAudioTiled (tile 1536, overlap 64 — inside
+ *  the engine's declared [32, 8192]/[0, 1024] bounds). */
+export declare const TILED_DECODE_SEATS: {
+    readonly tile_size: 1536;
+    readonly overlap: 64;
+};
+//# sourceMappingURL=decode.d.ts.map

package/lib/decode.js

@@ -0,0 +1,41 @@
+// decode.ts — THE VRAM-AWARE DECODE TIER (audit 014 C3): the audio
+// decode strategy derives from the lane's own VRAM/size signal, never
+// a fixed literal. The official template composes tiled decode with
+// a hardcoded true; its own model note seats int8_convrot as the
+// low-VRAM body — the quality-correct choice on a roomy box is the
+// plain decode, and the tier flips on the DECL's own numbers: a
+// low-VRAM cell (its declared vram_peak_gb under the floor) or a
+// long track (the AR's duration cap past the ceiling) tiles; a
+// measured-roomy cell at a short track decodes plain. An explicitly
+// stated knob overrides the derivation at the action (the flip needs
+// no re-compose of the lane); absent, the derivation decides — the
+// default lives HERE, once, never a second stamped literal.
+/** The VRAM floor under which a cell's declared peak tiles the
+ *  decode. The audit's box cut: a lane whose DECL-declared peak sits
+ *  at or above the floor decodes plain. */
+export const TILED_VRAM_FLOOR_GB = 16;
+/** The track length past which the decode tiles regardless of the
+ *  declared peak — VAE decode memory scales with the latent's
+ *  length, and the AR's duration cap is the compose-time size
+ *  signal (the realized length is the AR's own output, unknowable
+ *  here). */
+export const TILED_DURATION_CEIL_S = 90;
+/** Derive the decode tier from the lane's VRAM/size signal.
+ *  @param vramPeakGb the resolved cell's DECL-declared peak (null =
+ *   unmeasured — an unmeasured body is never called low-VRAM; the
+ *   audition-gated peak class, ROADMAP)
+ *  @param seconds the track's duration cap (the size signal)
+ *  @returns "tiled" past the size ceiling or under the VRAM floor,
+ *   "plain" otherwise */
+export function deriveDecodeTier(vramPeakGb, seconds) {
+    if (typeof seconds === "number" && seconds > TILED_DURATION_CEIL_S)
+        return "tiled";
+    if (typeof vramPeakGb === "number" && vramPeakGb < TILED_VRAM_FLOOR_GB)
+        return "tiled";
+    return "plain";
+}
+/** The tiled decode's segment seats, verbatim from the official
+ *  template's VAEDecodeAudioTiled (tile 1536, overlap 64 — inside
+ *  the engine's declared [32, 8192]/[0, 1024] bounds). */
+export const TILED_DECODE_SEATS = { tile_size: 1536, overlap: 64 };
+//# sourceMappingURL=decode.js.map

package/lib/index.d.ts

@@ -3,5 +3,7 @@ import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
 export declare const DECL: ModelDecl;
 export declare const family: Plugin;
 export { compose, parseMusicFacts, type MusicFacts, type MusicParams } from "./actions.js";
+export { MUSIC3_DISTILLED_STEPS, MUSIC3_FULL_STEPS, assertMusic3StepsInTier, music3StepTier, music3StepsEnvelope, type Music3StepTier, type Music3TierSteps, } from "./tier.js";
+export { TILED_DURATION_CEIL_S, TILED_VRAM_FLOOR_GB, deriveDecodeTier, type DecodeTier } from "./decode.js";
 export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -1,4 +1,8 @@
 import { compose } from "./actions.js";
+// THE STEP↔CHECKPOINT TIER (audit 014 C4): the row's sampler stamps
+// derive from the SAME module the compose action judges — one tier
+// derivation, never two homes.
+import { MUSIC3_FULL_STEPS, music3StepsEnvelope } from "./tier.js";
 export const DECL = {
     "id": "music3",
     "form": "form_music",
@@ -11,26 +15,64 @@ export const DECL = {
         "note": ""
     },
     "genre": "audio",
+    
+    // user-provided seats (prompt, lyrics) — the compose caller
+    // provides them. No variant-class rows: this family's served
+    // face exposes no steps+cfg pair (the census's surface-derived
+    // carve).
+    "required_defaults": [
+        { "name": "prompt", "class": "user" },
+        { "name": "lyrics", "class": "user" }
+    ],
     "variants": [
         {
             "id": "standard",
             "label": "Standard",
             "group": "Variant",
             "route": "music3",
+            // THE STEP↔CHECKPOINT TIER (audit 014 C4): the row's stamps ARE
+            // the tier derivation — the standard row's cells are full-
+            // schedule bodies, so the envelope and the resolver default
+            // spread from MUSIC3_FULL_STEPS. A distilled row lands its OWN
+            // tier stamps (MUSIC3_DISTILLED_STEPS) or the step-tier wall
+            // reds the divergent pairing.
+            "sampler_envelope": music3StepsEnvelope(MUSIC3_FULL_STEPS, [0.1, 10]),
+            // THE ACTION'S OWN SPELLING (the declared-plane door): this
+            // family's action param is n_diffusion_steps (the card schema's
+            // field) — the stamp seeds the compose body by this name.
+            "resolver_defaults": { "n_diffusion_steps": MUSIC3_FULL_STEPS.default },
             "cells": [
                 {
-                    
-                    // Comfy-Org safetensors the provisions rows carry, never a
-                    // GGUF tree.
-                    "quant": "int8",
-                    "label": "INT8 ConvRot",
+                    // THE QUANT-AXIS LAW (E2-4): the first declared cell is the
+                    // variant default — the fp16 body the official template
+                    // composes (audit 014 C5: int8 was the only row, and the
+                    // template labels it "# For low VRAM"). The fp16 cell rides
+                    // the family lane_inputs below — the atom IS this tier's
+                    // load, so the cell carries no lane stamps of its own.
+                    "quant": "fp16",
+                    "label": "FP16",
                     "route": "music3",
+                },
+                {
+                    // The low-VRAM body (the template's own note): an explicit
+                    // cell whose OWN route re-keys the address view so the
+                    // cell-lane cascade folds this unet at read (comfyui-cordis
+                    // service.ts getModel) — a stated int8 pick loads the int8
+                    // file, never the atom's. Its vram_peak_gb is the DECL's own
+                    // auditioned number and feeds the decode-tier derivation
+                    // (actions.ts deriveDecodeTier).
+                    "quant": "int8_convrot",
+                    "label": "INT8 ConvRot",
+                    "route": "music3-int8",
+                    "lane_inputs": {
+                        "unet": "minimax_music3_dit_int8_convrot.safetensors",
+                    },
                     "vram_peak_gb": 20,
                 }
             ]
         },
         {
-            "id": "short_sting",
+            "id": "short-sting",
             "label": "Short Sting",
             "hint": "Duration 5s — the card schema's own floor (a sting or loop).",
             "group": "Recipe",
@@ -38,7 +80,7 @@ export const DECL = {
             "cells": [],
         },
         {
-            "id": "full_length",
+            "id": "full-length",
             "label": "Full Length",
             "hint": "Duration 360s — the card schema's own ceiling (full-song length).",
             "group": "Recipe",
@@ -70,16 +112,34 @@ export const DECL = {
         }
     ],
     "has_inference": true,
+    // THE LANE TRUTH (audit 014 C5): the atom's unet is the fp16 body
+    // the official template composes — the family's default address
+    // serves the template's own weights. The int8_convrot file moved to
+    // its cell above (the low-VRAM pick owns its load); both bodies'
+    // downloads ride the provisions rows (the audio families' shape —
+    // no cell sources).
     "lane_inputs": {
         "clip_type": "minimax",
         "text_encoder": "minimax_music3_text_encoder_pruned_int8_convrot.safetensors",
-        "unet": "minimax_music3_dit_int8_convrot.safetensors",
+        "unet": "minimax_music3_dit_fp16.safetensors",
         "vae": "minimax_music3_dav.safetensors"
     },
     
     // three weights, provisioned from Comfy-Org's official Music-3 repo.
     "provisions": [
         {
+            // THE TEMPLATE'S BODY (audit 014 C5): the fp16 DiT the official
+            // template composes by default; digests are upstream's own HF
+            
+            "name": "minimax_music3_dit_fp16.safetensors",
+            "url": "https://huggingface.co/Comfy-Org/MiniMax-Music-3/resolve/main/diffusion_models/minimax_music3_dit_fp16.safetensors",
+            "folder": "diffusion_models",
+            "sha256": "45494a2b6b69af115902ff28eaf54118d19067aa54da01000f3e3efce7ba0e34",
+            "size_bytes": 4914197682
+        },
+        {
+            // The template's low-VRAM body ("# For low VRAM", the note
+            // verbatim) — the int8 cell's load.
             "name": "minimax_music3_dit_int8_convrot.safetensors",
             "url": "https://huggingface.co/Comfy-Org/MiniMax-Music-3/resolve/main/diffusion_models/minimax_music3_dit_int8_convrot.safetensors",
             "folder": "diffusion_models",
@@ -118,11 +178,20 @@ export const DECL = {
             },
         ],
     },
-    // THE LANE SURFACE (the z-image precedent): exactly the knobs the
-    // music card serves.
+    // THE LANE SURFACE (the z-image precedent): exactly the knobs this
+    
+    // cure): mode is the YuE2 ABC-planning vocabulary — this lane's
+    // engine node declares no mode input — so the DECL stops serving
+    // it and the write doors refuse a stated mode in the field's
+    // voice; the compose action refuses what a legacy draft still
+    // carries (actions.ts build).
     "params": [
-        "prompt", "lyrics", "duration", "mode",
+        "prompt", "lyrics", "duration",
         "guidance_scale", "n_diffusion_steps", "lm_cfg_scale", "seed",
+        // THE DECODE TIER KNOB (audit 014 C3): stated, it overrides the
+        // VRAM/size derivation; absent, the derivation decides (the
+        // compose action owns the default — no second literal home).
+        "tiled_decode",
     ],
     // THE DECLARED ACTIONS (the atom vocabulary, stroke 3):
     // the compose action the music card binds (the MiniMax Music 3 lane).
@@ -137,6 +206,8 @@ export const family = {
     },
 };
 export { compose, parseMusicFacts } from "./actions.js";
+export { MUSIC3_DISTILLED_STEPS, MUSIC3_FULL_STEPS, assertMusic3StepsInTier, music3StepTier, music3StepsEnvelope, } from "./tier.js";
+export { TILED_DURATION_CEIL_S, TILED_VRAM_FLOOR_GB, deriveDecodeTier } from "./decode.js";
 // The Loader-row face: DSH loads plugin rows by bare specifier and
 // unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
 // unwrapExports) — the default export IS the row-loadable plugin. The

package/lib/tier.d.ts

@@ -0,0 +1,51 @@
+/** The closed tier vocabulary: full-schedule vs distilled. */
+export type Music3StepTier = "full" | "distilled";
+/** The steps a tier's checkpoint samples: the closed domain and the
+ *  default the derivation stamps when the caller states nothing. */
+export interface Music3TierSteps {
+    readonly tier: Music3StepTier;
+    /** The domain's floor — a full body refuses below it. */
+    readonly min: number;
+    /** The domain's ceiling. */
+    readonly max: number;
+    /** The tier's default (the unstated compose). */
+    readonly default: number;
+}
+/** The full-schedule tier: the official template's marriage — 30
+ *  steps on the fp16/int8_convrot bodies. The card schema's served
+ *  default derives from here (one home; the shared face may not
+ *  drift from the derivation). */
+export declare const MUSIC3_FULL_STEPS: Music3TierSteps;
+/** The distilled tier: the turbo/lightning window (the qwen-img-21
+ *  turbo row's own [4, 8] and krea's distilled convention, widened
+ *  to the music family's 8–12 the audit names). A distilled variant
+ *  row is the only door below 30 — and it MUST stamp this tier (the
+ *  step-tier wall derives the roster and judges the stamps). */
+export declare const MUSIC3_DISTILLED_STEPS: Music3TierSteps;
+/** Derive the steps tier from the checkpoint a lane loads.
+ *  @param unet the resolved lane_inputs.unet (the diffusion body's
+ *   filename — the tier IS the body)
+ *  @returns the tier's closed steps domain + default */
+export declare function music3StepTier(unet: string): Music3TierSteps;
+/** The tier's sampler-envelope spelling (the DECL row's stamp shape
+ *  — the closed bounds the door's marriage judge reads). The steps
+ *  span IS the tier; the cfg span is the family's own guidance
+ *  domain, passed beside the call (the envelope schema requires both
+ *  seats — the guidance mode is the family's, not the tier's).
+ *  @param tier the derived tier whose steps span stamps
+ *  @param cfg the family's guidance domain (the DECL's card bounds)
+ *  @returns the envelope row the DECL stamps */
+export declare function music3StepsEnvelope(tier: Music3TierSteps, cfg: readonly [number, number]): {
+    steps: [number, number];
+    cfg: [number, number];
+};
+/** The compose-side pairing judge: a stated steps rides only inside
+ *  its checkpoint's tier domain.
+ *  @param unet the resolved lane_inputs.unet
+ *  @param steps the stated steps (the caller's word)
+ *  @returns the tier the pairing resolved to (the caller stamps
+ *   nothing — the value rode verbatim)
+ *  @throws naming the checkpoint, the tier, and the domain when the
+ *   stated steps is outside it (the divergent-stamp refusal) */
+export declare function assertMusic3StepsInTier(unet: string, steps: number): Music3TierSteps;
+//# sourceMappingURL=tier.d.ts.map

package/lib/tier.js

@@ -0,0 +1,74 @@
+// tier.ts — THE STEP↔CHECKPOINT TIER (audit 014 C4): the checkpoint
+// a lane loads and the steps it samples share ONE derivation. The
+// official Music-3 checkpoints are full-schedule bodies (fp16 is the
+// template's default; int8_convrot is its "For low VRAM" twin) and
+// sample the template's 30 steps; a distilled body (turbo / lightning
+// / distill marks in the filename) is the ONLY tier allowed below —
+// upstream's distilled convention is the 8–12 window. The DECL's
+// variant stamps (sampler_envelope + resolver_defaults on
+// index.ts's standard row) spread FROM this module, and the compose
+// action refuses a stated steps outside the resolved checkpoint's
+// domain — a divergent hand stamp (or a distilled row landing
+// without its bound) reds the wall, never composes.
+/** The full-schedule tier: the official template's marriage — 30
+ *  steps on the fp16/int8_convrot bodies. The card schema's served
+ *  default derives from here (one home; the shared face may not
+ *  drift from the derivation). */
+export const MUSIC3_FULL_STEPS = {
+    tier: "full",
+    min: 30,
+    max: 200,
+    default: 30,
+};
+/** The distilled tier: the turbo/lightning window (the qwen-img-21
+ *  turbo row's own [4, 8] and krea's distilled convention, widened
+ *  to the music family's 8–12 the audit names). A distilled variant
+ *  row is the only door below 30 — and it MUST stamp this tier (the
+ *  step-tier wall derives the roster and judges the stamps). */
+export const MUSIC3_DISTILLED_STEPS = {
+    tier: "distilled",
+    min: 8,
+    max: 12,
+    default: 10,
+};
+/** The distilled filename marks, spelling-agnostic: the same
+ *  grammar quant-encoding-truth's impliedQuant uses (separators
+ *  stripped, case-folded). */
+const DISTILLED_MARK = /turbo|lightning|distill/i;
+/** Derive the steps tier from the checkpoint a lane loads.
+ *  @param unet the resolved lane_inputs.unet (the diffusion body's
+ *   filename — the tier IS the body)
+ *  @returns the tier's closed steps domain + default */
+export function music3StepTier(unet) {
+    return DISTILLED_MARK.test(unet) ? MUSIC3_DISTILLED_STEPS : MUSIC3_FULL_STEPS;
+}
+/** The tier's sampler-envelope spelling (the DECL row's stamp shape
+ *  — the closed bounds the door's marriage judge reads). The steps
+ *  span IS the tier; the cfg span is the family's own guidance
+ *  domain, passed beside the call (the envelope schema requires both
+ *  seats — the guidance mode is the family's, not the tier's).
+ *  @param tier the derived tier whose steps span stamps
+ *  @param cfg the family's guidance domain (the DECL's card bounds)
+ *  @returns the envelope row the DECL stamps */
+export function music3StepsEnvelope(tier, cfg) {
+    return { steps: [tier.min, tier.max], cfg: [cfg[0], cfg[1]] };
+}
+/** The compose-side pairing judge: a stated steps rides only inside
+ *  its checkpoint's tier domain.
+ *  @param unet the resolved lane_inputs.unet
+ *  @param steps the stated steps (the caller's word)
+ *  @returns the tier the pairing resolved to (the caller stamps
+ *   nothing — the value rode verbatim)
+ *  @throws naming the checkpoint, the tier, and the domain when the
+ *   stated steps is outside it (the divergent-stamp refusal) */
+export function assertMusic3StepsInTier(unet, steps) {
+    const tier = music3StepTier(unet);
+    if (typeof steps !== "number" || !Number.isInteger(steps) || steps < tier.min || steps > tier.max) {
+        throw new Error(`music3 compose: n_diffusion_steps ${String(steps)} is outside the ${tier.tier} tier's ` +
+            `[${String(tier.min)}, ${String(tier.max)}] window for checkpoint '${unet}' ` +
+            `(the step↔checkpoint pairing — a full-schedule body samples ${String(tier.default)} steps; ` +
+            "only a distilled checkpoint (turbo/lightning/distill) may sample below, and it must stamp its own tier)");
+    }
+    return tier;
+}
+//# sourceMappingURL=tier.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@melite/models-music3",
-  "version": "0.1.5-pre-alpha",
-  "license": "SSPL-1.0",
+  "version": "0.2.2-alpha",
+  "license": "AGPL-3.0-or-later",
   "type": "module",
   "exports": {
     ".": {
@@ -11,12 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@melite/comfyui-card-kit": "0.1.5-pre-alpha"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.0",
-    "typescript": "^5.9.3",
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@melite/comfyui-card-kit": "0.2.2-alpha"
   },
   "files": [
     "lib/index.js",
@@ -24,12 +19,29 @@
     "lib/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
+  },
+  "description": "MiniMax Music 3 text-to-music — caption and lyrics conditioning over INT8 ConvRot weights, mp3 output under the run directory.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JayDataEngineer/melite.git",
+    "directory": "packages/models/music3"
   },
+  "keywords": [
+    "melite",
+    "comfyui",
+    "cordis",
+    "agent",
+    "media-generation",
+    "library"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit"
   },
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "publishConfig": {
     "access": "public"
   }