@melite/models-h3 0.2.0-alpha → 0.2.3-rc.4

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 CHANGED
@@ -9,7 +9,7 @@ import { vocabulary } from '@melite/comfyui-card-kit/vocab';
9
9
  import { samplingExtra } from '@melite/comfyui-card-kit/fields';
10
10
  import { bag } from '@melite/contracts/extraKeys';
11
11
  import { coerceWireArrays } from '@melite/comfyui-card-kit';
12
- import { CALL_KEYS, DOC_FPS_DEFAULT, FILM_ONLY_KEYS, GRID_BASE_FRAMES, GRID_MAX_FRAMES, GRID_STEP_FRAMES, REF_CAPS, T4_ONLY_KEYS, assertGridLength, assertSpanGrid, deriveWindowFamily, isMediaRef, normalizeDeclaredRefs, transitionOverlap } from './timelineContract.js';
12
+ import { CALL_KEYS, CALL_TRANSITIONS, DOC_FPS_DEFAULT, FILM_ONLY_KEYS, GRID_BASE_FRAMES, GRID_MAX_FRAMES, GRID_STEP_FRAMES, REF_CAPS, bookSeconds, assertGridLength, assertSpanGrid, deriveWindowFamily, isMediaRef, normalizeDeclaredRefs, transitionOverlap } from './timelineContract.js';
13
13
  // the window families this renderer builds (three shapes:
14
14
  // t4r opener / t4_open window / t4_chain window).
15
15
  export const FAMILIES = ['t4r', 't4_open', 't4_chain'];
@@ -26,6 +26,16 @@ export const H3_RECOMMENDED_SAMPLERS = [
26
26
  "res_multistep", "res_multistep_cfg_pp", "er_sde", "seeds_2", "seeds_3",
27
27
  ];
28
28
  export const JSON_ARRAY_PARAMS = ['calls', 'audio_clips', 'keyframes'];
29
+ /** The fps rail's own bounds, one home: the row declares them and the
30
+ * internal seconds rail derives its own bounds from them (see
31
+ * fps_seconds) — a second rail must never invent a rival bound. */
32
+ export const FPS_RAIL_MIN = 1;
33
+ export const FPS_RAIL_MAX = 120;
34
+ /** The refinement window's DECLARED default — one home for the seat,
35
+ * the schema walk, and every wall/receipt that judges the unstated
36
+ * rider (the SOTA plan's researched 0.30–0.35 band; 1.0 is the
37
+ * taomate full-denoise mechanic, opt-in). */
38
+ export const REFINE_DENOISE_DEFAULT = 0.35;
29
39
  // ── the params schema — H3TimelineCard mirrored 1:1 ─────────────────────────
30
40
  // the declared field order and defaults. Bare (defaultless) keys are the
31
41
  // ABSENT / required surface (prompt required=True; image
@@ -39,6 +49,12 @@ export const JSON_ARRAY_PARAMS = ['calls', 'audio_clips', 'keyframes'];
39
49
  // (historical shape); at runtime schema() normalizes an
40
50
  // omitted key back to null so the body resolves the family's literal
41
51
  // (t4 INT 8 / t4r 8.0 — the served structural values).
52
+ /** THE OUTPUT-NAME SLUG LAW (the file-plane seat on the carrier
53
+ * below): a filename segment and nothing else — the stem lands
54
+ * inside a SaveVideo / SaveImage prefix, so no space, slash, dot,
55
+ * or case may ride it. Shared by the carrier (the walk's boundary
56
+ * refusal) and the compose tail helper at the carrier's foot. */
57
+ export const OUTPUT_NAME_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
42
58
  export const paramSchema = z.object({
43
59
 
44
60
  // for the full model, remove that") — the film-level prompt field
@@ -109,7 +125,7 @@ export const paramSchema = z.object({
109
125
  start_time: z.number().min(0).default(0).description('Start (s)'),
110
126
  duration: z.number().min(0).default(0).description('Duration (s)'),
111
127
  })).max(REF_CAPS.videos).description("Reference video trims").extra('extra', bag({ order: null, tooltip: "Per-video trims, index-paired with Reference videos — entry i slices guide i (start seconds + duration seconds) before conditioning. duration 0 = to the clip's end; an absent entry = the whole clip." })),
112
- 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." })),
128
+ 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. Conditions each window's generated voice — each clip is loaded once per window and the synthesised voice mixes UNDER a conditioned row at duck_depth_db. Not a placed line: to hear your own take, place it in audio_clips. Audio rides ref_mods too — any media kind boards the bag, be it image, video, or audio, and the system bakes each kind; a path is a path (the operator's 1:1 law); this rail is the voice seat, the bag is the identity bake." })),
113
129
 
114
130
  // mods. The pack injects them as reference tokens through ALL
115
131
  // DiT blocks on the conditioning side: no bundle-bus slot is
