@melite/models-h3 0.0.0-stage → 0.1.4-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/schema.js ADDED
@@ -0,0 +1,487 @@
1
+ // The h3 schema plane — the film card's declared knob surface,
2
+ // moved family-side with the atom-vocabulary video stroke (the
3
+ // family's action re-validates each film stanza against THIS
4
+ // carrier; the card's wrap + compose gate import the same object —
5
+ // ONE spelling, never a second copy).
6
+ import z from '@deepseek-ai/schemastery';
7
+ import { SAMPLER_OPTIONS, SCHEDULER_OPTIONS } from '@melite/comfyui-card-kit/vocab';
8
+ import { vocabulary } from '@melite/comfyui-card-kit/vocab';
9
+ import { samplingExtra } from '@melite/comfyui-card-kit/fields';
10
+ import { bag } from '@melite/contracts/extraKeys';
11
+ import { coerceWireArrays } from '@melite/comfyui-card-kit';
12
+ import { CALL_KEYS, GRID_BASE_FRAMES, GRID_MAX_FRAMES, GRID_STEP_FRAMES, REF_CAPS, assertGridLength, assertSpanGrid, normalizeDeclaredRefs, transitionOverlap } from "./timelineContract.js";
13
+ // the window families this renderer builds (three shapes:
14
+ // t4r opener / t4_open window / t4_chain window).
15
+ export const FAMILIES = ['t4r', 't4_open', 't4_chain'];
16
+ export const wireList = normalizeDeclaredRefs;
17
+ export const H3_RECOMMENDED_SAMPLERS = [
18
+ "euler", "euler_cfg_pp", "euler_ancestral", "dpmpp_2m", "dpmpp_2m_sde", "heun",
19
+ // THE TIER-1/2 WINNERS (arena + Comfy-Org's own t2v/i2v/r2v
20
+ // templates; every name verified against the live engine's
21
+
22
+ // res_multistep is what the official templates run; er_sde +
23
+ // the beta scheduler (already on sched_name) is Parasyte's
24
+ // README rec (beta57); seeds_2/seeds_3 are the "dual clock"
25
+ // family the arena's top i2v runs rode with larryvrh v4.
26
+ "res_multistep", "res_multistep_cfg_pp", "er_sde", "seeds_2", "seeds_3",
27
+ ];
28
+ export const JSON_ARRAY_PARAMS = ['calls', 'audio_clips'];
29
+ const T4_ONLY_KEYS = [
30
+ 'sharpen_switch', 'sharpen_method', 'sharpen_strength', 'sharpen_radius',
31
+ 'sharpen_threshold', 'sharpen_iterations', 'interp_switch',
32
+ 'interp_multiplier', 'interp_model', 'sr_switch', 'sr_model', 'sr_resolution',
33
+ ];
34
+ // ── the params schema — H3TimelineCard mirrored 1:1 ─────────────────────────
35
+ // the declared field order and defaults. Bare (defaultless) keys are the
36
+ // ABSENT / required surface (prompt required=True; image
37
+ // default=None): the image-gen precedent — optional at parse, refused
38
+ // loud at compose where the lane needs them, and every read below
39
+ // normalizes with ?? so the served shape stays byte-identical.
40
+
41
+ // below are the declared constants (width 1344, height 768,
42
+ // sharpen_enabled false, shift_video 8.0) and the served shape
43
+ // carries the same values. shift_video's declared .default(8.0)
44
+ // (historical shape); at runtime schema() normalizes an
45
+ // omitted key back to null so the body resolves the family's literal
46
+ // (t4 INT 8 / t4r 8.0 — the served structural values).
47
+ export const paramSchema = z.object({
48
+ prompt: z.string().description("Prompt").extra('extra', bag({ order: null, wtype: 'textarea', placeholder: "the courier pushes off and rolls forward through the lantern glow; rain hisses on the stall awnings, a vendor calls out", tooltip: "The window's text (single-call shape). A film's calls carry their own text — a textless call refuses at compose; this field never substitutes for one." })),
49
+ image: z.string().role('path').description("First frame (keyframe lanes)").extra('extra', bag({ order: null, wtype: 'image', tooltip: "Absolute path to the PNG the video must start on (h3-keyframe). Optional for h3/h3-timeline." })),
50
+ // THE INPUT SURFACE (the H3 architecture truth — two DIFFERENT
51
+ // mechanics, the FL2VA latent anchors vs the Ref2VA conditioning
52
+ // bus): first_frame/last_frame are PIXEL anchors (bundle inputs
53
+ // 1-2, VAE-written into the latent ends — the i2v branch reads
54
+ // them verbatim); references ride the REMAINING image bus (inputs
55
+ // 3-9 → <Picture 3..9>) plus the video/audio lanes (<Video 1-3>,
56
+ // <Audio 1-3>) as AdaLN/cross-attention conditioning. Typed
57
+ // arrays, door-enforced: a non-string entry or an over-cap stack
58
+ // refuses LOUD at the gate (the probe-proven law —
59
+ // `expected array length <= 8`), never rides silent. The legacy
60
+ // `refs` stanza bag keeps its compose-side wireList readers; the
61
+ // declared fields are the primary surface.
62
+ last_frame: z.string().role('path').description("Last frame (end anchor)").extra('extra', bag({ order: null, wtype: 'image', tooltip: "FL2VA end anchor — bundle input 2. Locks the final frame's pixels; H3 generates the motion between the two anchors." })),
63
+ ref_images: z.array(z.string().role('path')).description("Reference images").max(REF_CAPS.images).extra('extra', bag({ order: null, wtype: 'image_list', max_stack: REF_CAPS.images, tooltip: "Loose references (identity, style, costume) → <Picture 3..9> via the bundle. 8 fills the bus; with a last frame set the cap is 7 (anchor + end + 7 = the 9-slot bus)." })),
64
+ ref_videos: z.array(z.string().role('path')).description("Reference videos").max(REF_CAPS.videos).extra('extra', bag({ order: null, wtype: 'image_list', media: 'video', max_stack: REF_CAPS.videos, tooltip: "Motion guides → <Video 1-3>: camera moves, timing, choreography." })),
65
+ ref_audios: z.array(z.string().role('path')).description("Reference audios").max(REF_CAPS.audios).extra('extra', bag({ order: null, wtype: 'image_list', media: 'audio', max_stack: REF_CAPS.audios, tooltip: "Sound references → <Audio 1-3>: timbre, cadence, musical tone." })),
66
+
67
+ // input. We don't use that, that is a bug that is there." Film
68
+ // music rides the D-M-E lanes' MUSIC clips, pinned per window;
69
+ // reference timbre rides ref_audios. No film-wide bed, no cuts,
70
+ // no MeliteAudioSlice in the graph.)
71
+ // DUCK DEPTH (roadmap §14, was a pinned −14 literal): how far the
72
+ // generated voice yields under a conditioned clip at its film
73
+ // span. −14dB is the natural mix-desk default; deeper for dense
74
+ // dialogue, shallower when the generated voice should hold.
75
+ duck_depth_db: z.number().description("Duck depth (dB)").min(-48).max(0).step(1).default(-14).extra('extra', bag({ order: null, wtype: 'number', columns: 2, width: 1, tooltip: "How far the generated voice ducks under a dialogue clip (−14 is the mix-desk default)." })),
76
+ seed: z.number().description("Seed").step(1).default(42).extra('extra', bag({ order: null, columns: 2, width: 1, tooltip: "Same seed across re-rolls = same world texture" })),
77
+ width: z.number().description("Width").min(448).max(1344).step(64).default(1344).extra('extra', bag({ order: null, wtype: 'number', columns: 2, width: 1 })),
78
+ height: z.number().description("Height").min(448).max(768).step(64).default(768).extra('extra', bag({ order: null, wtype: 'number', columns: 2, width: 1 })),
79
+
80
+ // (min 21, step 5) contradicted the card's own declared law — the
81
+ // 17k+5 frame grid (identity principle + tooltip: 56/90/124/362).
82
+ // Schemastery step is offset-from-min, so step(5) from 21 admitted
83
+ // {21, 26, ...} and REFUSED the documented values (90, 124, 362 —
84
+ // the compose door's `expected number multiple of 5` on a user-set
85
+ // Frames). min(22).step(17) admits exactly (L-5) % 17 === 0 — the
86
+ // served stepper now walks the true grid 22/39/56/.../362 and the
87
+ // explicit 90 passes the walk. 56 (the declared
88
+ // default) is on-grid; the omitted-key path normalizes to null in
89
+ // schema() so the body computes the family's frame budget.
90
+ length: z.number().description("Frames").min(GRID_BASE_FRAMES).max(GRID_MAX_FRAMES).step(GRID_STEP_FRAMES).default(56).extra('extra', bag({ order: null, columns: 2, width: 1, tooltip: "17k+5 grid at 24fps: 56 = 2.33s, 124 = 5.17s, 362 = 15s", wtype: 'number' })),
91
+ steps: z.number().description("Steps").min(4).max(30).default(12).extra('extra', samplingExtra('steps', { tooltip: "12 for draft; 30 standard; a boarded distill lora applies its own steps (edit them on the lora entry)" })),
92
+
93
+ // needs an on/off switch, it is very unclear if it is on or off"):
94
+ // one boolean heads the tab. Off (default) = the whole post chain
95
+ // is inert: the leaves hide AND the compose gates hard (sharpen,
96
+ // interp, VSR, refine all read the master FIRST — a legacy doc
97
+ // with leaves set but no master renders the plain pass).
98
+ second_pass_enabled: z.boolean().description("Second pass").default(false).extra('extra', bag({ order: null, group: 'second_pass', wtype: 'boolean', tooltip: "Master switch for the entire post chain — FSR sharpening, FILM interpolation, SeedVR2 super-res, and the refine lora. Off (default) = the film lands straight from the sampler. On = the pass controls below arm." })),
99
+ sharpen_enabled: z.boolean().description("FSR Sharpening").default(false).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", tooltip: "Apply AMD FidelityFX RCAS sharpening to the final output. Strength 0.3 looks natural." })),
100
+ sharpen_strength: z.number().description("Sharpen Strength").min(0).max(1).step(0.05).default(0.3).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true", tooltip: "RCAS sharpening intensity. 0.3 = natural; 0.5 = crisp; 0.0 = off.", wtype: 'number' })),
101
+ // interpolate_enabled: HONEST DEFAULT (hour 20): the card's
102
+ // `bool = False` — `default(false)`, not the "false"-as-boolean
103
+ // cast-lie. An absent key now fills the boolean NATIVELY (no
104
+
105
+ // The wire-string tolerance (the bench add-door rides the served
106
+ // literal "false"/"true" as an explicit key) is a DOC-level law —
107
+ // coerceWireBoolean below — because schemastery field transforms
108
+ // classify as type 'json' in the served taxonomy (the
109
+ // knob-freshness wall pins the honest 'boolean').
110
+ interpolate_enabled: z.boolean().description("FILM Interpolation").default(false).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'boolean', tooltip: "Apply FILM (Feature-aware Interpolation for Large Motion) frame interpolation to double the frame rate. Doubles render time." })),
111
+
112
+ // every key the compose READS rides the declared surface at its
113
+ // exact wire name — the studio's historical spellings
114
+ // (sampling_steps / sampler / scheduler / interpolate_model /
115
+ // interpolate_multiplier / rtx_vsr_enabled) never matched these,
116
+ // were never read, and die with the studio rework.
117
+
118
+ // sampler and scheduler next to each other but here they're on
119
+ // different rows?"): the sampling layout truth (group/columns/
120
+ // width/zone) is the KIT's — steps/sampler/scheduler ride
121
+ // samplingExtra() like every normal card; h3-only knobs (denoise,
122
+ // the shifts) declare the SAME layout facts inline (card-owned
123
+ // kinds, one place each). The 2-column grid seats sampler +
124
+ // scheduler side by side on EVERY face that honors the grammar.
125
+ denoise: z.number().description("Denoise").min(0).max(1).step(0.05).default(1.0).extra('extra', bag({ order: 4, group: 'sampling', columns: 2, width: 1, zone: 'params', wtype: 'number', tooltip: "How much of the latent the sampler rewrites. 1.0 = full denoise (fresh windows); lower inherits structure." })),
126
+ // CLOSED TYPES (hour 22 incident): these were
127
+ // z.string() with a DECORATIVE extra options list — the gate accepted
128
+ // any string (no membership refusal), the face showed the hand-stamped
129
+ // six, the engine accepts the pin's 45: three truths for one key. The
130
+ // union of consts is the ONE truth now — the face reads the members,
131
+ // the gate refuses off-set values at the compose door (the kit's own
132
+ // law: sampler/scheduler knobs ride vocabulary()), and the declared
133
+ // default stays reachable (fill === walk by construction).
134
+ // THE TIER WINNERS, TAKEN FROM THE KIT'S OWN 45 (the census's H2):
135
+
136
+ // engine vocabulary (regen-vocab.ts owns that file) left the film
137
+ // card's menu stale — and a name the engine had dropped would still
138
+ // be offered and then 400. The subset is NAMED here (a card's
139
+ // recommendation is real curation) but every member is READ from
140
+ // the SSOT, and a wall asserts the subset survives a regen.
141
+ sampler_name: vocabulary([
142
+ // the membership test widens the tuple's read view (a readonly
143
+ // literal tuple's includes() demands the literal union — the
144
+ // filter's n is string; the WALL, not the tuple's type, keeps
145
+ // every member honest against the SSOT)
146
+ ...SAMPLER_OPTIONS.filter((n) => H3_RECOMMENDED_SAMPLERS.includes(n)),
147
+ ]).description("Sampler").default("euler").extra('extra', samplingExtra('sampler', { tooltip: "The KSampler solver. euler family pairs with turbo adapters; res_multistep is the official-template solver; er_sde+beta is the Parasyte rec; seeds_2/3 are the dual-clock family." })),
148
+ // the same law for the scheduler: the kit's engine vocabulary,
149
+ // read (the census's H2 — a retyped list is a second SSOT)
150
+ sched_name: vocabulary([...SCHEDULER_OPTIONS]).description("Scheduler").default("simple").extra('extra', samplingExtra('scheduler', { tooltip: "The sigma schedule shape." })),
151
+ // ── THE T3 REFINE RIDER (roadmap item 2; ledger #30 §3(2)) —
152
+ // the crowd's third tier: a short CLOSING pass over each
153
+ // window's output latent, the refiner lora on its OWN loader
154
+ // (the primary stack never changes). Empty refine_lora = no
155
+ // rider, the graph renders exactly as before. The instrument:
156
+ // the catalog's refiner rows (h3_taomate_3step — 0.7 @ 3 steps,
157
+ // the arena's refiner operating point). ONE OWNER PER KNOB:
158
+ // refine_lora picks the instrument; strength/steps default from
159
+ // THE ROW (no silent overrides); the pass rides the doc's own
160
+ // sampler/scheduler.
161
+ refine_lora: z.string().description("Refine lora").default("").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'select', optionsFrom: 'loras', tooltip: "Catalog id of a refiner lora (e.g. h3_taomate_3step). Empty = no refine pass. Strength/steps default from the row. LORAS ARE ONLY MODS — the pick serves from the loras flavor rows, never a hand-spelled id (the compose door refuses unknown ids loud)." })),
162
+ refine_strength: z.number().description("Refine strength").min(0).max(2).step(0.05).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'number', tooltip: "Override the refiner row's strength. Rides only when refine_lora is set." })),
163
+ refine_steps: z.number().description("Refine steps").min(1).max(10).step(1).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'number', tooltip: "Override the refiner row's step count (taomate: 3). Rides only when refine_lora is set." })),
164
+ // ── THE ATTENTION BACKEND (roadmap item 3; the h3_attention
165
+ // "sage/sol" folklore was FICTION — no such knob, and the engine
166
+ // enumerates only 'pytorch attention' on ModelAttentionBackend;
167
+ // sage/sol are NOT served). This knob owns the ONE input the
168
+ // non-SLA arm actually pins: 'comfy kitchen attention' is the
169
+ // estate-proven literal (plaguekind's template value, silicon
170
+ // receipts on the t4 arm); 'pytorch attention' is the engine's
171
+ // own enumeration. Values the engine refuses are NOT offered.
172
+ attention_backend: vocabulary(["comfy kitchen attention", "pytorch attention"]).description("Attention backend").default("comfy kitchen attention").extra('extra', bag({ order: null, group: 'sampling', wtype: 'select', tooltip: "The non-SLA arm's ModelAttentionBackend — used when the SLA sparse attention switch (Sla group) is OFF. ck-kitchen is the estate-proven default; pytorch is the engine's enumerated literal." })),
173
+ interp_model: vocabulary(["film_net_fp16.safetensors", "rife47.pth"]).description("Interp model").default("film_net_fp16.safetensors").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&interpolate_enabled=true", wtype: 'select', tooltip: "FILM or RIFE frame-interpolation weights." })),
174
+ interp_multiplier: z.number().description("Interp multiplier").min(2).max(4).step(1).default(2).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&interpolate_enabled=true", wtype: 'number', tooltip: "Frame multiple (2 = double the frame rate)." })),
175
+ sr_switch: z.boolean().description("Super-Res (SeedVR2)").default(false).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", tooltip: "Upscale the final film through SeedVR2 before saving." })),
176
+ sr_resolution: z.number().description("Super-Res target").min(720).max(2160).step(360).default(1080).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sr_switch=true", wtype: 'number', tooltip: "The SeedVR2 output height in px." })),
177
+ // CLOSED FILE SURFACE (the operator's dropdown law — a free-text
178
+ // weights row is a guess box): the two SeedVR2 DiT files the estate
179
+ // actually runs (both proven in shipped _flow.json receipts: the fp16
180
+ // 3B default + the fp8_e4m3fn 3B the lane walked). The union owns the
181
+ // dropdown AND the membership refusal (an off-set value fails at the
182
+ // schema door, never as a ComfyUI 400). Gated behind sr_switch like
183
+ // every other post leaf.
184
+ sr_model: vocabulary(["seedvr2_ema_3b_fp16.safetensors", "seedvr2_ema_3b_fp8_e4m3fn.safetensors"]).description("Super-Res model").default("seedvr2_ema_3b_fp16.safetensors").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sr_switch=true", wtype: 'select', tooltip: "SeedVR2 weights (models/upscale_models/): fp16 3B default, fp8_e4m3fn 3B leaner." })),
185
+ // the R2V COMBO size mode — the literals OR a concrete WxH dimension
186
+ // ("704x1280" rides in real runs; a number or a typo refuses LOUD at
187
+ // the gate now, not as a ComfyUI 400). The select face serves the
188
+ // two literals; WxH stays reachable by patch, exactly as before.
189
+ ref_image_size: z.union([z.const("match"), z.const("max"), z.string().pattern(/^\d+x\d+$/).description("WxH")]).description("Ref size").default("match").extra('extra', bag({ order: null, group: 'sampling', wtype: 'select', tooltip: "How the bundle resizes ref images: match the anchor, take the max edge, or an explicit WxH." })),
190
+
191
+ // one truth, one owner. shift_video is a NUMBER, default 8, served
192
+ // and walked identically. The old z.const(null) arm — the
193
+ // "family-literal resolution path" that walked empty docs to null
194
+ // so the renderer's ?? floor could silently pick the family's own
195
+ // literal — is deleted. An explicit null in a draft now REFUSES
196
+ // LOUD at the walk. The hour-22 double-default (same 8 spelled on
197
+ // the union and the inner arm) never made the walk fill 8; it
198
+ // bought the face a number while the call kept the body literal.
199
+ shift_video: z.number().description("Video Shift").min(1).max(20).step(0.5).default(8).extra('extra', bag({ order: 5, group: 'sampling', columns: 2, width: 1, zone: 'params', wtype: 'number', tooltip: "Timestep shift for video attention. Higher = more coherent motion." })),
200
+ shift_audio: z.number().description("Audio Shift").min(1).max(10).step(0.5).default(3).extra('extra', bag({ order: 6, group: 'sampling', columns: 2, width: 1, zone: 'params', wtype: 'number', tooltip: "Timestep shift for audio attention. Lower = more detailed sound.", })),
201
+ // ── the SLA family (hour 16, item 3): compose-read knobs, now
202
+ // EMITTED — the studio's advanced panel rides the served spec
203
+ // (SpecFieldRow) instead of hand-rolled rows. Defaults are the
204
+ // compose's own ?? fallbacks, byte-for-byte; the h3_ prefix is the
205
+ // studio's LayerA spelling (docModel), never the card's.
206
+
207
+ // to turn SLA on/off or is it always on" — it was always on): the
208
+ // one boolean heads the sla group; every tuning leaf below rides
209
+ // visible_when behind it. Default true = today's behavior for
210
+ // every existing doc (absent = on at compose).
211
+ sla_enabled: z.boolean().description("SLA sparse attention").default(true).extra('extra', bag({ order: null, group: "sla", tooltip: "Block-sparse attention on the DiT (the primary speed arm, ~1.75x). Off falls back to the Attention backend row." })),
212
+ sla_sparsity: z.number().description("SLA sparsity").min(0).max(0.95).step(0.05).default(0.9).extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'slider', tooltip: "Block-sparse attention density. 0.90 ≈ 1.75x speedup, no quality loss." })),
213
+ sla_block_size: vocabulary(["32", "64", "128"]).description("SLA block size").default("32").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'select', tooltip: "64 = clean audio; 128 = faster, robotic." })),
214
+ sla_min_seq_len: z.number().description("SLA min seq length").min(512).step(512).default(12288).extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'number', tooltip: "Sequences shorter than this skip sparsity." })),
215
+ sla_dense_last_steps: z.number().description("SLA dense last steps").min(0).max(10).step(1).default(1).extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'number', tooltip: "Final steps run dense for convergence." })),
216
+ sla_dense_steps: z.string().description("SLA dense steps (explicit)").default("0").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", tooltip: "e.g. 0,1 or 0-2 — explicit dense step indices." })),
217
+ sla_dense_backend: vocabulary(["comfy_kitchen", "pytorch", "auto"]).description("SLA dense backend").default("comfy_kitchen").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'select' })),
218
+ sla_reference_protection: vocabulary(["Off", "Light", "Heavy Enforcement"]).description("SLA ref protection").default("Heavy Enforcement").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", wtype: 'select', tooltip: "Protects reference frames from sparse-attention drift." })),
219
+ sla_protect_audio: z.boolean().description("SLA protect audio").default(true).extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", tooltip: "Keep the audio stream out of the sparse path." })),
220
+ sla_stabilize_motion: z.boolean().description("SLA stabilize motion").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", tooltip: "Default on except t4r openers (the family-conditional compose fallback stays the truth at run)." })),
221
+ sla_disable_fp16_accum: z.boolean().description("SLA full-precision accum").default(true).extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", tooltip: "Full-precision accumulation inside the sparse kernel." })),
222
+ // ── the sharpen leaves (compose: only EXPLICITLY-set leaves patch
223
+ // ImageSharpenKJ's grouped dict — bare emission defaults do NOT
224
+ // change a run that never sets them). VISIBILITY rides the
225
+ // declaration's own visible_when grammar (&-ANDed guards, |-SET
226
+ // values) — no hand-rolled predicates anywhere.
227
+ sharpen_method: vocabulary(["rcas", "adaptive_usm", "high_pass", "deconvolution"]).description("Sharpen Method").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true", wtype: 'select' })),
228
+ sharpen_radius: z.number().description("Sharpen Radius").min(0.5).max(5).step(0.5).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true&sharpen_method=adaptive_usm|high_pass|deconvolution", wtype: 'number', tooltip: "adaptive_usm / high_pass / deconvolution only." })),
229
+ sharpen_threshold: z.number().description("Sharpen Noise Gate").min(0).max(1).step(0.05).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true&sharpen_method=adaptive_usm", wtype: 'number', tooltip: "adaptive_usm only." })),
230
+ sharpen_iterations: z.number().description("Sharpen Iterations").min(1).max(100).step(1).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true&sharpen_method=deconvolution", wtype: 'number', tooltip: "deconvolution only." })),
231
+ // NOTE: the calls[] SHOTS surface is deliberately NOT a carrier
232
+ // knob — the carrier feeds the studio's frozen form-spec (the
233
+ // studio owns its own shots editor, ui/studio/docModel) and the
234
+ // served manifests. The AGENT plane declares calls in the tool
235
+ // face (src/tool.ts); the SHOT LAWS are the card gate's (schema()
236
+ // below — the model_validator port), so every composer
237
+ // agent tool, studio, any future caller — meets the same gate.
238
+
239
+ // schema enforces EVERY key the renderer reads — no blind casts, no
240
+ // silent rides): the stanza/film vocabulary below was historically
241
+ // undeclared (it rode `admits` and every walk passed it verbatim
242
+ // while renderH3Window blind-cast it). Types mirror the renderer's
243
+ // reads exactly; NO defaults — the renderer's ?? fallback chains
244
+ // stay authoritative, the walk only REFUSES garbage. HIDDEN FROM
245
+
246
+ // INDEX, WHY IS IT BLANK"): validation-only keys never render; a
247
+ // default-less blank row on the form is a lie.
248
+ k: z.number().description("Window index (film vocabulary)").step(1).extra('extra', bag({ hidden: true })),
249
+ noise_seed: z.number().description("Per-window noise seed").step(1).extra('extra', bag({ hidden: true })),
250
+ fps_seconds: z.number().description("Clip seconds (fps rail)").min(1).max(60).default(10).extra('extra', bag({ order: null, wtype: 'number', tooltip: "The clip's duration in seconds (the fps rail's duration primitive)." })),
251
+ // THE LEGACY ALIASES (renderer-era spellings of the mod switches)
252
+ // — gate-admitted for old drafts, never user surface: the MODS
253
+
254
+ interp_switch: z.boolean().description("Interpolate switch (legacy alias)").extra('extra', bag({ hidden: true })),
255
+ sharpen_switch: z.boolean().description("Sharpen switch (legacy alias)").extra('extra', bag({ hidden: true })),
256
+ sla_switch: z.boolean().description("SLA switch (legacy alias)").extra('extra', bag({ hidden: true })),
257
+ image_name: z.string().role('path').description("Guide image (renderer alias)").extra('extra', bag({ hidden: true, wtype: 'image', tooltip: "The renderer's guide-image spelling — gate-admitted for old docs; the rail's First frame is the user face." })),
258
+ });
259
+ /** Schemastery objects are lenient (unknown/missing keys ride); the
260
+ * family-admission laws are the renderer's own validators, ported:
261
+ * unknown variant + family-conditional key admission on EXPLICIT
262
+ * params only (the python gate reads model_fields_set). The t4r
263
+ * staged-image law rides compose (it reads the merged value). The
264
+ * renderer-vocabulary keys (variant, k, ctx_*, sla_*, ...) are NOT
265
+ * declared knobs — old drafts keep working because the schema admits
266
+ * them and the compose door overlays explicit params last (the
267
+ * img-to-mesh filename_prefix precedent). */
268
+ // THE WIRE LAW (hour 20 — ONE definition, every door): a fresh stage
269
+ // from the bench add-door rides the served wire literal ("false"/"true")
270
+ // as an EXPLICIT key; coerce it to the runtime boolean before the
271
+ // boolean walk refuses it. Absent keys need nothing — default(false)
272
+ // fills natively. (A schemastery field transform would classify the
273
+ // served knob as type 'json' — the honest 'boolean' taxonomy wins,
274
+ // so the law lives here, shared by schema() and the compose gate.)
275
+ export const coerceWireBoolean = (raw) => {
276
+ if (typeof raw.interpolate_enabled === 'string') {
277
+
278
+ // the TWO wire literals only — any other string refused LOUD
279
+ // (silent garbage-to-false was a walk bypass, never the wire law).
280
+ const v = raw.interpolate_enabled;
281
+ if (v !== 'true' && v !== 'false') {
282
+ throw new Error(`interpolate_enabled must be a boolean or the wire literal "true"/"false" — got ${JSON.stringify(v).slice(0, 40)}`);
283
+ }
284
+ return { ...raw, interpolate_enabled: v === 'true' };
285
+ }
286
+ return raw;
287
+ };
288
+ export function schema(v) {
289
+ const raw = (v ?? {});
290
+ if (raw.calls !== undefined && !Array.isArray(raw.calls)) {
291
+ throw new Error('h3-timeline: calls must be an array of shot rows');
292
+ }
293
+ if (raw.audio_clips !== undefined && !Array.isArray(raw.audio_clips)) {
294
+ throw new Error('h3-timeline: audio_clips must be an array of clip rows');
295
+ }
296
+ // length null SURVIVES this walk on purpose (the walk-shadow fix:
297
+ // multi-call docs keep null — per-window spans compute at compose).
298
+
299
+ // names the array keys — a wire "" (the empty-array corruption)
300
+ // fills to [], an {item:[…]} wrapper unwraps — same law as the
301
+ // boolean wire tolerance above (receipts: commission 034's
302
+ // run-9953f652410d-d365af74, `$.ref_images expected array but
303
+ // got [object Object]` ×4 and `calls: ""`).
304
+ const out = paramSchema(coerceWireArrays(paramSchema, coerceWireBoolean(raw)));
305
+ let variant = typeof raw.variant === 'string' ? raw.variant : undefined;
306
+ // variant DERIVATION (opener_family/chain_family): the studio calls shape carries no variant; the card derives it.
307
+ // An image-anchored opener rides t4r; a text-only single call is t4_open; multiple calls chain (t4_chain).
308
+
309
+ // a freshly added card holds params {} — calls is NOT a form knob,
310
+ // so the bench tile's Run composed no shots and the door refused
311
+ // "no calls to compose" before the studio ever persisted its doc).
312
+ // ABSENT calls compose the card's own fresh-card document: ONE
313
+ // window 0→90 — the t4_open fresh-card draft budget (
314
+ // display = render, 3.8s). A user authoring a LONGER single window
315
+
316
+ // gates; if a user wants a long window, they should get a long
317
+ // window"); the span-vs-engine receipts live in the ledger as
318
+ // knowledge, never enforcement. An
319
+ // EXPLICIT empty array keeps the retired compose refusal verbatim
320
+ // ("%s: no calls to compose"): a caller naming
321
+ // zero shots is garbage; a caller naming none is a fresh card.
322
+ if (variant === undefined) {
323
+ let calls = [];
324
+ if (Array.isArray(raw.calls)) {
325
+ calls = raw.calls;
326
+ }
327
+ else {
328
+ calls = [{ start_frame: 0, end_frame: 90 }];
329
+ out['calls'] = calls;
330
+ }
331
+ if (calls.length === 0) {
332
+ throw new Error('h3-timeline: no calls to compose');
333
+ }
334
+ // THE ROW-LEVEL NUMERIC RESTORE (attempt-035/009's stop-law
335
+
336
+ // DELIBERATELY undeclared on paramSchema (the agent plane owns
337
+ // them) — the dict-driven wire fill has no license on undeclared
338
+ // keys, so a stringified `start_frame: "0"` rode into the shot
339
+ // laws and refused `start_frame is required (int frames — text
340
+ // alone is not a shot)` EVEN THOUGH the caller sent the number.
341
+ // The card OWNS the int law here — it restores the strict-grammar
342
+ // int-string itself (same fill law as the kit's, scoped to the
343
+ // row fields the shot laws read).
344
+ const INT_STRING = /^[+-]?\d+$/;
345
+ const wireInt = (x) => (typeof x === 'string' && INT_STRING.test(x.trim()) ? Number(x.trim()) : x);
346
+ for (let wi = 0; wi < calls.length; wi++) {
347
+ const wc = (calls[wi] ?? {});
348
+ for (const wn of ['start_frame', 'end_frame']) {
349
+ const wv = wireInt(wc[wn]);
350
+ if (wv !== wc[wn]) {
351
+ wc[wn] = wv;
352
+ calls[wi] = wc;
353
+ }
354
+ }
355
+ }
356
+ // THE SHOT LAWS (the ranges are the card gate's, never a silent re-default: an out-of-range seam is refused and a reversed span is refused; both banned).
357
+ // (the seam_carry law died with the MotionContext seam — the
358
+ // drift-control continuation owns the chaining now, overlap is
359
+ // automatic, never user-authored lane physics)
360
+ for (let i = 0; i < calls.length; i++) {
361
+ const c = (calls[i] ?? {});
362
+ const unknown = Object.keys(c).filter((key) => !CALL_KEYS.has(key)).sort();
363
+ if (unknown.length > 0) {
364
+ throw new Error(`calls[${i}]: unknown per-call key(s): ${unknown.join(', ')}`);
365
+ }
366
+ for (const name of ['start_frame', 'end_frame']) {
367
+ const v = c[name];
368
+ if (v === undefined || v === null || typeof v !== 'number' || !Number.isInteger(v)) {
369
+ throw new Error(`calls[${i}]: ${name} is required (int frames — text alone is not a shot)`);
370
+ }
371
+ }
372
+ if (c.end_frame <= c.start_frame) {
373
+ throw new Error(`calls[${i}]: end_frame ${c.end_frame} <= start_frame ${c.start_frame} — a reversed or empty span is not a shot`);
374
+ }
375
+ if (i > 0) {
376
+ // the previous row was already validated as an int-span object
377
+ // (a hole at i-1 refused at its own iteration), so no fallback
378
+ const previous = calls[i - 1];
379
+ if (c.start_frame !== previous.end_frame) {
380
+ throw new Error(`calls[${i}]: start_frame ${String(c.start_frame)} must equal previous end_frame ${String(previous.end_frame)} — calls tile the film timeline; gaps and overlaps are refused`);
381
+ }
382
+ }
383
+ const transition = typeof c.transition === 'string' ? c.transition : undefined;
384
+ // THE GRID GATE (§26, the walk arm): a call's knobs.length pin
385
+ // bypasses every snap arm downstream — validate at the walk so
386
+ // `validate` refuses what the engine would kill at GPU cost.
387
+ const cknobs = (c.knobs ?? {});
388
+ if (cknobs.length !== undefined && cknobs.length !== null) {
389
+ assertGridLength(cknobs.length, `calls[${i}].knobs.length`);
390
+ }
391
+ // THE UNIFORM SPAN GATE: one grid law for every window shape —
392
+ // carried windows (i>0, non-cut) generate span+22, first/cut
393
+ // windows generate their span, and an off-grid authored span is
394
+ // refused at admission instead of silently snapped.
395
+ assertSpanGrid({
396
+ start: c.start_frame,
397
+ end: c.end_frame,
398
+ }, `calls[${i}]`, i > 0 ? transitionOverlap(transition) : 0);
399
+ }
400
+ // (the shot-law loop above guarantees every row is a shaped
401
+ // object with pinned int spans — no gap-arms needed here)
402
+ // variant is a WINDOW property: a single-call doc's guide makes the
403
+ // whole (one-window) graph t4r; a MULTI-call doc is a film — its
404
+ // variant is t4_chain and each window derives its own family in
405
+ // the merged renderer (a guide call renders as its own t4r window)
406
+ const hasGuide = calls.some((c) => {
407
+ const cc = c;
408
+ return Boolean(cc.ref_images) || Boolean(cc.ref_image) || Boolean(cc.image_name);
409
+ })
410
+ // THE DECLARED INPUT SURFACE (the input rail's law): card-level
411
+ // refs / an end anchor / the audio bed imply the r2v lane by the
412
+ // same law as a per-call guide — the window re-checks, but the
413
+ // derivation owns it first
414
+ || wireList(raw.ref_images).length + wireList(raw.ref_videos).length + wireList(raw.ref_audios).length > 0
415
+ || (typeof raw.last_frame === 'string' && raw.last_frame.trim() !== '');
416
+ variant = calls.length > 1 ? 't4_chain' : hasGuide ? 't4r' : 't4_open';
417
+ out.variant = variant;
418
+ }
419
+ if (!FAMILIES.includes(variant)) {
420
+ throw new Error(`unknown window family '${variant}' (known: ${[...FAMILIES].sort().join(', ')})`);
421
+ }
422
+ const explicit = new Set(Object.keys(raw));
423
+
424
+ // default(8) is THE owner. The old nulling — "an omitted key
425
+ // normalizes back to null so the body resolves the family's
426
+ // literal (t4 INT 8 / t4r 8.0) and the frozen graphs stay
427
+ // byte-identical" — was the two-owner disease in its purest form:
428
+ // the declaration promised 8, the walk delivered null, the body
429
+ // invented 8 back. JS serializes 8.0 and 8 identically, so the
430
+ // nulling bought nothing but the lie. The no-cheat door refuses
431
+ // this card shape on sight now.
432
+
433
+ // declared .default(56) is the declared default,
434
+ // but the body computes the family's frame budget where the python
435
+ // computes it (t4_open 90 / else 56 — "None = absent on wire").
436
+ // Without this normalization the schemastery walk materializes 56 on
437
+ // every doc that omits the key and the t4_open 90 branch is dead —
438
+ // a hand-authored single text window silently rendered 56 frames.
439
+
440
+ // default may never walk null. Single-call docs keep the span
441
+ // rider (the window's grid-snapped span, EXPLICIT — the doc's span
442
+ // IS the film). Multi-call docs let the walked default stand INERT
443
+ // — the doc-level length is a WINDOW knob and multi-call films
444
+ // have no doc-level window; the per-window stanza lengths own the
445
+ // film (each call's span), and the studio's timeline readouts
446
+ // compute off the calls, never this key. (An earlier arm of this
447
+ // rework filled the FILM TOTAL here — wrong law: the 17k+5 grid
448
+ // belongs to windows, a total is arbitrary span arithmetic, and
449
+ // the walk's grid validation rightly refused off-grid totals.)
450
+ if (!explicit.has('length')) {
451
+ const rows = Array.isArray(out.calls) ? out.calls : [];
452
+ if (rows.length === 1) {
453
+ // (the shot laws above guarantee valid int spans — direct
454
+ // reads, no defensive re-validation)
455
+ const sf = rows[0].start_frame;
456
+ const ef = rows[0].end_frame;
457
+ // (the shot laws above guarantee valid int spans — every
458
+ // single-call doc rides the snap arm; no defensive else)
459
+ out.length = ef - sf;
460
+ }
461
+ // rows.length !== 1: the walked default stands (56 fresh-card,
462
+ // inert for multi-call chains — spans own the film)
463
+ }
464
+ const bad = (keys) => keys.filter((kk) => explicit.has(kk)).sort();
465
+ if (variant === 't4r') {
466
+ const b = bad(T4_ONLY_KEYS);
467
+ if (b.length)
468
+ throw new Error(`h3_window(t4r): unsanctioned inject keys: ${b.join(', ')}`);
469
+ }
470
+ // THE STEPS-PIN STAMP (007-H3-LoRA-PLANE L3): whether the caller
471
+ // pinned steps is a fact only this walk owns (the raw keys —
472
+ // defaults materialize downstream and the film build can no
473
+ // longer tell a pinned count from the walked default). The
474
+ // single-window marriage reads it: an explicit count is the
475
+ // user's word and the distill default never overwrites it. The
476
+ // __-prefix internal channel (the film loop's
477
+ // __iteration/__overlap precedent) — faces project the carrier's
478
+ // declared knobs only, so no served surface changes.
479
+ out.__steps_pinned = explicit.has('steps');
480
+ return out;
481
+ }
482
+ // THE TOOL-FACE EXPORTS: the carrier (paramSchema — the same object
483
+ // the registry's schemaCarrier hands the served-manifest projection;
484
+ // ONE spelling, two doors) + the identity rung (the ring's label/
485
+ // description prose, stated once).
486
+ export const carrier = paramSchema;
487
+ //# sourceMappingURL=schema.js.map
@@ -0,0 +1,79 @@
1
+ export declare const SEAM_OVERLAP_FRAMES = 22;
2
+ export declare const GRID_BASE_FRAMES = 22;
3
+ export declare const GRID_STEP_FRAMES = 17;
4
+ export declare const GRID_MAX_FRAMES = 362;
5
+ export declare const GRID_REMAINDER = 5;
6
+ export declare const IMAGE_BUS_SLOTS = 9;
7
+ export declare const REF_CAPS: {
8
+ readonly images: 8;
9
+ readonly videos: 3;
10
+ readonly audios: 3;
11
+ };
12
+ export interface TimelineSpan {
13
+ readonly start: number;
14
+ readonly end: number;
15
+ readonly transition?: string;
16
+ }
17
+ export interface TimelineCallSpan {
18
+ readonly start_frame: number;
19
+ readonly end_frame: number;
20
+ readonly transition?: string;
21
+ }
22
+ export declare function transitionOverlap(transition?: string): number;
23
+ export declare function spanOverlap(span: TimelineSpan): number;
24
+ export declare function spanStanzaFrames(span: TimelineSpan, carry?: number): number;
25
+ export interface CarriedSpanGrid {
26
+ readonly generatedStart: number;
27
+ readonly generatedEnd: number;
28
+ readonly length: number;
29
+ readonly lowerEnd: number;
30
+ readonly upperEnd: number;
31
+ }
32
+ export declare function carriedSpanGrid(span: TimelineSpan, carry?: number): CarriedSpanGrid;
33
+ export declare function assertCarriedSpanGrid(span: TimelineSpan, where: string, carry?: number): number;
34
+ export declare function gridSnap(length: number): number;
35
+ /** THE GRID PREDICATE, one owner: a length the engine can render is
36
+ * 22+17k inside [22,362]. Every refusal door asks this question, so
37
+ * knob pins, single windows, cut windows, and carried windows cannot
38
+ * drift into different laws. */
39
+ export declare function isGridLength(length: number): boolean;
40
+ export declare function assertGridLength(length: unknown, where: string): number;
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+ export declare function assertSpanGrid(span: TimelineSpan, where: string, carry?: number): number;
50
+ export declare function deliveredFrames(call: TimelineCallSpan, index: number): number;
51
+ export declare function imageReferenceCap(hasLastFrame: boolean): number;
52
+ export declare function splitRefList(value: string | undefined): string[];
53
+ export declare function normalizeDeclaredRefs(value: unknown): string[];
54
+ export declare function joinRefList(value: unknown): string | undefined;
55
+ export declare function mergeDeclaredRefs(declared: readonly string[], perCall: readonly string[]): string[];
56
+ export declare function refGenreOf(name: string, url?: string): 'image' | 'video' | 'audio' | 'other';
57
+ export declare const KNOB_ORDER: readonly ["steps", "denoise", "sampler_name", "sched_name", "shift_video", "shift_audio", "sla_sparsity", "sla_block_size", "sla_min_seq_len", "sla_dense_last_steps", "sla_protect_audio", "sla_stabilize_motion", "sla_reference_protection", "sla_dense_backend", "sla_dense_steps", "sla_disable_fp16_accum", "sharpen_enabled", "sharpen_method", "sharpen_strength", "sharpen_radius", "sharpen_threshold", "sharpen_iterations", "interpolate_enabled", "interp_model", "interp_multiplier", "length"];
58
+ export type KnobKey = (typeof KNOB_ORDER)[number];
59
+ export declare const CALL_KNOB_KEYS: ReadonlySet<string>;
60
+ export declare const CALL_KEYS: ReadonlySet<string>;
61
+ export declare const LEGACY_KNOB_KEY: {
62
+ readonly sampling_steps: "steps";
63
+ readonly sampler: "sampler_name";
64
+ readonly scheduler: "sched_name";
65
+ readonly h3_sla_sparsity: "sla_sparsity";
66
+ readonly h3_sla_block_size: "sla_block_size";
67
+ readonly h3_sla_min_seq_len: "sla_min_seq_len";
68
+ readonly h3_sla_dense_last_steps: "sla_dense_last_steps";
69
+ readonly h3_sla_protect_audio: "sla_protect_audio";
70
+ readonly h3_sla_stabilize_motion: "sla_stabilize_motion";
71
+ readonly h3_sla_reference_protection: "sla_reference_protection";
72
+ readonly h3_sla_dense_backend: "sla_dense_backend";
73
+ readonly h3_sla_dense_steps: "sla_dense_steps";
74
+ readonly h3_sla_disable_fp16_accum: "sla_disable_fp16_accum";
75
+ readonly interpolate_model: "interp_model";
76
+ readonly interpolate_multiplier: "interp_multiplier";
77
+ };
78
+ export declare function migrateCallKnobKey(key: string): string;
79
+ //# sourceMappingURL=timelineContract.d.ts.map