@melite/models-h3 0.2.0-alpha → 0.2.2-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/refine.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { chainSaveBoundaries, concatSavedFilms, filmJoinAudio } from './actions.js';
2
2
  import { h3MaskedEditPlane, loadVideo } from './chainEdit.js';
3
- import { MAX_COMPOSED_WINDOWS } from './timelineContract.js';
3
+ import { DOC_FPS_DEFAULT, MAX_COMPOSED_WINDOWS, SEAM_OVERLAP_FRAMES } from './timelineContract.js';
4
4
  /** The learned 3D-conv upscale weights (the schema's upscale_model
5
5
  * seat carries this same single option — one file, one spelling, no
6
6
  * hand-spelled alternatives). */
@@ -18,6 +18,15 @@ export const REFINE_2X_OOM_FRAMES = 141;
18
18
 
19
19
 
20
20
  export const REFINE_DEFAULT_CLIP_SECONDS = 3.75;
21
+ /** The refine auto-tile's default carried overlap, in frames at the
22
+ * film clock — the film's own seam (SEAM_OVERLAP_FRAMES), which is
23
+ * also token-exact (5, 22, 39 …), so the default auto-tile takes the
24
+ * carry face: the windows chain through the film's own latent
25
+ * continuation across every join. Imported, never hand-typed
26
+ * (refine-window audit D1: the card must never carry a hand-typed
27
+ * copy of a measured constant — and the overlap that matches the
28
+ * generation seam grid is the family contract's own number). */
29
+ export const REFINE_DEFAULT_OVERLAP_FRAMES = SEAM_OVERLAP_FRAMES;
21
30
  /** The refine entry's required seats (the reshoot idiom: an armed
22
31
  * doc with an empty seat refuses loud naming the seat). */
