@melite/models-h3 0.2.2-alpha → 0.3.0-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/repair.js CHANGED
@@ -1,21 +1,40 @@
1
- import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
2
- import { assertGridLength } from './timelineContract.js';
3
- /** The SAM3 checkpoint the mask family declares + hash-pins
4
- * (packages/models/mask/src/index.ts — auto-provisioned; the track
5
- * card's own SAM3_CKPT constant is the same file). */
6
- const SAM3_CKPT = 'sam3.1_multiplex_fp16.safetensors';
1
+ import { contexMaskedTarget, loadVideo, renderMaskedEditChain, resolvePlanTier, sheetRefSlots } from './chainEdit.js';
2
+ import { assertGridLength, resolveCarryOverlap } from './timelineContract.js';
7
3
  /** The repair entry's required seats (the reshoot idiom: an armed
8
- * doc with an empty seat refuses loud naming the seat). Two of the
9
- * three are text, not staged media — the loop still speaks the one
10
- * spelling so the refusal names the seat the same way the swap's
11
- * does. */
4
+ * doc with an empty seat refuses loud naming the seat). The third
5
+ * is staged media, not text — P0-2 (defect board row 2, the
6
+ * operator's contract "repair receives a mask and errors without
7
+ * one") killed the inline SAM3 manufacture: the mask is RECEIVED as
8
+ * ONE staged PNG, and the refusal names the seat the same way the
9
+ * swap's does. */
12
10
  const REQUIRED_SEATS = [
13
11
  ['source_clip', 'the clip whose region is repaired — ONE staged leaf: the VHS window loader + the core LoadVideo read it by staged name, and the timeline reads it back off the native VIDEO wire'],
14
12
  ['repair_prompt', 'the repair action text — what the masked region should become (the R2V prompt seat; agent-composed, user-confirmed)'],
15
- ['region_prompt', 'the free-text SAM3 detection target naming the region — "hands", "a person", "a face" are param VALUES, never card kinds (the region-agnostic law)'],
13
+ ['mask', "ONE staged PNG the repair RECEIVES (the operator's contract, defect board row 2: a repair errors without one) — the track run's pixel-max union is the recommended bridge; the chain resizes it to its own geometry in-graph, prose manufactures nothing"],
16
14
  ];
17
- const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
18
- const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
15
+ /** Reads one required seat NARROWED by its own refusal — the seat
16
+ * is a string or the door never composes (no fallback arm exists:
17
+ * a validated seat re-read through a forgiving helper would be a
18
+ * second, weaker validator below the law — a silent error). */
19
+ const requiredSeat = (entry, seat, what) => {
20
+ const v = entry[seat];
21
+ if (typeof v !== 'string' || v.trim() === '') {
22
+ throw new Error(`h3-timeline repair: '${seat}' names no media — ${what}; a repair needs all three seats bound (source_clip, repair_prompt, mask)`);
23
+ }
24
+ return v;
25
+ };
26
+ /** Reads one optional number seat: absent falls to the documented
27
+ * default; a stated non-number REFUSES — a defaulting fallback would
28
+ * swallow a bypassed door's wrong-typed value as a silent error. */
29
+ const statedNumber = (p, k, d) => {
30
+ const v = p[k];
31
+ if (v === undefined)
32
+ return d;
33
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
34
+ throw new Error(`h3-timeline repair: '${k}' is stated as ${JSON.stringify(v)} — a number seat carries a number (absent falls to ${d}); a wrong-typed value never silently defaults`);
35
+ }
36
+ return v;
37
+ };
19
38
  /** The repair renderer: validates the bound entry, then composes the
20
39
  * masked second-pass chain. Like the swap, the film path never
21
40
  * reaches here (the card branches on a non-empty repair bag, refuses
@@ -28,22 +47,23 @@ const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
28
47
  * @param g the run's graph builder
29
48
  * @param runId the run tree's id (the assemble filename rides it) */