@@ -143,7 +159,7 @@ export const paramSchema = z.object({
143
159
  // generated voice yields under a conditioned clip at its film
144
160
  // span. −14dB is the natural mix-desk default; deeper for dense
145
161
  // dialogue, shallower when the generated voice should hold.
146
- 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)." })),
162
+ 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 conditioned row — a placed dialogue clip or a ref_audios voice (−14 is the mix-desk default; range −48–0)." })),
147
163
  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" })),
148
164
  width: z.number().description("Width").min(448).max(1344).step(32).default(1344).extra('extra', bag({ order: null, wtype: 'number', columns: 2, width: 1 })),
149
165
  height: z.number().description("Height").min(448).max(1344).step(32).default(768).extra('extra', bag({ order: null, wtype: 'number', columns: 2, width: 1 })),
@@ -178,7 +194,7 @@ export const paramSchema = z.object({
178
194
  // the walk fills it, the lawful declared kind, never a silent ??
179
195
  // in the compose). The old hardcoded 24 in both render arms played
180
196
  // a 90-frame window at 3.75s under a 5.6s bar.
181
- fps: z.number().description("Playback fps").min(1).max(120).default(DOC_FPS_DEFAULT).extra('extra', bag({ hidden: true })),
197
+ fps: z.number().description("Playback fps").min(FPS_RAIL_MIN).max(FPS_RAIL_MAX).default(DOC_FPS_DEFAULT).extra('extra', bag({ hidden: true })),
182
198
  steps: z.number().description("Steps").min(4).max(30).default(6).extra('extra', samplingExtra('steps', { tooltip: "6 for draft — the engine kernel's own calibrated count (its H3SLAAttention tooltip: use 6 steps rather than lowering sparsity; PARITY-pinned with plaguekind v7 — the 12 carried no receipt and matched neither his v7=6 nor v9=8; regolded by the 2026-10-16 upstream-parity audit); 30 standard; a boarded distill lora applies its own steps (edit them on the lora entry)" })),
183
199
 
184
200
  // needs an on/off switch, it is very unclear if it is on or off"):
@@ -260,18 +276,19 @@ export const paramSchema = z.object({
260
276
  // full-denoise mechanic). 1.0 stays STATEABLE for that mechanic;
261
277
  // the ARM 36 band arm outlaws an out-of-window default.
262
278
  // (0.05, 1]; 0 is a dead pass and refuses.
263
- refine_denoise: z.number().description("Refine denoise").min(0.05).max(1).step(0.05).default(0.35).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'number', tooltip: "The refinement window (the researched 0.30–0.35 band): pass 1's structure stays, the second pass polishes texture. Default 0.35. 1.0 = full re-denoise (the taomate full pass, opt-in). Rides on the refine rider when refine_lora is set — and as the handoff's own window when the latent-upscale route is on." })),
279
+ refine_denoise: z.number().description("Refine denoise").min(0.05).max(1).step(0.05).default(REFINE_DENOISE_DEFAULT).extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'number', tooltip: "The refinement window (the researched 0.30–0.35 band): pass 1's structure stays, the second pass polishes texture. Default 0.35. 1.0 = full re-denoise (the taomate full pass, opt-in). Rides on the refine rider when refine_lora is set — and as the handoff's own window when the latent-upscale route is on." })),
264
280
 
265
281
  // the learned-latent alternative to the SeedVR2 pixel route: the
266
282
  // vendored xmarre pack's MinimaxH3LatentUpscaler3DRefineHandoff
267
283
  // rides IN-BAND on the pass-1 joint AV latent (upscale + the
268
284
  // low-sigma refinement inside the 3D-conv kernel, audio preserved
269
- // under lock_audio). The sub-gate: route latents halve the r2v head
270
- // (1344×768 → 672×384) so pass 1 composes the quarter the kernel
271
- // was distilled on; the rider (when set) mounts in-band on the
272
- // upscaled latent. Route off (default) = the graph is byte-stable
273
- // with the pre-route estate (ARM 41).
274
- upscale_route: vocabulary(["off", "latent_2x"]).description("Latent upscale route").default("off").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'select', tooltip: "Upscale between the passes: off (default — the second pass works at full size) or latent_2x (pass 1 renders at half size, the learned upscaler doubles the latent in-band before the second pass)." })),
285
+ // under lock_audio). Pass 1 composes the STATED geometry and the
286
+ // handoff doubles ON TOP of it — armed, the render lands at 2× the
287
+ // stated grid (the half-grid stamp that rendered base tier died
288
+
289
+ // set) mounts in-band on the upscaled latent. Route off (default)
290
+ // = the graph is byte-stable with the pre-route estate (ARM 41).
291
+ upscale_route: vocabulary(["off", "latent_2x"]).description("Latent upscale route").default("off").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true", wtype: 'select', tooltip: "Upscale between the passes: off (default — the render stays at the stated size) or latent_2x (pass 1 renders the stated size and the learned upscaler doubles the latent in-band — the render lands at 2× the stated size)." })),
275
292
  // CLOSED FILE SURFACE (the operator's dropdown law — the sr_model
276
293
  // precedent above): the ONE file the estate runs — the on-disk LBH
277
294
  // v1 3D-conv bf16 checkpoint (the h3 latent weight, verified