23
32
  const REQUIRED_SEATS = [
@@ -35,6 +44,35 @@ export function refineArmed(p) {
35
44
  const bag = p.refine;
36
45
  return Array.isArray(bag) && bag.length > 0;
37
46
  }
47
+ /** One entry's dials, read with the arm's own defaults — ONE owner
48
+ * for the single-window arm, the bag walk and the carry face.
49
+ * @param entry the refine entry
50
+ * @returns the dial set its window renders under (denoise refuses at
51
+ * or above 1: a second pass is a refine, never a re-render) */
52
+ const refineDials = (entry) => {
53
+ const denoise = num(entry, 'denoise', 0.32);
54
+ if (denoise >= 1) {
55
+ throw new Error(`h3-timeline refine: denoise ${denoise} >= 1 — a second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; a full-noise sigma discards the learned upscaled latent and the vendored node throws — that is a reshoot, and the reshoot door exists)`);
56
+ }
57
+ return {
58
+ denoise,
59
+ seed: num(entry, 'seed', 0),
60
+ steps: num(entry, 'steps', 6),
61
+ upMode: entry['mode'] ?? 'scale by multiplier',
62
+ upScale: entry['scale'] ?? 2.0,
63
+ };
64
+ };
65
+ /** An entry's two media seats, bound or the door refuses loud naming
66
+ * the seat (the reshoot idiom: an armed doc never rides an empty seat).
67
+ * @param entry the refine entry */
68
+ const requireRefineEntry = (entry) => {
69
+ for (const [seat, what] of REQUIRED_SEATS) {
70
+ const v = entry[seat];
71
+ if (typeof v !== 'string' || v.trim() === '') {
72
+ throw new Error(`h3-timeline refine: '${seat}' names no media — ${what}; a refine needs both seats bound (source_clip, refine_prompt)`);
73
+ }
74
+ }
75
+ };
38
76
 
39
77
 
40
78
 
@@ -44,122 +82,123 @@ export function refineArmed(p) {
44
82
 
45
83
 
46
84
 
47
-
48
-
49
-
50
-
51
-
52
-
53
- export function renderH3RefineWindow(entry, p, facts, g, seat) {
54
- for (const [seat, what] of REQUIRED_SEATS) {
55
- const v = entry[seat];
56
- if (typeof v !== 'string' || v.trim() === '') {
57
- throw new Error(`h3-timeline refine: '${seat}' names no media — ${what}; a refine needs both seats bound (source_clip, refine_prompt)`);
58
- }
59
- }
60
- const denoise = num(entry, 'denoise', 0.32);
61
- if (denoise >= 1) {
62
- throw new Error(`h3-timeline refine: denoise ${denoise} >= 1 — a second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; a full-noise sigma discards the learned upscaled latent and the vendored node throws — that is a reshoot, and the reshoot door exists)`);
85
+ const judgeRefineWindow = (cap, dials) => {
86
+ const sameSize = dials.upMode === 'scale by multiplier' && dials.upScale < 2;
87
+ if (!sameSize && cap > REFINE_2X_OOM_FRAMES) {
88
+ const named = dials.upMode === 'scale by multiplier' ? `${dials.upScale}x` : dials.upMode;
89
+ throw new Error(`h3-timeline refine: a ${cap} f window at ${named} — the 2x pass was measured OOM at ${REFINE_2X_OOM_FRAMES} f and green at ${REFINE_DEFAULT_CLIP_SECONDS * 24} f (2688×1536, 48 kHz; H3 memory grows with the window, so a wider window cannot fit — the ceiling belongs to the WINDOW, whichever sizing mode upsizes). Cut clip_seconds to ${(REFINE_2X_OOM_FRAMES / 24).toFixed(2)} s or less and cover the rest window by window, or lower scale to 1 for a same-size pass`);
63
90
  }
64
- const seed = num(entry, 'seed', 0);
65
- const steps = num(entry, 'steps', 6);
66
-
67
- // three sizing modes and a [1, 4] multiplier. A stated seat rides
68
- // verbatim (the knob bounds are the card's own); absent keeps the
69
- // shipped 2x so every existing doc composes byte-identically.
70
- const upMode = entry['mode'] ?? 'scale by multiplier';
71
- const upScale = entry['scale'] ?? 2.0;
72
- // ── THE WINDOW (F24's cure, round 6): a refine refines a WINDOW of
73
-
74
- // frame of the source and hand the full latent to the 2x handoff,
75
- // so any clip past ~90 f died engine-side (141 f OOM, §13.2). The
76
- // window is the loader's own two seats: frame_load_cap stops the
77
- // read and skip_first_frames offsets it — VHS trims the soundtrack
78
- // by the same window (load_video_nodes.py: `start_time =
79
- // skip_first_frames * target_frame_time`, `lazy_get_audio(video,
80
- // start_time, frame_load_cap * target_frame_time)`), so the encode
81
- // seats read the WINDOW's frames and the WINDOW's audio, in sync.
82
- // A long film is covered by advancing start_seconds window by
83
- // window (the card's section states the stepping law).
84
- const clipSeconds = seat.cap / 24;
85
- if (!Number.isInteger(seat.cap) || seat.cap < 1) {
86
- throw new Error(`h3-timeline refine: a ${seat.cap} f window — a refine window needs frames (the loop's cap is the loader's frame_load_cap at 24 fps; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
87
- }
88
- if (!Number.isInteger(seat.skip) || seat.skip < 0) {
89
- throw new Error(`h3-timeline refine: a window starting at frame ${seat.skip} — a window starts at or after the clip's first frame (the loop's skip is the loader's skip_first_frames)`);
90
- }
91
- const windowFrames = seat.cap;
92
- const skipFrames = seat.skip;
93
-
94
- // the measured OOM is a function of the WINDOW first and the upscale
95
- // factor second — H3's memory grows with the frame count through the
96
- // learned 3D upscaler and the sampler. The first cut guarded only
97
- // `scale by multiplier` ≥ 2, so a target-dimensions or megapixels
98
- // window walked past the same ceiling into the measured OOM with no
99
- // refusal. Only a same-size multiplier pass (< 2, the capacity cure)
100
- // is exempt: its upscaler is the identity, which is what made 144 f
101
- // fit at 1x. The other two modes size from the source and cannot be
102
- // judged ≤ 1x before the read, so they take the ceiling.
103
- const sameSize = upMode === 'scale by multiplier' && upScale < 2;
104
- if (!sameSize && windowFrames > REFINE_2X_OOM_FRAMES) {
105
- const named = upMode === 'scale by multiplier' ? `${upScale}x` : upMode;
106
- throw new Error(`h3-timeline refine: a ${windowFrames} f window at ${named} — the 2x pass was measured OOM at ${REFINE_2X_OOM_FRAMES} f and green at ${REFINE_DEFAULT_CLIP_SECONDS * 24} f (2688×1536, 48 kHz; H3 memory grows with the window, so a wider window cannot fit — the ceiling belongs to the WINDOW, whichever sizing mode upsizes). Cut clip_seconds to ${(REFINE_2X_OOM_FRAMES / 24).toFixed(2)} s or less and cover the rest window by window, or lower scale to 1 for a same-size pass`);
107
- }
108
- // ── the staged media (the shared loader law, force-rate-24 VHS —
109
- // never a private LoadVideo pair) + the family's own plane ──
110
- // (the REQUIRED_SEATS loop above proved source_clip a non-empty
111
- // string — the cast restates the proven, never a fallback: there
112
- // is no default clip, and the sibling str() fallback would be a
113
- // dead branch here, uncovered by any honest door)
114
- const [srcFrames, srcAudio] = loadVideo(g, entry['source_clip'], windowFrames, skipFrames);
115
- const { sigmaModel, samplerSel, clip, vaeVideo, vaeAudio } = h3MaskedEditPlane(g, p, facts, clipSeconds);
116
- // ── the split-stream encode (the node's own contract:
117
- // _resolve_h3_sources rebuilds native joint AV from plain 24ch
118
- // video + the matching audio latent) ──
119
- const videoLatent = g.node('VAEEncode', { pixels: srcFrames, vae: vaeVideo }).out(0);
120
- const audioLatent = g.node('VAEEncodeAudio', { audio: srcAudio, vae: vaeAudio }).out(0);
91
+ };
92
+ /** THE JOINT AV TARGET — the estate's one source→nested-AV
93
+ * constructor, the same three nodes the extend/repair/swap spine
94
+ * rides (the all-white SolidMask → MiniMaxH3FantasticVideoEditLatent
95
+ * → MiniMaxH3ContexMaskedTarget). White means "every frame is
96
+ * editable" (nothing is held; a refine re-renders the window at its
97
+ * own denoise) and `keep_audio` carries the window's soundtrack into
98
+ * the joint latent, so the audio stream every downstream node reads
99
+ * is the source's own. The mask's size comes from the loader's
100
+ * frames (GetImageSizeAndCount), never from a hand-typed resolution.
101
+ * @param g the run's graph builder
102
+ * @param plane the plane's two VAE seats
103
+ * @param frames the window's loaded frames
104
+ * @param audio the window's loaded soundtrack
105
+ * @returns the nested video+audio target latent the handoff refines */
106
+ const refineJointTarget = (g, plane, frames, audio) => {
107
+ const size = g.node('GetImageSizeAndCount', { image: frames });
108
+ const whiteMask = g.node('SolidMask', {
109
+ value: 1, width: size.out(1), height: size.out(2),
110
+ }).out(0);
111
+ const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
112
+ grow: 0, keep_audio: true, megapixels: 0,
113
+ vae: plane.vaeVideo, images: frames, mask: whiteMask,
114
+ audio_vae: plane.vaeAudio, audio,
115
+ }).out(0);
116
+ return g.node('MiniMaxH3ContexMaskedTarget', {
117
+ mask_meaning: 'white = generate',
118
+ audio_mode: 'preserve source audio',
119
+ mask_conversion: 'H3 exact (causal/token max)',
120
+ target_latent: edit, mask: whiteMask,
121
+ }).out(0);
122
+ };
123
+ /** THE WINDOW BODY — one refine window, whichever door composed it:
124
+ * joint AV target → (carry) → the 2x handoff → decode → (head-trim).
125
+ * THE CARRY IS THE FILM'S OWN NODE, with the film's own seats
126
+ * (iteration, overlap_frames, continue_audio_latent true, the
127
+ * model + sigmas the sampler will ride, previous_latent = the
128
+ * previous window's joint latent): the carried tail is copied into
129
+ * this window's head, the zero-prefix mask pins it (gradient false),
130
+ * the audio prefix takes the same Soft AV half-cosine release, and
131
+ * the returned model is the drift-controlled one the handoff samples
132
+ * with — one mechanism for normal gens and refine gens.
133
+ *
134
+ * WHAT rides as `previous_latent` (settled round 27): the previous
135
+ * window's JOINT TARGET — the latent its handoff refined. A refine
136
+ * has no base-rate sample (its only sample IS the 2x handoff's), and
137
+ * the joint-AV upscaler the handoff wraps takes a base-rate latent,
138
+ * so the film's own 2x-arm law applies: carry the base grid and let
139
+ * each window's upscale re-derive the high grid (actions.ts's F44
140
+ * seam currency — `seamLatent = upscaleOn ? sampled.out(0)` — is the
141
+ * symmetry owner). The head-trim then drops the carried duplicate,
142
+ * exactly as the film's windows do, and the tail is the plain file
143
+ * concat — no alpha blend anywhere on either path.
144
+ * @param g the run's graph builder
145
+ * @param entry the window's entry (prompt + dials)
146
+ * @param p the walked doc params (the scheduler name)
147
+ * @param plane the family plane (shared by a carry film)
148
+ * @param seat the window's loader seats + carried head + save prefix
149
+ * @param iteration the window's index in its emission (the
150
+ * continuation's own `iteration` seat; only read when carrying)
151
+ * @param previousLatent the previous window's joint target — present
152
+ * exactly when this window carries
153
+ * @returns the window's SaveVideo passthrough plus the joint target
154
+ * the NEXT window carries */
155
+ const composeRefineWindow = (g, entry, p, plane, seat, iteration, previousLatent) => {
156
+ const dials = refineDials(entry);
157
+ requireRefineEntry(entry);
158
+ judgeRefineWindow(seat.cap, dials);
159
+ const [srcFrames, srcAudio] = loadVideo(g, entry['source_clip'], seat.cap, seat.skip);
160
+ const target = refineJointTarget(g, plane, srcFrames, srcAudio);
121
161
  const positive = g.node('CLIPTextEncode', {
122
- text: entry['refine_prompt'], clip,
162
+ text: entry['refine_prompt'], clip: plane.clip,
123
163
  }).out(0);
124
- const noise = g.node('RandomNoise', { noise_seed: seed }).out(0);
164
+ const noise = g.node('RandomNoise', { noise_seed: dials.seed }).out(0);
125
165
  const sched = g.node('BasicScheduler', {
126
- model: sigmaModel, scheduler: p.sched_name,
127
- steps, denoise,
166
+ model: plane.sigmaModel, scheduler: p.sched_name,
167
+ steps: dials.steps, denoise: dials.denoise,
128
168
  }).out(0);
129
- // ── THE HANDOFF (the report-named chain: learned 2x upscale +
130
- // the low-sigma refinement pass, one node — its output is final/
131
- // decode-ready, no external guider or second sampler) ──
132
- // THE CAPACITY SEATS ride the handoff verbatim — the window above is
133
- // what keeps a 2x pass inside memory; a ≤1x pass sizes its own.
169
+ let cond = positive;
170
+ let mdl = plane.sigmaModel;
171
+ let lat = target;
172
+ if (previousLatent !== undefined) {
173
+ /* v8 ignore next 5 -- unreachable by construction: every caller passes previousLatent exactly for k ≥ 1, where overlapFrames = carries[k−1], and the tokenExactCarry door (≥ 5) has already refused every smaller carry; the guard stays as the window body's own contract against a future wiring slip */
174
+ if (seat.overlapFrames <= 0) {
175
+ throw new Error(`h3-timeline refine: window ${iteration} arrived with a previous latent but no carried head — a carry without frames to carry is a wiring bug, not a doc to fix`);
176
+ }
177
+ const cont = g.node('MiniMaxH3FiniteLatentContinuation', {
178
+ positive: cond, target_latent: lat, iteration,
179
+ overlap_frames: seat.overlapFrames, continue_audio_latent: true,
180
+ model: mdl, sigmas: sched, previous_latent: previousLatent,
181
+ });
182
+ cond = cont.out(0);
183
+ lat = cont.out(1);
184
+ mdl = cont.out(3);
185
+ }
134
186
  const upscaled = g.node('MinimaxH3LatentUpscaler3DRefineHandoff', {
135
- latent: videoLatent, audio_latent: audioLatent,
136
- noise, sampler: samplerSel, sigmas: sched,
137
- model: sigmaModel, positive,
187
+ latent: lat, noise, sampler: plane.samplerSel, sigmas: sched,
188
+ model: mdl, positive: cond,
138
189
  model_name: REFINE_UPSCALE_MODEL,
139
- // THE FLAT CLASS (F23 blocker, round-6 audit): THIS handoff
140
- // declares `mode` as a plain combo and `scale` as its OWN required
141
- // top-level FLOAT (production /object_info + the vendored
142
- // minimax_h3_refine.py:349-353) — there is no `mode.scale` seat on
143
- // it. The dotted spelling belongs to MinimaxH3LatentUpscaler3D
144
- // (COMFY_DYNAMICCOMBO_V3, chainUpscale.ts), a DIFFERENT node; the
145
- // round-5 cure crossed the two and reintroduced
146
- // required_input_missing on this member.
147
- mode: upMode, scale: upScale,
148
- // Multiplier mode ignores these (the film's own note at its
149
- // handoff mount) — they ride the upscaler's own defaults.
190
+ mode: dials.upMode, scale: dials.upScale,
150
191
  width: 1280, height: 704, megapixels: 1,
151
192
  keep_proportion: true, align: 32,
152
193
  lock_audio: true, cfg: 1.0, device: 'cuda', precision: 'bf16',
153
194
  offload_after_upscale: false,
154
195
  }).out(0);
155
- // ── decode + the film tail's file law ──
156
- let vdec = g.node('VAEDecode', { samples: upscaled, vae: vaeVideo }).out(0);
157
- let adec = g.node('VAEDecodeAudio', { samples: upscaled, vae: vaeAudio }).out(0);
196
+ let vdec = g.node('VAEDecode', { samples: upscaled, vae: plane.vaeVideo }).out(0);
197
+ let adec = g.node('VAEDecodeAudio', { samples: upscaled, vae: plane.vaeAudio }).out(0);
158
198
  if (seat.overlapFrames > 0) {
159
- // THE CARRIED HEAD (the loop's seam law): a k≥2 window's opening
160
- // overlap is the previous window's tail re-rendered, so this
161
- // window's OWN clip never replays it — the film's finalize node,
162
- // hard audio trim (the carried seam leaves picture AND sound).
199
+ // THE CARRIED HEAD: the film's own finalize node, the film's own
200
+ // seats (iteration 1, the carried span, audio trimmed with the
201
+ // picture) — the seam is never replayed and never blended.
163
202
  const fin = g.node('MiniMaxH3FiniteSegmentFinalize', {
164
203
  sampled_latent: upscaled, images: vdec, audio: adec,
165
204
  iteration: 1, overlap_frames: seat.overlapFrames, trim_audio_head: true,
@@ -170,10 +209,52 @@ export function renderH3RefineWindow(entry, p, facts, g, seat) {
170
209
  const created = g.node('CreateVideo', {
171
210
  images: vdec, audio: filmJoinAudio(g, adec), fps: 24, bit_depth: 8,
172
211
  });
173
- return g.node('SaveVideo', {
174
- video: created.out(), filename_prefix: seat.prefix,
175
- format: 'mp4', codec: 'h264',
176
- }).out(0);
212
+ return {
213
+ save: g.node('SaveVideo', {
214
+ video: created.out(), filename_prefix: seat.prefix,
215
+ format: 'mp4', codec: 'h264',
216
+ }).out(0),
217
+ target,
218
+ };
219
+ };
220
+
221
+
222
+
223
+
224
+
225
+
226
+
227
+
228
+
229
+
230
+
231
+
232
+ export function renderH3RefineWindow(entry, p, facts, g, seat) {
233
+ if (!Number.isInteger(seat.cap) || seat.cap < 1) {
234
+ throw new Error(`h3-timeline refine: a ${seat.cap} f window — a refine window needs frames (the loop's cap is the loader's frame_load_cap at 24 fps; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
235
+ }
236
+ if (!Number.isInteger(seat.skip) || seat.skip < 0) {
237
+ throw new Error(`h3-timeline refine: a window starting at frame ${seat.skip} — a window starts at or after the clip's first frame (the loop's skip is the loader's skip_first_frames)`);
238
+ }
239
+ const plane = h3MaskedEditPlane(g, p, facts, seat.cap / 24);
240
+ return composeRefineWindow(g, entry, p, plane, seat, 0).save;
241
+ }
242
+ /** ONE entry's window ORIGIN seats (the loader's coordinates, derived
243
+ * from the seconds the entry states — the film clock, 24 fps). One
244
+ * owner for the single-window arm and the bag carrier, so both doors
245
+ * judge a stated length/start identically.
246
+ * @param entry the refine entry (clip_seconds, start_seconds)
247
+ * @returns the window's frame cap and first frame */
248
+ function refineWindowOrigin(entry) {
249
+ const clipSeconds = num(entry, 'clip_seconds', REFINE_DEFAULT_CLIP_SECONDS);
250
+ const startSeconds = num(entry, 'start_seconds', 0);
251
+ if (!(clipSeconds > 0)) {
252
+ throw new Error(`h3-timeline refine: clip_seconds ${clipSeconds} — a refine window needs frames (the seat is the loader's frame_load_cap: seconds × 24 at the film clock; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
253
+ }
254
+ if (!(startSeconds >= 0)) {
255
+ throw new Error(`h3-timeline refine: start_seconds ${startSeconds} — a window starts at or after the clip's first frame (the seat is the loader's skip_first_frames); advance it window by window to cover a long film`);
256
+ }
257
+ return { cap: Math.max(1, Math.round(clipSeconds * 24)), skip: Math.round(startSeconds * 24) };
177
258
  }
178
259
  /** The refine renderer: validates the bound entry, then composes
179
260
  * the standalone single-window second pass. Like the swap, the film
@@ -187,19 +268,14 @@ export function renderH3RefineWindow(entry, p, facts, g, seat) {
187
268
  * — the family plane this refine renders under)
188
269
  * @param facts the family's lane facts (unet off the DECL row)
189
270
  * @param g the run's graph builder
190
- * @param runId the run tree's id (the refine filename rides it) */
271
+ * @param runId the run tree's id (the refine filename rides it)
272
+ * @returns the window's SaveVideo passthrough (the bag carrier's
273
+ * N=1 delegate returns the same handle; statement callers ignore it) */
191
274
  export function renderH3Refine(entry, p, facts, g, runId) {
192
- const clipSeconds = num(entry, 'clip_seconds', REFINE_DEFAULT_CLIP_SECONDS);
193
- const startSeconds = num(entry, 'start_seconds', 0);
194
- if (!(clipSeconds > 0)) {
195
- throw new Error(`h3-timeline refine: clip_seconds ${clipSeconds} — a refine window needs frames (the seat is the loader's frame_load_cap: seconds × 24 at the film clock; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
196
- }
197
- if (!(startSeconds >= 0)) {
198
- throw new Error(`h3-timeline refine: start_seconds ${startSeconds} — a window starts at or after the clip's first frame (the seat is the loader's skip_first_frames); advance it window by window to cover a long film`);
199
- }
200
- renderH3RefineWindow(entry, p, facts, g, {
201
- cap: Math.max(1, Math.round(clipSeconds * 24)),
202
- skip: Math.round(startSeconds * 24),
275
+ const { cap, skip } = refineWindowOrigin(entry);
276
+ return renderH3RefineWindow(entry, p, facts, g, {
277
+ cap,
278
+ skip,
203
279
  overlapFrames: 0,
204
280
  prefix: `${runId}/refine`,
205
281
  });
@@ -232,6 +308,374 @@ export function renderH3Refine(entry, p, facts, g, runId) {
232
308
 
233
309
 
234
310
 
311
+
312
+
313
+
314
+
315
+
316
+
317
+
318
+
319
+
320
+
321
+
322
+
323
+
324
+
325
+
326
+
327
+
328
+
329
+
330
+
331
+
332
+
333
+
334
+
335
+
336
+
337
+
338
+
339
+
340
+
341
+
342
+
343
+
344
+
345
+
346
+
347
+
348
+
349
+ function refineCarryStanddown(what) {
350
+ return `h3-timeline refine: ${what} would carry the film's own continuation between windows — and that carry is DEAD in the engine today (F3-14, operator burn 2026-11-05): the carried window dies at its handoff with "ValueError: Drift-Control AV packed mask does not match its audio stream" (the Drift-Control mask state splits the packed mask by the install-time stream shapes, drift_control_av.py:159, and a continuation-carried latent's audio prefix no longer lands; the node is MinimaxH3LatentUpscaler3DRefineHandoff). Window 0 renders and bills BEFORE that failure, so the door refuses the carry shape instead of billing a partial. The hard cut serves today: state overlap_frames 0 (the auto-tile) or start the next window at the previous window's end (the bag) — the plain concat of independent windows, no continuation. The carried refine is owed the engine cure (ROADMAP F3-14).`;
351
+ }
352
+
353
+
354
+
355
+
356
+
357
+
358
+
359
+
360
+
361
+
362
+
363
+
364
+
365
+
366
+ export const tokenExactCarry = (frames) => Number.isInteger(frames) && frames >= 5 && (frames - 5) % 17 === 0;
367
+ /** The next token-exact carry at or above a measured span — the rung
368
+ * a refusal names so the fix is a stated number, not a search.
369
+ * @param frames the measured carry in frames
370
+ * @returns the smallest token-exact carry ≥ `frames` */
371
+ export const nextTokenExact = (frames) => frames <= 5 ? 5 : 5 + 17 * Math.ceil((frames - 5) / 17);
372
+ /** The most truthful start for the next window: the film's own 22 f
373
+ * seam when the previous window can hold it, else the largest
374
+ * token-exact carry the window can still advance from. The refusal
375
+ * names this frame, so the fix is one edited Start seconds.
376
+ * @param prev the previous window's origin (cap + skip at the film clock)
377
+ * @returns the next window's start frame, or null when the window is
378
+ * too short for any carried join */
379
+ export const lawfulCarryStart = (prev) => {
380
+ for (const carry of [22, 5, 39, 56, 73, 90, 107, 124, 141]) {
381
+ if (carry < prev.cap)
382
+ return prev.skip + prev.cap - carry;
383
+ }
384
+ return null;
385
+ };
386
+ /** THE TILING SEATS — the two seats that set a member's geometry
387
+ * (mode + scale). Prompts and dials stay per-window (the film's own
388
+ * freedom: every window composes its own conditioning), but one
389
+ * film joins one shape, so a bag that states different tiling seats
390
+ * refuses.
391
+ * @param a the entry the face reads (bag[0])
392
+ * @param b the entry compared against it
393
+ * @returns one entry per differing tiling seat, empty when they agree */
394
+ const refineTilingDiff = (a, b) => {
395
+ const out = [];
396
+ const modeA = a['mode'] ?? 'scale by multiplier';
397
+ const modeB = b['mode'] ?? 'scale by multiplier';
398
+ if (modeA !== modeB)
399
+ out.push(`mode ('${modeA}' vs '${modeB}')`);
400
+ const scaleA = num(a, 'scale', 2.0);
401
+ const scaleB = num(b, 'scale', 2.0);
402
+ if (scaleA !== scaleB)
403
+ out.push(`scale (${String(scaleA)} vs ${String(scaleB)})`);
404
+ return out;
405
+ };
406
+ /** THE CARRY FACE — N windows of ONE film, each join riding the
407
+ * FILM'S OWN SEAM NODE (round 27; operator order: "ZERO DIFFERENCE
408
+ * BETWEEN THE CONTEXT CARRY FROM THE NORMAL GENS AND THE REFINE
409
+ * GENS"). Every window composes the single-press body (joint AV
410
+ * target → [MiniMaxH3FiniteLatentContinuation] → the 2x handoff →
411
+ * decode → head-trim → SaveVideo); window k's continuation receives
412
+ * window k−1's joint target as `previous_latent` with the film's
413
+ * seats (iteration, the carried overlap, continue_audio_latent true,
414
+ * the model + sigmas the handoff samples with), and the film tail is
415
+ * the film's own join — the finalize head-trim per window, then the
416
+ * plain file concat ordered by the unload boundary chain. No
417
+ * crossfade, no list-seat copy, no refine-only carry: the same node,
418
+ * the same overlap, the same audio release, the same trim.
419
+ *
420
+ * PER-ENTRY CONDITIONING IS LAWFUL: each window composes its own
421
+ * CLIPTextEncode/RandomNoise/BasicScheduler from ITS entry, so a bag
422
+ * of different prompts refines window by window (the film's own
423
+ * freedom). Only the tiling seats must agree — they set the member
424
+ * geometry and one film joins one shape.
425
+ * @param entries the bag's entries, film order (one per window)
426
+ * @param p the walked doc params
427
+ * @param facts the family's lane facts
428
+ * @param g the run's graph builder
429
+ * @param windows each window's cap + skip, film order (≥ 2)
430
+ * @param carries each join's carried overlap in frames (one per join)
431
+ * @param runId the run tree's id (member + film prefixes ride it)
432
+ * @returns the assembled film's SaveVideo passthrough */
433
+ /** THE CARRY LAW, judged without emitting (the stand-down and the
434
+ * carrier share one judge): the entries tile the stated windows one
435
+ * per window, every join is token-exact, each window passes its own
436
+ * seat/ceiling door, and the tiling seats (mode + scale) agree across
437
+ * the film. Called by `renderH3RefineCarry` before its walk and by
438
+ * the bag/loop before the F3-14 stand-down, so a malformed shape
439
+ * keeps its own better voice and the stand-down owns only lawful
440
+ * carries.
441
+ * @param entries the film's entries, film order (one per window)
442
+ * @param windows each window's cap + skip, film order (≥ 2)
443
+ * @param carries each join's carried overlap in frames (one per join) */
444
+ function assertRefineCarryLawful(entries, windows, carries) {
445
+ if (entries.length !== windows.length) {
446
+ throw new Error(`h3-timeline refine: the carry face names ${entries.length} entries over ${windows.length} windows — one entry per window, film order`);
447
+ }
448
+ if (windows.length < 2 || carries.length !== windows.length - 1) {
449
+ throw new Error(`h3-timeline refine: the carry face tiles ${windows.length} windows over ${carries.length} joins — at least two windows and one carried join each, in film order`);
450
+ }
451
+ if (!carries.every(tokenExactCarry)) {
452
+ throw new Error(`h3-timeline refine: the carry face carries ${carries.join(', ')} f — every join must be token-exact (frames >= 5 and (frames - 5) % 17 === 0: 5, 22, 39 …; the H3 VAE maps 5 frames to 2 latent tokens, then 17 frames to every 5 further tokens); a non-exact overlap refuses — the crossfade of two independent renders is the ghost, never a silent snap`);
453
+ }
454
+ for (let k = 0; k < windows.length; k += 1) {
455
+ const w = windows[k];
456
+ if (!Number.isInteger(w.cap) || w.cap < 1) {
457
+ throw new Error(`h3-timeline refine: the carry face's window ${k} carries cap ${w.cap} f — a whole frame count at or above one`);
458
+ }
459
+ if (!Number.isInteger(w.skip) || w.skip < 0) {
460
+ throw new Error(`h3-timeline refine: the carry face's window ${k} starts at skip ${w.skip} — a whole frame offset at or above zero`);
461
+ }
462
+ const dials = refineDials(entries[k]);
463
+ requireRefineEntry(entries[k]);
464
+ judgeRefineWindow(w.cap, dials);
465
+ if (k === 0)
466
+ continue;
467
+ const carry = carries[k - 1];
468
+ if (carry >= w.cap) {
469
+ throw new Error(`h3-timeline refine: window ${k} carries ${carry} f of its ${w.cap} f — the carried head must leave frames of its own to refine (a window at or below the carried span re-renders nothing)`);
470
+ }
471
+ if (carry >= windows[k - 1].cap) {
472
+ throw new Error(`h3-timeline refine: the join into window ${k} carries ${carry} f but window ${k - 1} holds only ${windows[k - 1].cap} f — a carry cannot exceed the window it comes from`);
473
+ }
474
+ const diffs = refineTilingDiff(entries[0], entries[k]);
475
+ if (diffs.length > 0) {
476
+ throw new Error(`h3-timeline refine: window ${k} states ${diffs.join('; ')} against window 0's — the members would save at different shapes and one film joins one shape (the tiling seats are mode + scale; prompts and dials stay per-window)`);
477
+ }
478
+ }
479
+ }
480
+ export function renderH3RefineCarry(entries, p, facts, g, windows, carries, runId) {
481
+ assertRefineCarryLawful(entries, windows, carries);
482
+ // ── ONE shared plane for the whole film (the film's own posture:
483
+ // one unet stack, one clip, the two VAEs; the boundary chain below
484
+ // orders the saves, never a second unet) ──
485
+ const plane = h3MaskedEditPlane(g, p, facts, windows[0].cap / 24);
486
+ // ── the film's own walk: window k≥2 carries window k−1's joint
487
+ // target through the film's seam node, saves its trimmed member
488
+ // under its own prefix, and the boundary chain orders every save
489
+ // before the concat reads the files back ──
490
+ const saves = [];
491
+ const prefixes = [];
492
+ let previous;
493
+ for (let k = 0; k < windows.length; k += 1) {
494
+ const prefix = `${runId}/refine_w${k}`;
495
+ const body = composeRefineWindow(g, entries[k], p, plane, {
496
+ cap: windows[k].cap,
497
+ skip: windows[k].skip,
498
+ overlapFrames: k === 0 ? 0 : carries[k - 1],
499
+ prefix,
500
+ }, k, previous);
501
+ saves.push(body.save);
502
+ prefixes.push(prefix);
503
+ previous = body.target;
504
+ }
505
+ const boundary = chainSaveBoundaries(g, saves);
506
+ return concatSavedFilms(g, prefixes, boundary, `${runId}/refine`);
507
+ }
508
+ export function renderH3RefineBag(bag, p, facts, g, runId) {
509
+ // The card door arms on bag presence (refineArmed) — an empty bag
510
+ // here is a wiring bug, never user input. Refuse loud at the seam.
511
+ if (!Array.isArray(bag) || bag.length === 0) {
512
+ throw new Error('h3-timeline refine: the bag arrived empty at the family carrier — the card door arms on a non-empty refine bag, so this is a compose-wiring bug, not a doc to fix');
513
+ }
514
+ // THE SEQUENTIAL-PRESS LAW (F36): one entry IS the arm's own
515
+ // single-window emission — byte-identical, no boundary, no concat.
516
+ // The walk posture (press, judge, press) stays lawful through this
517
+ // delegate, and a doc that needs no tiling pays nothing for it.
518
+
519
+ // can make windows, but the human operator can't"): a LONE entry
520
+ // stating windows > 1 tiles ITSELF through the F24 loop renderer —
521
+ // the compose derives every window's start (start_seconds + k ×
522
+ // (cap − overlap)), so the human states a window SIZE and a COUNT
523
+ // instead of hand-tiling N entries with frame-exact starts the
524
+ // 0.25-step dials cannot reach. windows = 1 keeps the delegate
525
+ // above byte-identically (a lone window has no join, so a stated
526
+ // overlap_frames rides along unused — the seat's own tooltip says
527
+ // so, never a silent second meaning). A windows > 1 seat on ANY
528
+ // entry of a MULTI-entry bag refuses below — two tilings stated,
529
+ // and the bag already IS one.
530
+ if (bag.length === 1) {
531
+ const entry = bag[0];
532
+ const stated = entry['windows'];
533
+ const windows = typeof stated === 'number' ? stated : 1;
534
+ if (windows !== 1) {
535
+ if (!Number.isInteger(windows) || windows < 2 || windows > MAX_COMPOSED_WINDOWS) {
536
+ throw new Error(`h3-timeline refine: windows ${String(stated)} — one entry auto-tiles a whole number of windows from 2 to ${MAX_COMPOSED_WINDOWS} (1 is the single-window walk posture: judge each window before pressing the next); hand-tiled entries are the bag's own shape for mixed-seat films`);
537
+ }
538
+ const rawOverlap = entry['overlap_frames'];
539
+ const overlap = rawOverlap === undefined ? REFINE_DEFAULT_OVERLAP_FRAMES : rawOverlap;
540
+ if (!Number.isInteger(overlap) || overlap < 0) {
541
+ throw new Error(`h3-timeline refine: overlap_frames ${String(rawOverlap)} — the carried overlap is whole frames at or above zero (22 is the film's own seam and token-exact: 5, 22, 39 … the film's own continuation carries each join; any other overlap of 1 or more refuses — a crossfade of two independent renders is not served; 0 abuts with the hard cut)`);
542
+ }
543
+ return renderH3RefineWindows(entry, p, facts, g, runId, { windows, overlapFrames: overlap });
544
+ }
545
+ return renderH3Refine(entry, p, facts, g, runId);
546
+ }
547
+ if (bag.some((e) => typeof e['windows'] === 'number' && e['windows'] > 1)) {
548
+ throw new Error('h3-timeline refine: a multi-entry bag states windows above 1 — the bag already IS the tiling (each entry is one window, placed by its own start_seconds); state windows on ONE lone entry to auto-tile, or tile the entries by hand');
549
+ }
550
+ if (bag.length > MAX_COMPOSED_WINDOWS) {
551
+ throw new Error(`h3-timeline refine: the bag carries ${bag.length} entries — the film's composed-window ceiling is ${MAX_COMPOSED_WINDOWS} (${(MAX_COMPOSED_WINDOWS * (REFINE_DEFAULT_CLIP_SECONDS - 22 / 24)).toFixed(2)} s at the default window); refine a shorter film or raise clip_seconds inside the measured ${REFINE_2X_OOM_FRAMES} f ceiling`);
552
+ }
553
+ // LAW 1 — ONE FILM PER BAG: the staged leaf is per-entry text, so
554
+ // compare the named leaves. An entry naming NO leaf skips this
555
+ // comparison on purpose: the window renderer's own REQUIRED_SEATS
556
+ // refusal owns that voice (missing seat, not mixed sources).
557
+ const leaves = new Set();
558
+ for (const entry of bag) {
559
+ const leaf = entry['source_clip'];
560
+ if (typeof leaf === 'string' && leaf.trim() !== '')
561
+ leaves.add(leaf.trim());
562
+ }
563
+ if (leaves.size > 1) {
564
+ const named = [...leaves].map((l) => `'${l}'`).join(', ');
565
+ throw new Error(`h3-timeline refine: the bag's entries name ${leaves.size} different source clips (${named}) — ONE FILM PER BAG: a multi-entry refine tiles windows of ONE staged leaf into one film (the boundary chain + file join join windows of one timeline); two sources are two films, and a second card is the honest door for a second source`);
566
+ }
567
+ // LAW 2 — NO GAPS, NO FULL OVERLAP (the no-drop law): derive every
568
+ // window's origin first (the same validation the single-window arm
569
+ // runs, per entry), then judge consecutive entries in STATED order.
570
+ const origins = bag.map((entry) => refineWindowOrigin(entry));
571
+ for (let k = 1; k < origins.length; k += 1) {
572
+ const prev = origins[k - 1];
573
+ const cur = origins[k];
574
+ const overlap = prev.skip + prev.cap - cur.skip;
575
+ if (overlap < 0) {
576
+ throw new Error(`h3-timeline refine: window ${k} starts at frame ${cur.skip} but window ${k - 1} ends at frame ${prev.skip + prev.cap} — a ${-(overlap)} f gap silently drops source seconds (the no-drop law: consecutive windows overlap, never a hole; state window ${k} at or before frame ${prev.skip + prev.cap})`);
577
+ }
578
+ if (cur.skip <= prev.skip) {
579
+ throw new Error(`h3-timeline refine: window ${k} starts at frame ${cur.skip}, at or before window ${k - 1}'s start (frame ${prev.skip}) — out of order and fully covering the previous window (the compose never silently sorts; in film order every entry starts strictly after the one before it, carrying its tail as overlap)`);
580
+ }
581
+ }
582
+ // Every entry binds BOTH seats before any join judgment: a bag whose
583
+ // second window names no prompt is malformed whichever join it would
584
+ // have taken, and the seat's own door says so (the carry refusal
585
+ // below owns stated-but-different seats, never an absent one).
586
+ for (const entry of bag) {
587
+ for (const [seat, what] of REQUIRED_SEATS) {
588
+ const v = entry[seat];
589
+ if (typeof v !== 'string' || v.trim() === '') {
590
+ throw new Error(`h3-timeline refine: '${seat}' names no media — ${what}; a refine needs both seats bound (source_clip, refine_prompt)`);
591
+ }
592
+ }
593
+ }
594
+ // THE TILING: one window body per entry, prefix k 0-based (the F24
595
+ // loop's walled spelling). THE JOIN FACE is decided by the carries:
596
+ // a bag whose every join CARRIES (≥ 1 f) rides the carry face — the
597
+ // film's own continuation per join, head-trim + plain concat — and
598
+ // a bag with ANY zero-carry join keeps the independent walk
599
+ // (head-trim for the overlaps it states, then the concat: a hard
600
+ // cut where nothing is carried). N=1 never reaches here (the
601
+ // sequential-press delegate above).
602
+ const originsCarries = [];
603
+ for (let k = 1; k < origins.length; k += 1) {
604
+ originsCarries.push(origins[k - 1].skip + origins[k - 1].cap - origins[k].skip);
605
+ }
606
+ const blendJoins = originsCarries.length > 0 && originsCarries.every((o) => o >= 1);
607
+ // THE GHOST IS NOT A FALLBACK (FRICTION F26, operator burn
608
+
609
+ // join is off the token grid cannot continue the stream — and the
610
+
611
+ // the blend fallback, was a linear crossfade of two INDEPENDENT
612
+ // renders: a double exposure at the seam. The measured burn: a
613
+ // hand-placed 20 f carry silently switched the mechanism and
614
+ // shipped the ghost. It refuses instead, naming the measured carry
615
+ // and the start that lands the film's own 22 f seam.
616
+ if (blendJoins) {
617
+ const offGrid = originsCarries.findIndex((c) => !tokenExactCarry(c));
618
+ if (offGrid !== -1) {
619
+ const carry = originsCarries[offGrid];
620
+ const prev = origins[offGrid];
621
+ const next = origins[offGrid + 1];
622
+ const lawful = lawfulCarryStart(prev);
623
+ const clockFps = num(p, 'fps', DOC_FPS_DEFAULT);
624
+ const rung = nextTokenExact(carry);
625
+ throw new Error(`h3-timeline refine: the join between windows ${offGrid} and ${offGrid + 1} carries ${carry} f (derived: ${prev.skip} + ${prev.cap} − ${next.skip}) — not token-exact, so the model cannot continue the stream across it (5 frames = 2 latent tokens, then 17 frames = every 5 further tokens: 5, 22, 39, 56 …). A crossfade of the two independent renders would hide the mismatch behind a double exposure (the ghost) and is not served. ${lawful === null
626
+ ? `This window is too short for any carried join — state zero carry (abut the windows) or one entry with windows above 1.`
627
+ : `State window ${offGrid + 1} at frame ${lawful} (${(lawful / clockFps).toFixed(3)} s) for a 22 f carry — the film's own seam — (the nearest rung above the measured span is ${rung} f), or make the join zero-carry (start window ${offGrid + 1} at frame ${prev.skip + prev.cap}, the hard cut).`}`);
628
+ }
629
+ // THE CARRY STAND-DOWN (F3-14): the shape above is exactly the
630
+ // engine path that dies at window 1's handoff. Judge the shape
631
+ // first (a malformed bag keeps its own better voice), then refuse
632
+ // before a single node is emitted (the wall asserts g stays
633
+ // empty), so the press never bills window 0.
634
+ assertRefineCarryLawful(bag, origins, originsCarries);
635
+ const spans = originsCarries
636
+ .map((carry, k) => `window ${k}→${k + 1} carries ${carry} f`)
637
+ .join(', ');
638
+ throw new Error(refineCarryStanddown(`the carried join${originsCarries.length === 1 ? '' : 's'} (${spans})`));
639
+ }
640
+ const prefixes = [];
641
+ const saves = [];
642
+ for (let k = 0; k < bag.length; k += 1) {
643
+ const prefix = `${runId}/refine_w${k}`;
644
+ saves.push(renderH3RefineWindow(bag[k], p, facts, g, {
645
+ cap: origins[k].cap,
646
+ skip: origins[k].skip,
647
+ overlapFrames: k === 0 ? 0 : originsCarries[k - 1],
648
+ prefix,
649
+ }));
650
+ prefixes.push(prefix);
651
+ }
652
+ // THE FILM TAIL (one boundary chain, one join face here): one unload
653
+ // boundary per window save, the final token transitively depending
654
+ // on EVERY save (the §20 memory law — N windows must never
655
+ // co-reside), then the abutting concat into the one terminal film.
656
+ const boundary = chainSaveBoundaries(g, saves);
657
+ return concatSavedFilms(g, prefixes, boundary, `${runId}/refine`);
658
+ }
659
+
660
+
661
+
662
+
663
+
664
+
665
+
666
+
667
+
668
+
669
+
670
+
671
+
672
+
673
+
674
+
675
+
676
+
677
+
678
+
235
679
 
236
680
 
237
681
 
@@ -257,11 +701,41 @@ export function renderH3RefineWindows(entry, p, facts, g, runId, loop) {
257
701
  }
258
702
  const prefixes = [];
259
703
  const saves = [];
704
+ // THE JOIN FACE has exactly TWO faces: a carried loop (windows ≥ 2,
705
+ // overlap ≥ 1) walks the film's own continuation per join (the
706
+ // carry face: MiniMaxH3FiniteLatentContinuation with the film's
707
+ // seats, head-trim + plain concat); a one-window loop or a
708
+ // zero-overlap loop keeps the independent walk (head-trim + concat,
709
+ // a hard cut where nothing is carried).
710
+ const blend = loop.windows >= 2 && loop.overlapFrames >= 1;
711
+ // THE GHOST IS NOT A FALLBACK (FRICTION F26, operator burn
712
+
713
+ // the film's own seam —, 39 …) cannot continue the stream, and the
714
+
715
+ // crossfade of two INDEPENDENT renders — a double exposure at the
716
+ // seam. It refuses, naming the grid and the next rung.
717
+ if (blend && !tokenExactCarry(loop.overlapFrames)) {
718
+ const rung = nextTokenExact(loop.overlapFrames);
719
+ throw new Error(`h3-timeline refine: the loop carries a ${loop.overlapFrames} f overlap — not token-exact, so the model cannot continue the stream across it (5 frames = 2 latent tokens, then 17 frames = every 5 further tokens: 5, 22, 39, 56 …). A crossfade of the two independent renders would hide the mismatch behind a double exposure (the ghost) and is not served. State overlap_frames 22 — the film's own seam — (the nearest rung above ${loop.overlapFrames} f is ${rung} f), another rung of the grid, or 0 for the abutting hard cut.`);
720
+ }
721
+ if (blend) {
722
+ const windows = Array.from({ length: loop.windows }, (_, k) => ({
723
+ cap, skip: startFrames + k * step,
724
+ }));
725
+ const carries = new Array(loop.windows - 1).fill(loop.overlapFrames);
726
+ const entries = new Array(loop.windows).fill(entry);
727
+ // THE CARRY STAND-DOWN (F3-14): the carried joins die at window
728
+ // 1's handoff in the engine today; refuse before a node is
729
+ // emitted. The zero-overlap loop (the hard cut) never reaches here.
730
+ assertRefineCarryLawful(entries, windows, carries);
731
+ const joins = loop.windows - 1;
732
+ throw new Error(refineCarryStanddown(`a ${loop.windows}-window loop at a ${loop.overlapFrames} f overlap (${joins} carried join${joins === 1 ? '' : 's'})`));
733
+ }
260
734
  for (let k = 0; k < loop.windows; k += 1) {
261
735
  const prefix = `${runId}/refine_w${k}`;
262
736
  saves.push(renderH3RefineWindow(entry, p, facts, g, {
263
737
  cap, skip: startFrames + k * step,
264
- overlapFrames: k === 0 ? 0 : loop.overlapFrames,
738
+ overlapFrames: 0,
265
739
  prefix,
266
740
  }));
267
741
  prefixes.push(prefix);