30
49
  export function renderH3Repair(entry, p, facts, g, runId) {
31
- for (const [seat, what] of REQUIRED_SEATS) {
32
- const v = entry[seat];
33
- if (typeof v !== 'string' || v.trim() === '') {
34
- throw new Error(`h3-timeline repair: '${seat}' names no media — ${what}; a repair needs all three seats bound (source_clip, repair_prompt, region_prompt)`);
35
- }
36
- }
37
- const denoise = num(entry, 'denoise', 0.32);
50
+ // NO FALLBACK READS: every required seat narrows through its own
51
+ // refusal; every optional number refuses a wrong-typed stated
52
+ // value instead of silently defaulting (the schema walk types
53
+ // every lawful doc — a wrong-typed value means a bypassed door).
54
+ const sourceClipSeat = requiredSeat(entry, 'source_clip', REQUIRED_SEATS[0][1]);
55
+ const repairPromptSeat = requiredSeat(entry, 'repair_prompt', REQUIRED_SEATS[1][1]);
56
+ const maskSeat = requiredSeat(entry, 'mask', REQUIRED_SEATS[2][1]);
57
+ const denoise = statedNumber(entry, 'denoise', 0.32);
38
58
  if (denoise >= 1) {
39
59
  throw new Error(`h3-timeline repair: denoise ${denoise} >= 1 — a masked second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; denoise 1 would boil the held region into a new take — that is a reshoot, and the reshoot door exists)`);
40
60
  }
41
- const seed = num(entry, 'seed', 0);
42
- const steps = num(entry, 'steps', 6);
43
- const clipSeconds = num(entry, 'clip_seconds', 6);
44
- const resolution = str(entry, 'resolution') || '736p';
45
- const windowStart = num(entry, 'window_start', 0);
46
- const windowLength = num(entry, 'window_length', 0);
61
+ const seed = statedNumber(entry, 'seed', 0);
62
+ const steps = statedNumber(entry, 'steps', 6);
63
+ const clipSeconds = statedNumber(entry, 'clip_seconds', 6);
64
+ const resolution = resolvePlanTier(entry, p);
65
+ const windowStart = statedNumber(entry, 'window_start', 0);
66
+ const windowLength = statedNumber(entry, 'window_length', 0);
47
67
  // No silent clamps (the no-silent-repair law): a negative window
48
68
  // is a caller bug — refuse loud, never round it into a render.
49
69
 
@@ -60,22 +80,7 @@ export function renderH3Repair(entry, p, facts, g, runId) {
60
80
  // ── the staged media: the WINDOW loader (cap + skip on the same
61
81
  // VHS seat, so frames and audio stay in sync) and the inline
62
82
  // per-frame SAM3 mask that replaces the swap's staged PNG ──
63
- const [srcFrames, srcAudio] = loadVideo(g, str(entry, 'source_clip'), Math.round(windowLength), Math.round(windowStart));
64
- const scaled = g.node('ImageScaleToMaxDimension', {
65
- image: srcFrames, upscale_method: 'area', largest_size: 1008,
66
- }).out(0);
67
- const sam = g.node('CheckpointLoaderSimple', { ckpt_name: SAM3_CKPT });
68
- const regionCond = g.node('CLIPTextEncode', {
69
- text: str(entry, 'region_prompt'), clip: sam.out(1),
70
- }).out(0);
71
- const track = g.node('SAM3_VideoTrack', {
72
- images: scaled, model: sam.out(0), conditioning: regionCond,
73
- detection_threshold: num(entry, 'detection_threshold', 0.5),
74
- max_objects: 0, detect_interval: 1,
75
- }).out(0);
76
- const regionMasks = g.node('SAM3_TrackToMask', {
77
- track_data: track, object_indices: '',
78
- }).out(0);
83
+ const [srcFrames, srcAudio] = loadVideo(g, sourceClipSeat, Math.round(windowLength), Math.round(windowStart));
79
84
  // picture_1 for the plan head: the window's own first frame. The
80
85
  // plan node REQUIRES a picture (its describer vocabulary); the
81
86
  // repair's "replacement" is the source's own person, so the
@@ -88,16 +93,16 @@ export function renderH3Repair(entry, p, facts, g, runId) {
88
93
  renderMaskedEditChain(g, {
89
94
  p, facts,
90
95
  clipSeconds,
91
- overlapFrames: num(entry, 'overlap_frames', 39),
96
+ overlapFrames: resolveCarryOverlap(entry),
92
97
  resolution, seed, steps,
93
98
  roles: '',
94
- sourceClip: str(entry, 'source_clip'),
99
+ sourceClip: sourceClipSeat,
95
100
  windowStart,
96
101
  picture1: anchorFrame,
97
102
  srcFrames, srcAudio,
98
103
  // the ignored literal fallback — the plan node's WINDOW-RE-SLICED
99
104
  // shots ride plan_json_input (the repair's geometry law)
100
- planJson: JSON.stringify({ shots: [{ id: 'repair', prompt: str(entry, 'repair_prompt') }] }),
105
+ planJson: JSON.stringify({ shots: [{ id: 'repair', prompt: repairPromptSeat }] }),
101
106
  planFromSource: true,
102
107
  denoise,
103
108
  assemble: {
@@ -107,56 +112,58 @@ export function renderH3Repair(entry, p, facts, g, runId) {
107
112
  audioSource: 'source',
108
113
  filename: `${runId}/repair`,
109
114
  },
110
- body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
115
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio, refImages }) => {
116
+ // ── P0-2 (defect board row 2): the mask is RECEIVED, never
117
+ // manufactured — the inline SAM3 prose door (and its F7
118
+ // per-scene slice of a TRACKED stack) died with the contract.
119
+ // The static arm verbatim (the edit door's own F3-16 cure):
120
+ // the staged PNG's own shape is the TRACK's shape, not the
121
+ // chain's — resize to the plan geometry in-graph, never trust
122
+ // the file. The recommended bridge (the track run's pixel-max
123
+ // union) arrives already grown; prose manufactures nothing. ──
124
+ const raw = g.node('LoadImage', { image: maskSeat }).out(0);
111
125
 
112
- // parity. The plan head segments the window engine-side (the
113
- // swap's own choreography — planFromSource rides the same
114
- // seat); the loop drives the scenes; ChainAssemble stitches.
115
- // The one wire that never segmented was THE MASK: the tracked
116
- // stack (the whole window's timeline) fed every scene whole,
117
- // so a multi-scene repair saw rows it did not own (the F7
118
- // burn: one oversized shot, the mask leg loop-posture-only).
119
- // MiniMaxH3ContexLoopMaskSlice selects the current scene's
120
- // interval off the loop state — the tracked mask stack sliced
121
- // to each scene's frame range, BEFORE the grow (the
122
- // extension's own posture: slice, then Grow Mask). A
123
- // single-scene window slices its own whole interval — the
124
- // cure is posture-uniform, never a branch. ──
125
- const sceneMask = g.node('MiniMaxH3ContexLoopMaskSlice', {
126
- state: cur.out(0), mask: regionMasks, source_fps: 24,
127
- });
128
- const grown = g.node('GrowMaskWithBlur', {
129
- mask: sceneMask.out(0), expand: Math.round(num(entry, 'mask_grow', 16)),
130
- tapered_corners: true, blur_radius: 0,
126
+ // `ImageResize` — a class NO engine build owns (1817 classes,
127
+ // none so named; the refusal landed at compose time, after the
128
+ // authoring pass). Core `ImageScale` is the exact-fit resize
129
+ // the law always meant: it resizes to width/height with no
130
+ // proportion-keeping arm — the mask fills the chain canvas.
131
+
132
+ // plane and the conversion rides LAST — ImageScale is
133
+ // IMAGE→IMAGE, and a MASK socket fed an IMAGE is the
134
+ // prompt-validation death the engine serves after compose
135
+ // passes. Same two nodes; the ORDER is the law.
136
+ const fitted = g.node('ImageScale', {
137
+ image: raw, width: cur.out(8), height: cur.out(9),
138
+ upscale_method: 'bilinear', crop: 'disabled',
139
+ }).out(0);
140
+ const editMask = g.node('ImageToMask', {
141
+ image: fitted, channel: 'red',
131
142
  }).out(0);
132
143
  // ── the masked second-pass body: NO still, NO mannequin — the
133
144
  // source clip rides its own ref_video seat (the identity
134
145
  // anchor of a repair is the person already in the frame — the
135
146
  // zero-new-pixels law) ──
136
147
  const r2v = g.node('MiniMaxH3ReferenceToVideo', {
137
- prompt: str(entry, 'repair_prompt'),
148
+ prompt: repairPromptSeat,
138
149
  width: cur.out(8), height: cur.out(9), length: cur.out(6),
139
150
  ref_image_size: 'match',
140
151
  clip, vae: vaeVideo, audio_vae: vaeAudio,
141
152
  'ref_videos.ref_video_0': srcFrames,
142
153
  'ref_video_audios.ref_video_audio_0': mutedChainAudio,
154
+ // THE SHEET (P0-1): repair mounts NO image anchor — the
155
+ // declared ref_images ride from slot 0, stated exactly as
156
+ // the gen door states them (an input slot, nothing more).
157
+ ...sheetRefSlots(refImages, 0),
143
158
  });
144
159
  const slice = g.node('H3SourceSlice', {
145
160
  source_fps: 24, crop: 'center',
146
161
  state: cur.out(0), latent: r2v.out(1),
147
162
  audio_vae: vaeAudio, source_frames: srcFrames, source_audio: sliceAudio,
148
163
  });
149
- const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
150
- grow: 0, keep_audio: true, megapixels: 0,
151
- vae: vaeVideo, images: slice.out(0), mask: grown,
152
- audio_vae: vaeAudio, audio: slice.out(1),
153
- }).out(0);
154
- const target = g.node('MiniMaxH3ContexMaskedTarget', {
155
- mask_meaning: 'white = generate',
156
- audio_mode: 'preserve source audio',
157
- mask_conversion: 'H3 exact (causal/token max)',
158
- target_latent: edit, mask: grown,
159
- }).out(0);
164
+ const target = contexMaskedTarget(g, { vaeVideo, vaeAudio }, {
165
+ frames: slice.out(0), audio: slice.out(1), mask: editMask, keepAudio: true,
166
+ });
160
167
  return { conditioning: r2v.out(0), targetLatent: target };
161
168
  },
162
169
  });
package/lib/reshoot.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { outputNameTailOf } from './schema.js';
1
2
  /** The pack's clip-normalization node (the official chain's first
2
3
  * stage — resamples to 24 fps, snaps the frame count to H3's 17k+5
3
4
  * grid, centre-crops to the requested aspect at the pixel budget).
@@ -334,13 +335,17 @@ export function buildH3Reshoot(p, g, windowFrames, runId) {
334
335
  batch_index: 0,
335
336
  length: 1,
336
337
  }).out(0);
338
+
339
+ // press): the re-shoot's DELIVERED plates are BORN named
340
+ // (`reshoot_warp_<slug>` / `reshoot_orbit_<slug>`) — the same
341
+ // stem on both faces of the one re-shoot.
337
342
  const plateSave = g.node('SaveImage', {
338
343
  images: plate,
339
- filename_prefix: `${runId}/reshoot_warp`,
344
+ filename_prefix: `${runId}/reshoot_warp${outputNameTailOf(p)}`,
340
345
  }).out(0);
341
346
  const orbitSave = g.node('SaveImage', {
342
347
  images: warpNode.out(1),
343
- filename_prefix: `${runId}/reshoot_orbit`,
348
+ filename_prefix: `${runId}/reshoot_orbit${outputNameTailOf(p)}`,
344
349
  }).out(0);
345
350
  return {
346
351
  refFrames: source,
package/lib/schema.d.ts CHANGED
@@ -15,6 +15,12 @@ export declare const FPS_RAIL_MAX = 120;
15
15
  * rider (the SOTA plan's researched 0.30–0.35 band; 1.0 is the
16
16
  * taomate full-denoise mechanic, opt-in). */
17
17
  export declare const REFINE_DENOISE_DEFAULT = 0.35;
18
+ /** THE OUTPUT-NAME SLUG LAW (the file-plane seat on the carrier
19
+ * below): a filename segment and nothing else — the stem lands
20
+ * inside a SaveVideo / SaveImage prefix, so no space, slash, dot,
21
+ * or case may ride it. Shared by the carrier (the walk's boundary
22
+ * refusal) and the compose tail helper at the carrier's foot. */
23
+ export declare const OUTPUT_NAME_SLUG_RE: RegExp;
18
24
  export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
19
25
  image: z<string, string, "plain">;
20
26
  last_frame: z<string, string, "plain">;
@@ -80,6 +86,7 @@ export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
80
86
  k: z<number, number, "plain">;
81
87
  noise_seed: z<number, number, "plain">;
82
88
  fps_seconds: z<number, number, "plain">;
89
+ output_name: z<string, string, "plain">;
83
90
  interp_switch: z<boolean, boolean, "plain">;
84
91
  sharpen_switch: z<boolean, boolean, "plain">;
85
92
  sla_switch: z<boolean, boolean, "plain">;
@@ -149,11 +156,21 @@ export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
149
156
  k: z<number, number, "plain">;
150
157
  noise_seed: z<number, number, "plain">;
151
158
  fps_seconds: z<number, number, "plain">;
159
+ output_name: z<string, string, "plain">;
152
160
  interp_switch: z<boolean, boolean, "plain">;
153
161
  sharpen_switch: z<boolean, boolean, "plain">;
154
162
  sla_switch: z<boolean, boolean, "plain">;
155
163
  image_name: z<string, string, "plain">;
156
164
  }>>, "plain">;
165
+ /** The composed prefix tail for a doc's output_name — `_<slug>` when
166
+ * spelled, '' when absent. The DELIVERABLE prefix sites thread this
167
+ * (the film `h3_t4_film`, the extend film `extend_film`, the
168
+ * re-shoot plates `reshoot_warp` / `reshoot_orbit`); a stem that
169
+ * escaped the boundary walk (a legacy draft, a hand-built doc)
170
+ * refuses HERE loud, naming the law — a bad stem must never reach
171
+ * a filename. An empty string is the label seam's silence law:
172
+ * no stem, no tail, no refusal. */
173
+ export declare function outputNameTailOf(p: Record<string, unknown>): string;
157
174
  /** Schemastery objects are lenient (unknown/missing keys ride); the
158
175
  * family-admission laws are the renderer's own validators, ported:
159
176
  * unknown variant + family-conditional key admission on EXPLICIT
@@ -175,6 +192,12 @@ export declare const refinePlaneSchema: z<Schemastery.ObjectS<NoInfer<{
175
192
  }>>, Schemastery.ObjectT<NoInfer<{
176
193
  [k: string]: z;
177
194
  }>>, "plain">;
195
+ /** The wire tolerance for interpolate_enabled: the bench add-door's
196
+ * "false"/"true" string literal folds to a boolean before the walk;
197
+ * any other string refuses loud. Booleans and every other key pass
198
+ * verbatim.
199
+ * @param raw the pre-walk params record
200
+ * @returns the record with interpolate_enabled narrowed to boolean */
178
201
  export declare const coerceWireBoolean: (raw: Record<string, unknown>) => Record<string, unknown>;
179
202
  /** THE PIN ROW SHAPE (one law, two seats): the doc walk and the compose
180
203
  * gate both run this BEFORE any placement math — a row must carry a
@@ -183,6 +206,15 @@ export declare const coerceWireBoolean: (raw: Record<string, unknown>) => Record
183
206
  * gate-and-walk wall pins them); placement and media existence stay
184
207
  * the compose gate's, which owns the doc's calls/windows. */
185
208
  export declare function assertKeyframeRowShape(rows: readonly unknown[]): void;
209
+ /** The compose-admission walk over a raw doc (the card gate's
210
+ * model_validator port): array and boolean wire tolerances restored,
211
+ * keyframe rows shape-judged, shot rows judged (per-call vocabulary,
212
+ * int spans, tiling, seam/grid/guide gates), the window family
213
+ * derived, and the family-conditional key gates run. A refusal names
214
+ * the row and the cure; a passing doc returns the walked params with
215
+ * the __steps_pinned/__shift_pinned stamps added.
216
+ * @param v the raw doc (absent = the fresh-card draft)
217
+ * @returns the walked params record the compose reads */
186
218
  export declare function schema(v: unknown): Record<string, unknown>;
187
219
  export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
188
220
  image: z<string, string, "plain">;
@@ -249,6 +281,7 @@ export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
249
281
  k: z<number, number, "plain">;
250
282
  noise_seed: z<number, number, "plain">;
251
283
  fps_seconds: z<number, number, "plain">;
284
+ output_name: z<string, string, "plain">;
252
285
  interp_switch: z<boolean, boolean, "plain">;
253
286
  sharpen_switch: z<boolean, boolean, "plain">;
254
287
  sla_switch: z<boolean, boolean, "plain">;
@@ -318,6 +351,7 @@ export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
318
351
  k: z<number, number, "plain">;
319
352
  noise_seed: z<number, number, "plain">;
320
353
  fps_seconds: z<number, number, "plain">;
354
+ output_name: z<string, string, "plain">;
321
355
  interp_switch: z<boolean, boolean, "plain">;
322
356
  sharpen_switch: z<boolean, boolean, "plain">;
323
357
  sla_switch: z<boolean, boolean, "plain">;
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, bookSeconds, 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'];
@@ -49,6 +49,12 @@ export const REFINE_DENOISE_DEFAULT = 0.35;
49
49
  // (historical shape); at runtime schema() normalizes an
50
50
  // omitted key back to null so the body resolves the family's literal
51
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-]*$/;
52
58
  export const paramSchema = z.object({
53
59
 
54
60
  // for the full model, remove that") — the film-level prompt field
@@ -119,7 +125,7 @@ export const paramSchema = z.object({
119
125
  start_time: z.number().min(0).default(0).description('Start (s)'),
120
126
  duration: z.number().min(0).default(0).description('Duration (s)'),
121
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." })),
122
- 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." })),
123
129
 
124
130
  // mods. The pack injects them as reference tokens through ALL
125
131
  // DiT blocks on the conditioning side: no bundle-bus slot is
@@ -153,7 +159,7 @@ export const paramSchema = z.object({
153
159
  // generated voice yields under a conditioned clip at its film
154
160
  // span. −14dB is the natural mix-desk default; deeper for dense
155
161
  // dialogue, shallower when the generated voice should hold.
156
- 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)." })),
157
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" })),
158
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 })),
159
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 })),
@@ -444,6 +450,29 @@ export const paramSchema = z.object({
444
450
  // the 400-class guard against a zero/negative clock on the wire —
445
451
  // while every grid-legal window at every legal fps passes.
446
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." })),
447
476
  // THE LEGACY ALIASES (renderer-era spellings of the mod switches)
448
477
  // — gate-admitted for old drafts, never user surface: the MODS
449
478
 
@@ -455,6 +484,24 @@ export const paramSchema = z.object({
455
484
  // here is dead surface the estate wtype judge refuses.)
456
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." })),
457
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
+ }
458
505
  /** Schemastery objects are lenient (unknown/missing keys ride); the
459
506
  * family-admission laws are the renderer's own validators, ported:
460
507
  * unknown variant + family-conditional key admission on EXPLICIT
@@ -491,6 +538,12 @@ export const refinePlaneSchema = z.object(Object.fromEntries(REFINE_PLANE_KEYS.m
491
538
  }
492
539
  return [k, knob];
493
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 */
494
547
  export const coerceWireBoolean = (raw) => {
495
548
  if (typeof raw.interpolate_enabled === 'string') {
496
549
 
@@ -526,6 +579,15 @@ export function assertKeyframeRowShape(rows) {
526
579
  }
527
580
  }
528
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 */
529
591
  export function schema(v) {
530
592
  const raw = (v ?? {});
531
593
  if (raw.calls !== undefined && !Array.isArray(raw.calls)) {
@@ -640,6 +702,16 @@ export function schema(v) {
640
702
  }
641
703
  }
642
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
+ }
643
715
  // THE GRID GATE (§26, the walk arm): a call's knobs.length pin
644
716
  // bypasses every snap arm downstream — validate at the walk so
645
717
  // `validate` refuses what the engine would kill at GPU cost.
@@ -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