@@ -290,7 +307,16 @@ export const paramSchema = z.object({
290
307
  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." })),
291
308
  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)." })),
292
309
  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." })),
293
- 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." })),
310
+
311
+ // BELOW the film's own 768 native canvas (the F34 plan geometry,
312
+ // 1344×768) — a super-res target below the rendered height is a
313
+ // downscale wearing the upscale seat. The floor IS the native
314
+ // height (768); the step is 24, the coarsest step that keeps
315
+
316
+ // grid from the new floor, so the served ladder survives the
317
+ // floor move byte-stable — the walk's step is the served
318
+ // quantization, never the instrument's law.
319
+ sr_resolution: z.number().description("Super-Res target").min(768).max(2160).step(24).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 (never below the film's own 768 native canvas)." })),
294
320
  // CLOSED FILE SURFACE (the operator's dropdown law — a free-text
295
321
  // weights row is a guess box): the two SeedVR2 DiT files the estate
296
322
  // actually runs (both proven in shipped _flow.json receipts: the fp16
@@ -298,7 +324,7 @@ export const paramSchema = z.object({
298
324
  // dropdown AND the membership refusal (an off-set value fails at the
299
325
  // schema door, never as a ComfyUI 400). Gated behind sr_switch like
300
326
  // every other post leaf.
301
- 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." })),
327
+ sr_model: vocabulary(["seedvr2_ema_3b_fp16.safetensors", "seedvr2_ema_3b_fp8_e4m3fn.safetensors"]).description("Super-Res model").default("seedvr2_ema_3b_fp8_e4m3fn.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/): fp8_e4m3fn 3B default (the leaner row — a 24GB card cannot hold the fp16 3B model beside a 90-frame 1080p decode), fp16 for cards with more headroom." })),
302
328
  // the R2V COMBO size mode — the engine's own vocabulary is the
303
329
 
304
330
  // ref_image_size "704x1280" against comfy_extras.nodes_minimax_h3
@@ -374,8 +400,10 @@ export const paramSchema = z.object({
374
400
  sla_stabilize_motion: z.boolean().description("SLA stabilize motion").extra('extra', bag({ order: null, group: "sla", visible_when: "sla_enabled=true", tooltip: "Untouched, this turns on for every model except the t4r openers — those run with it off." })),
375
401
  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." })),
376
402
  // ── the sharpen leaves (compose: only EXPLICITLY-set leaves patch
377
- // ImageSharpenKJ's grouped dict — bare emission defaults do NOT
378
- // change a run that never sets them). VISIBILITY rides the
403
+ // the installed node's V3 combo wires (GAPS-1/F9 cure — the old
404
+ // flat grouped dict matched no option key, so the finalize dropped
405
+ // `method` outright); bare emission defaults do NOT change a run
406
+ // that never sets them). VISIBILITY rides the
379
407
  // declaration's own visible_when grammar (&-ANDed guards, |-SET
380
408
  // values) — no hand-rolled predicates anywhere.
381
409
  sharpen_method: vocabulary(["rcas", "adaptive_usm", "high_pass", "deconvolution"]).default("rcas").description("Sharpen Method").extra('extra', bag({ order: null, group: 'second_pass', visible_when: "second_pass_enabled=true&sharpen_enabled=true", wtype: 'select' })),
@@ -410,7 +438,41 @@ export const paramSchema = z.object({
410
438
  // 10 seconds of mush. No default, no user face: hidden; the
411
439
  // compose owns the derivation (render loop restates it
412
440
  // unconditionally from the actual window length).
413
- fps_seconds: z.number().description("Clip seconds (fps rail — internal, derived from the window length at compose)").min(1).max(60).extra('extra', bag({ hidden: true })),
441
+
442
+ // burn: `$.fps_seconds expected number >= 1 but got 0.917`). The old
443
+ // .min(1).max(60) was a hand-picked second-count laid over two laws
444
+ // that already bound this quotient: the grid's 22..362 frames and the
445
+ // fps rail's 1..120. The grid's own SHORTEST window is 22f = 0.917s at
446
+ // the doc default 24fps, so the floor refused every grid-legal opener;
447
+ // the ceiling refused a grid-legal 362f window on a 1fps doc (362s).
448
+ // The bounds below are DERIVED from those two laws (never authored
449
+ // numbers): they refuse only what the laws already make impossible —
450
+ // the 400-class guard against a zero/negative clock on the wire —
451
+ // while every grid-legal window at every legal fps passes.
452
+ fps_seconds: z.number().description("Clip seconds (fps rail — internal, derived from the window length at compose)").min(bookSeconds(GRID_BASE_FRAMES, FPS_RAIL_MAX)).max(bookSeconds(GRID_MAX_FRAMES, FPS_RAIL_MIN)).extra('extra', bag({ hidden: true })),
453
+ // ── THE OUTPUT-NAME SEAT, FILE PLANE (queue 12's owed half,
454
+
455
+ // offering the ai the ability to name the actual outputs to make
456
+
457
+ // registry row cards-output-name-label) named the DISPLAY rows
458
+ // only — the settled file itself stayed `h3_t4_film_00001_.mp4`,
459
+
460
+ // developer-repo copy index the end user never sees. THIS seat is
461
+ // the file plane: the declared param walks the compose (the
462
+ // registry's reserved lift spares keys the card declares —
463
+ // runsRegistry.ts), and the renderer threads the stem into every
464
+ // DELIVERABLE save prefix (`h3_t4_film`, `extend_film`,
465
+ // `reshoot_warp`, `reshoot_orbit`) so the artifact is BORN named:
466
+ // run dir, gallery, downloads, and every film-lead finder
467
+ // (filmLead.ts + its three mirrors) carry it. Windows/x0/x1/audio
468
+ // stems stay machinery names — chain intermediates, not the
469
+ // outputs the operator means. SLUG LAW: a filename segment and
470
+ // nothing else — lowercase alnum + hyphen, 64 max; no separator
471
+ // can smuggle a path escape into the `${runId}/` prefix wiring.
472
+
473
+ // slug rode its own 'naming' tab — a SIXTH tab for ONE row. It
474
+ // rides General now (no group extra), the tab dies at the rail.
475
+ output_name: z.string().max(64).pattern(OUTPUT_NAME_SLUG_RE).description("Output name").extra('extra', bag({ order: null, wtype: 'text', tooltip: "Names the delivered files: the composed film and re-shoot plates are BORN with this stem beside the machinery prefix (h3_t4_film_<name>_00001_.mp4). Absent = the machinery name, byte-frozen." })),
414
476
  // THE LEGACY ALIASES (renderer-era spellings of the mod switches)
415
477
  // — gate-admitted for old drafts, never user surface: the MODS
416
478
 
@@ -422,6 +484,24 @@ export const paramSchema = z.object({
422
484
  // here is dead surface the estate wtype judge refuses.)
423
485
  image_name: z.string().role('path').description("Guide image (renderer alias)").extra('extra', bag({ hidden: true, tooltip: "The renderer's guide-image spelling — gate-admitted for old docs; the rail's First frame is the user face." })),
424
486
  });
487
+ /** The composed prefix tail for a doc's output_name — `_<slug>` when
488
+ * spelled, '' when absent. The DELIVERABLE prefix sites thread this
489
+ * (the film `h3_t4_film`, the extend film `extend_film`, the
490
+ * re-shoot plates `reshoot_warp` / `reshoot_orbit`); a stem that
491
+ * escaped the boundary walk (a legacy draft, a hand-built doc)
492
+ * refuses HERE loud, naming the law — a bad stem must never reach
493
+ * a filename. An empty string is the label seam's silence law:
494
+ * no stem, no tail, no refusal. */
495
+ export function outputNameTailOf(p) {
496
+ const stem = p['output_name'];
497
+ if (stem === undefined || stem === null || stem === '')
498
+ return '';
499
+ if (typeof stem !== 'string' || stem.length > 64 || !OUTPUT_NAME_SLUG_RE.test(stem)) {
500
+ throw new Error('h3-timeline: output_name must be a filename slug (lowercase letters, digits, hyphens; 64 max) — ' +
501
+ JSON.stringify(stem) + ' cannot name a delivered file');
502
+ }
503
+ return '_' + stem;
504
+ }
425
505
  /** Schemastery objects are lenient (unknown/missing keys ride); the
426
506
  * family-admission laws are the renderer's own validators, ported:
427
507
  * unknown variant + family-conditional key admission on EXPLICIT
@@ -458,6 +538,12 @@ export const refinePlaneSchema = z.object(Object.fromEntries(REFINE_PLANE_KEYS.m
458
538
  }
459
539
  return [k, knob];
460
540
  })));
541
+ /** The wire tolerance for interpolate_enabled: the bench add-door's
542
+ * "false"/"true" string literal folds to a boolean before the walk;
543
+ * any other string refuses loud. Booleans and every other key pass
544
+ * verbatim.
545
+ * @param raw the pre-walk params record
546
+ * @returns the record with interpolate_enabled narrowed to boolean */
461
547
  export const coerceWireBoolean = (raw) => {
462
548
  if (typeof raw.interpolate_enabled === 'string') {
463
549
 
@@ -493,6 +579,15 @@ export function assertKeyframeRowShape(rows) {
493
579
  }
494
580
  }
495
581
  }
582
+ /** The compose-admission walk over a raw doc (the card gate's
583
+ * model_validator port): array and boolean wire tolerances restored,
584
+ * keyframe rows shape-judged, shot rows judged (per-call vocabulary,
585
+ * int spans, tiling, seam/grid/guide gates), the window family
586
+ * derived, and the family-conditional key gates run. A refusal names
587
+ * the row and the cure; a passing doc returns the walked params with
588
+ * the __steps_pinned/__shift_pinned stamps added.
589
+ * @param v the raw doc (absent = the fresh-card draft)
590
+ * @returns the walked params record the compose reads */
496
591
  export function schema(v) {
497
592
  const raw = (v ?? {});
498
593
  if (raw.calls !== undefined && !Array.isArray(raw.calls)) {
@@ -607,6 +702,16 @@ export function schema(v) {
607
702
  }
608
703
  }
609
704
  const transition = typeof c.transition === 'string' ? c.transition : undefined;
705
+ // THE SEAM VOCABULARY GATE (the carry+keyframe audit's owed
706
+ // wall): a transition outside the three this timeline
707
+ // composes ('cut' | 'extend' | 'carry+keyframe') is a typo or
708
+ // a foreign dialect — transitionOverlap would silently treat
709
+ // ANY non-'cut' string as a carry join, so a typo'd seam
710
+ // composed as carry with no refusal. Judge at the walk, name
711
+ // the value and the vocabulary.
712
+ if (transition !== undefined && !CALL_TRANSITIONS.includes(transition)) {
713
+ throw new Error(`calls[${i}].transition '${transition}' is not a seam this timeline composes — the vocabulary is ${CALL_TRANSITIONS.map((t) => `'${t}'`).join(', ')} (unstated = carry)`);
714
+ }
610
715
  // THE GRID GATE (§26, the walk arm): a call's knobs.length pin
611
716
  // bypasses every snap arm downstream — validate at the walk so
612
717
  // `validate` refuses what the engine would kill at GPU cost.
@@ -731,33 +836,18 @@ export function schema(v) {
731
836
  // inert for multi-call chains — spans own the film)
732
837
  }
733
838
  const bad = (keys) => keys.filter((kk) => explicit.has(kk)).sort();
734
- if (variant === 't4r') {
735
- const b = bad(T4_ONLY_KEYS);
736
- if (b.length) {
737
-
738
- // §CURES-OWED 6 / timeline-calls-burn §CURES-OWED 7) THE
739
- // HONEST-VOICE RIDER, per the cured unknownQuantVoice precedent
740
- // (web-kit/contracts laneRelations: a refusal names the SEAM
741
- // and the repair, not just the fact). The spine
742
- // `h3_window(t4r): unsanctioned inject keys: <keys>` stays
743
- // byte-identical — the B5 admission clause and the pick verdict
744
- // quote it verbatim, the walls grep it — the tail only extends
745
- // it. The writer: the keys were staged lawfully on the doc's
746
- // Layer-A plane (the serializer's emit dialects or a recipe
747
- // stamp) and the guide seats re-derived t4r under them. The
748
- // repair is one gesture: a stating commit through the studio
749
- // re-derives the family and unstamps the residue in the same
750
- // save (the B2 flip writer), or the named keys null-delete at
751
- // the bench patch door. The film-only sibling below keeps its
752
- // own voice — its writer is a stale duck row, not this emit
753
- // (follow-up, not this scope).
754
- throw new Error(`h3_window(t4r): unsanctioned inject keys: ${b.join(', ')}`
755
- + ` — the studio's Layer-A emit carries lane-dead post keys (the family re-derived t4r under a legal stamp);`
756
- + ` the repair is one gesture: restate the doc through the studio`
757
- + ` (the commit re-derives the family and unstamps the residue)`
758
- + ` or null the named keys at the patch door`);
759
- }
760
- }
839
+
840
+ // gate-11 burn: the compose gate refused a lawful Final-Cut doc
841
+ // with four unactionable lines, because the t4r render arm wired
842
+ // no pixel post chain). The arm now mounts the chain
843
+ // (actions.ts renderH3Window hoists it above the family branch),
844
+ // so every finish key fires on every lane and the walk has no
845
+ // lane-conditional refusal to speak. The old T4_ONLY_KEYS set and
846
+ // its t4rInjectRefusal spine are deleted from timelineContract.ts
847
+ // — do not reintroduce a lane dead-letter gate here; cure the
848
+ // renderer instead, and let THIS walk's own gates judge what a
849
+ // doc shape can honor (the film-only gate below, the route-master
850
+ // gate, the guide seats).
761
851
  // (B6, timeline-calls-burn §CURES-OWED 5 / ui-truth-gap #4's walk
762
852
  // leg) THE FILM-ONLY GATE, the t4r gate's sibling: FILM_ONLY_KEYS
763
853
  // are read in exactly one seat — computeFilmMix's manifest, inside
@@ -772,6 +862,28 @@ export function schema(v) {
772
862
  if (b.length)
773
863
  throw new Error(`h3_window(${variant}): film-only inject keys: ${b.join(', ')}`);
774
864
  }
865
+
866
+ // run-d96317409da9: the doc stated the sub-gate alone, the ledger's
867
+ // own graph_receipt dropped `upscale_route`, the handoff never
868
+ // composed, and the film rendered the plain 1344×768 pass). The
869
+ // latent-upscale route is a SUB-GATE: its one consumer (the
870
+ // MinimaxH3LatentUpscaler3DRefineHandoff mount, actions.ts
871
+ // upscaleOn) reads it only behind the second-pass master, so a
872
+ // stated latent_2x beside an absent or false master composes into
873
+ // NO node — the inert-knob admission the misconfiguration law
874
+ // bans. Self-contained judge (two walked keys, zero engine truth),
875
+ // so it rides the walk beside the t4r and film-only gates; the
876
+ // upscale BAG's engine-side referent (the chain store) stays at the
877
+
878
+ // gate is the SAME shape on every lane — a t4r doc that states the
879
+ // route without its master is refused here exactly like an open
880
+ // or film doc, because the t4r arm mounts the same handoff.
881
+ if (explicit.has('upscale_route') && out.upscale_route === 'latent_2x' && out.second_pass_enabled !== true) {
882
+ throw new Error(`h3_window(${variant}): upscale_route 'latent_2x' fires nothing without its master — the latent handoff `
883
+ + `(MinimaxH3LatentUpscaler3DRefineHandoff) composes only behind second_pass_enabled=true; the sub-gate alone `
884
+ + `rode the doc, armed no node, and rendered the plain pass (run-d96317409da9's burn). `
885
+ + `Arm the master beside the route, or turn the route off`);
886
+ }
775
887
  // THE STEPS-PIN STAMP (007-H3-LoRA-PLANE L3): whether the caller
776
888
  // pinned steps is a fact only this walk owns (the raw keys —
777
889
  // defaults materialize downstream and the film build can no
@@ -0,0 +1,31 @@
1
+ /** The arms' source vocabulary: where the second pass reads its
2
+ * latents or pixels from. */
3
+ export declare const SECOND_PASS_SOURCES: readonly ["same-run", "prior-run", "decoded"];
4
+ export type SecondPassSource = (typeof SECOND_PASS_SOURCES)[number];
5
+ /** The doc-side claims that arm the seat (the edit door's own
6
+ * spellings; undefined/false/empty = the arm is not stated). */
7
+ export interface SecondPassClaim {
8
+ readonly refine?: boolean;
9
+ readonly chain_run?: string;
10
+ }
11
+ /** The refinement window every second-pass denoise rides
12
+ * (partial only; 1 is the full-denoise pole this law refuses). */
13
+ export declare const SECOND_PASS_WINDOW: readonly [0.05, 1];
14
+ /** The full-noise clause shared by every arm's refusal — the
15
+ * never-a-re-render law in the arm's own word. */
16
+ export declare function fullNoiseClause(arm: 'refine' | 'upscale'): string;
17
+ /** The shared reason the full-noise law refuses (the learned
18
+ * latent the pole would discard). */
19
+ export declare const FULL_NOISE_REASON = "a full-noise sigma discards the learned upscaled latent";
20
+ /** Which arm a claim states (the first in the seat's own order);
21
+ * undefined when the doc states no second pass at all. */
22
+ export declare function secondPassSourceOf(claim: SecondPassClaim): SecondPassSource | undefined;
23
+ /**
24
+ * THE ONE-SEAT LAW: refuses a doc stating two second-pass arms,
25
+ * naming the seat (the shared door every spelling is an arm of).
26
+ * @param claim the doc's second-pass claims (refine switch, chain_run)
27
+ * @param voice the refusing door's own prefix ("h3-timeline edit")
28
+ * @throws when both the same-run and prior-run arms are stated
29
+ */
30
+ export declare function refuseCompetingSecondPass(claim: SecondPassClaim, voice: string): void;
31
+ //# sourceMappingURL=secondPass.d.ts.map
@@ -0,0 +1,59 @@
1
+ // THE SECOND_PASS GATE LAW (the unification's first increment):
2
+ // the family's second-pass spellings — the edit door's refine
3
+ // switch (same-run latents, the learned handoff), the film
4
+ // handoff's upscale_route latent_2x (same-run, the window arm), a
5
+ // stated chain_run on the edit door (prior-run checkpoints, the
6
+ // deferred loop), and the postImage finish limb (decoded pixels) —
7
+ // are ARMS of ONE seat. This module is that seat's shared
8
+ // vocabulary and refusal laws; the arms keep their own nodes (a
9
+ // vocabulary and gate unification, NEVER a graph change — the
10
+ // byte-exact frozen suites stay green).
11
+ //
12
+ // THE ONE-SEAT LAW: one doc states ONE second-pass arm. Stating
13
+ // two refuses loud, naming the seat itself — the pair-wise
14
+ // refusals the doors carried collapse into this one law.
15
+ //
16
+ // THE FULL-NOISE LAW: a second pass is a refine or an upscale,
17
+ // never a re-render — a full-noise sigma discards the learned
18
+ // upscaled latent (the vendored refinement runs 0 <= sigmas[0] < 1
19
+ // STRICT and throws otherwise). A full-denoise re-render is a
20
+ // reshoot, and the reshoot door exists.
21
+ /** The arms' source vocabulary: where the second pass reads its
22
+ * latents or pixels from. */
23
+ export const SECOND_PASS_SOURCES = ['same-run', 'prior-run', 'decoded'];
24
+ /** The refinement window every second-pass denoise rides
25
+ * (partial only; 1 is the full-denoise pole this law refuses). */
26
+ export const SECOND_PASS_WINDOW = [0.05, 1];
27
+ /** The full-noise clause shared by every arm's refusal — the
28
+ * never-a-re-render law in the arm's own word. */
29
+ export function fullNoiseClause(arm) {
30
+ return `a second pass is ${arm === 'upscale' ? 'an' : 'a'} ${arm}, never a re-render`;
31
+ }
32
+ /** The shared reason the full-noise law refuses (the learned
33
+ * latent the pole would discard). */
34
+ export const FULL_NOISE_REASON = 'a full-noise sigma discards the learned upscaled latent';
35
+ /** Which arm a claim states (the first in the seat's own order);
36
+ * undefined when the doc states no second pass at all. */
37
+ export function secondPassSourceOf(claim) {
38
+ if (claim.refine === true)
39
+ return 'same-run';
40
+ if (typeof claim.chain_run === 'string' && claim.chain_run.trim() !== '')
41
+ return 'prior-run';
42
+ return undefined;
43
+ }
44
+ /**
45
+ * THE ONE-SEAT LAW: refuses a doc stating two second-pass arms,
46
+ * naming the seat (the shared door every spelling is an arm of).
47
+ * @param claim the doc's second-pass claims (refine switch, chain_run)
48
+ * @param voice the refusing door's own prefix ("h3-timeline edit")
49
+ * @throws when both the same-run and prior-run arms are stated
50
+ */
51
+ export function refuseCompetingSecondPass(claim, voice) {
52
+ const stated = secondPassSourceOf(claim);
53
+ if (stated !== 'same-run')
54
+ return;
55
+ if (!(typeof claim.chain_run === 'string' && claim.chain_run.trim() !== ''))
56
+ return;
57
+ throw new Error(`${voice}: the refine switch under an upscale — two second-pass arms on the ONE second-pass seat (the switch arms the same-run handoff on THIS chain, the upscale resumes a PRIOR run's checkpointed scenes; the doc's duplicate-2x resolved into ONE door — the seat takes one arm per doc). Leave refine off`);
58
+ }
59
+ //# sourceMappingURL=secondPass.js.map
package/lib/swap.js CHANGED
@@ -1,4 +1,5 @@
1
- import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
1
+ import { resolveCarryOverlap } from './timelineContract.js';
2
+ import { contexMaskedTarget, loadVideo, renderMaskedEditChain, resolvePlanTier, sheetRefSlots } from './chainEdit.js';
2
3
  /** The swap entry's required media + text seats (the reshoot idiom:
3
4
  * an armed doc with an empty seat refuses loud naming the seat). */
4
5
  const REQUIRED_SEATS = [
@@ -8,8 +9,40 @@ const REQUIRED_SEATS = [
8
9
  ['mask', 'ONE staged PNG from the track-card run — the pixel-max UNION of its grown per-frame masks is recommended (per-frame motion rides the mannequin; the edit-latent + masked-target mask, reference GrowMaskWithBlur expand 40)'],
9
10
  ['swap_prompt', 'the swap action text (agent-composed, user-confirmed — the R2V prompt seat; the estate has no in-graph describers)'],
10
11
  ];
11
- const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
12
- const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
12
+ /** Reads one required seat NARROWED by its own refusal — the seat
13
+ * is a string or the door never composes (no fallback arm exists:
14
+ * a validated seat re-read through a forgiving helper would be a
15
+ * second, weaker validator below the law — a silent error). */
16
+ const requiredSeat = (entry, seat, what) => {
17
+ const v = entry[seat];
18
+ if (typeof v !== 'string' || v.trim() === '') {
19
+ throw new Error(`h3-timeline replace: '${seat}' names no media — ${what}; a swap needs all five seats bound (source_clip, still, mannequin, mask, swap_prompt)`);
20
+ }
21
+ return v;
22
+ };
23
+ /** An optional number seat: absent falls to the documented default;
24
+ * a stated non-number REFUSES — a defaulting fallback would swallow
25
+ * a bypassed door's wrong-typed value as a silent error. */
26
+ const statedNumber = (p, k, d) => {
27
+ const v = p[k];
28
+ if (v === undefined)
29
+ return d;
30
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
31
+ throw new Error(`h3-timeline replace: '${k}' is stated as ${JSON.stringify(v)} — a number seat carries a number (absent falls to ${d}); a wrong-typed value never silently defaults`);
32
+ }
33
+ return v;
34
+ };
35
+ /** An optional text seat: absent is the lawful unstated ('' rides
36
+ * on); a stated non-string REFUSES. */
37
+ const seatString = (p, k) => {
38
+ const v = p[k];
39
+ if (v === undefined)
40
+ return '';
41
+ if (typeof v !== 'string') {
42
+ throw new Error(`h3-timeline replace: '${k}' is stated as ${JSON.stringify(v)} — a text seat carries text; a wrong-typed value never silently reads as unbound`);
43
+ }
44
+ return v;
45
+ };
13
46
  /** The swap renderer: validates the bound entry, then composes the
14
47
  * masked-edit chain per the reference map above. The film path
15
48
  * never reaches here (the card branches ONLY on a non-empty replace
@@ -21,73 +54,69 @@ const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
21
54
  * @param g the run's graph builder
22
55
  * @param runId the run tree's id (the assemble filename rides it) */
23
56
  export function renderH3Swap(entry, p, facts, g, runId) {
24
- for (const [seat, what] of REQUIRED_SEATS) {
25
- const v = entry[seat];
26
- if (typeof v !== 'string' || v.trim() === '') {
27
- throw new Error(`h3-timeline replace: '${seat}' names no media — ${what}; a swap needs all five seats bound (source_clip, still, mannequin, mask, swap_prompt)`);
28
- }
29
- }
57
+ // NO FALLBACK READS: every required seat narrows through its own
58
+ // refusal; optional seats refuse wrong-typed stated values.
59
+ const sourceClipSeat = requiredSeat(entry, 'source_clip', REQUIRED_SEATS[0][1]);
60
+ const stillSeat = requiredSeat(entry, 'still', REQUIRED_SEATS[1][1]);
61
+ const mannequinSeat = requiredSeat(entry, 'mannequin', REQUIRED_SEATS[2][1]);
62
+ const maskSeat = requiredSeat(entry, 'mask', REQUIRED_SEATS[3][1]);
63
+ const swapPromptSeat = requiredSeat(entry, 'swap_prompt', REQUIRED_SEATS[4][1]);
30
64
  const keepAudio = entry.keep_audio !== false;
31
- const seed = num(entry, 'seed', 0);
32
- const steps = num(entry, 'steps', 6);
33
- const clipSeconds = num(entry, 'clip_seconds', 6);
34
- const resolution = str(entry, 'resolution') || '736p';
65
+ const seed = statedNumber(entry, 'seed', 0);
66
+ const steps = statedNumber(entry, 'steps', 6);
67
+ const clipSeconds = statedNumber(entry, 'clip_seconds', 6);
68
+ const resolution = resolvePlanTier(entry, p);
35
69
  // ── the staged media (the R0 cards' artifacts: the source clip,
36
70
  // the still, the track card's mannequin + grown mask) ──
37
- const [srcFrames, srcAudio] = loadVideo(g, str(entry, 'source_clip'));
38
- const stillImg = g.node('LoadImage', { image: str(entry, 'still') }).out(0);
71
+ const [srcFrames, srcAudio] = loadVideo(g, sourceClipSeat);
72
+ const stillImg = g.node('LoadImage', { image: stillSeat }).out(0);
39
73
  const maskOf = g.node('ImageToMask', {
40
- image: g.node('LoadImage', { image: str(entry, 'mask') }).out(0),
74
+ image: g.node('LoadImage', { image: maskSeat }).out(0),
41
75
  channel: 'red',
42
76
  }).out(0);
43
- const [mannequin] = loadVideo(g, str(entry, 'mannequin'));
77
+ const [mannequin] = loadVideo(g, mannequinSeat);
44
78
  renderMaskedEditChain(g, {
45
79
  p, facts,
46
80
  clipSeconds,
47
- overlapFrames: num(entry, 'overlap_frames', 39),
81
+ overlapFrames: resolveCarryOverlap(entry),
48
82
  resolution, seed, steps,
49
- roles: str(entry, 'roles'),
50
- sourceClip: str(entry, 'source_clip'),
83
+ roles: seatString(entry, 'roles'),
84
+ sourceClip: sourceClipSeat,
51
85
  windowStart: 0,
52
86
  picture1: stillImg,
53
87
  srcFrames, srcAudio,
54
88
  // the ignored literal fallback — the plan node's SOURCE-SLICED
55
89
  // shots ride plan_json_input (the swap's own semantics)
56
- planJson: JSON.stringify({ shots: [{ id: 'swap', prompt: str(entry, 'swap_prompt') }] }),
90
+ planJson: JSON.stringify({ shots: [{ id: 'swap', prompt: swapPromptSeat }] }),
57
91
  planFromSource: true,
58
92
  denoise: 1,
59
93
  assemble: {
60
94
  audioSource: keepAudio ? 'source' : 'generated',
61
95
  filename: `${runId}/swap`,
62
96
  },
63
- body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
97
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio, refImages }) => {
64
98
  // ── the masked edit body: the still anchors identity, the
65
99
  // mannequin carries motion, the staged PNG masks the edit ──
66
100
  const r2v = g.node('MiniMaxH3ReferenceToVideo', {
67
- prompt: str(entry, 'swap_prompt'),
101
+ prompt: swapPromptSeat,
68
102
  width: cur.out(8), height: cur.out(9), length: cur.out(6),
69
103
  ref_image_size: 'match',
70
104
  clip, vae: vaeVideo, audio_vae: vaeAudio,
71
105
  'ref_images.ref_image_0': stillImg,
72
106
  'ref_videos.ref_video_0': mannequin,
73
107
  'ref_video_audios.ref_video_audio_0': mutedChainAudio,
108
+ // THE SHEET (P0-1): the still owns slot 0 — the declared
109
+ // sheet follows it, the same input-slot grammar as gen.
110
+ ...sheetRefSlots(refImages, 1),
74
111
  });
75
112
  const slice = g.node('H3SourceSlice', {
76
113
  source_fps: 24, crop: 'center',
77
114
  state: cur.out(0), latent: r2v.out(1),
78
115
  audio_vae: vaeAudio, source_frames: srcFrames, source_audio: sliceAudio,
79
116
  });
80
- const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
81
- grow: 0, keep_audio: keepAudio, megapixels: 0,
82
- vae: vaeVideo, images: slice.out(0), mask: maskOf,
83
- audio_vae: vaeAudio, audio: slice.out(1),
84
- }).out(0);
85
- const target = g.node('MiniMaxH3ContexMaskedTarget', {
86
- mask_meaning: 'white = generate',
87
- audio_mode: keepAudio ? 'preserve source audio' : 'generate all audio',
88
- mask_conversion: 'H3 exact (causal/token max)',
89
- target_latent: edit, mask: maskOf,
90
- }).out(0);
117
+ const target = contexMaskedTarget(g, { vaeVideo, vaeAudio }, {
118
+ frames: slice.out(0), audio: slice.out(1), mask: maskOf, keepAudio,
119
+ });
91
120
  return { conditioning: r2v.out(0), targetLatent: target };
92
121
  },
93
122
  });