@aicopycoders/exodus 2026.11.200-beta.1 → 2026.11.700-beta.1

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.
@@ -1,5 +1,74 @@
1
1
  // #2988: the types of the exports the Trigger worker calls. The script is
2
2
  // plain JS so the CLI can run it with `node` and no build.
3
+ import type { SourceIdentity, TextItem, TextPlan, VerifyObservation, RasterMeasurement, MeasureText } from "./first-cut-text.mjs";
4
+
5
+ // The worker's shapes (scout cut-sounds.ts, temporal-action-evidence.ts), kept loose here: the root typecheck
6
+ // runs without scout's packages, so the tool's types must not load the worker.
7
+ type SoundSource =
8
+ | { kind: "generated"; provider: "elevenlabs" }
9
+ | { kind: "library"; assetId: string; bytesVerified: true; [field: string]: unknown };
10
+ type TemporalRequirement = { [field: string]: unknown };
11
+ type TemporalActionReceipt = { [field: string]: unknown };
12
+ import type { PlanningBudget } from "../../../../../video/lib/picturePlan.js";
13
+
14
+ export interface TextRasterEvidence {
15
+ id: string; kind: string; startSec: number; endSec: number;
16
+ renderBox: [number, number, number, number]; box: [number, number, number, number]; fs: number;
17
+ textSha256: string;
18
+ measurement: Omit<RasterMeasurement, "lines">;
19
+ /** ASS centiseconds are selected to rasterize exactly these video frames; heard seconds above are unchanged. */
20
+ raster: { startFrame: number; frames: number; startCs: number; endCs: number };
21
+ }
22
+
23
+ export interface FinishHold { id: string; code: string; reason: string }
24
+ export interface FinalPlanningTiming {
25
+ basis: "decoded-final-picture-clock";
26
+ /** Actual final file bytes; null can never support a known exported timing proof. */
27
+ finalSha256: string | null;
28
+ planned: { targetSeconds: number; overrun: { name: string; seconds: number }; ceilingSeconds: number };
29
+ decoded: { frames: number; fps: 24; seconds: number } | null;
30
+ status: "within-budget" | "over-budget" | "unknown";
31
+ }
32
+ export interface FinishFulfillment {
33
+ ok: boolean;
34
+ lines: Array<{
35
+ lineId: string; sourceSpan: { lineId: string; startChar: number; endChar: number; partId: string } | null;
36
+ retained: string[]; exactCanonicalWords: boolean;
37
+ }>;
38
+ beats: Array<{
39
+ id: string; windows: Array<{ start: number; end: number }>; seconds: number; reservedSeconds: number | null;
40
+ retained: boolean; action: "observed" | "not-temporally-observed" | "not-asked";
41
+ }>;
42
+ /** Separate from output permission; absent on historical finish receipts.
43
+ * Native endings may use a measured spine picture or muted overlay through EOF;
44
+ * either requires the selected owner's uninterrupted observed release. */
45
+ ending?: {
46
+ status: "unselected" | "fulfilled" | "hold"; kind?: string;
47
+ beatId?: string | null; sceneIndex?: number | null;
48
+ startFrame?: number | null; endFrame?: number | null; phaseId?: string | null;
49
+ };
50
+ holds: FinishHold[];
51
+ resolvedPlanningFindings: Array<{ scene: number; code: string; phaseId: string }>;
52
+ }
53
+ export interface TemporalFinishEvidence {
54
+ requirements: TemporalRequirement[];
55
+ owners: Array<{ id: string; sceneIndex: number }>;
56
+ holds: FinishHold[];
57
+ receipt: TemporalActionReceipt | null;
58
+ retention: unknown;
59
+ }
60
+
61
+ export class TextFinishRefusal extends FirstCutError {
62
+ constructor(holds: FinishHold[]);
63
+ readonly holds: FinishHold[];
64
+ }
65
+
66
+ export type ReadoutPreparer = (args: {
67
+ source: SourceIdentity;
68
+ sourceBytes: Uint8Array;
69
+ items: Array<Omit<TextItem, "provenance"> & { provenance?: "physical-readout" | "authentic-lettering"; value?: string; unit?: string }>;
70
+ heardWords?: Array<{ word: string; start: number; end: number; cueLineId?: string }>;
71
+ }) => Promise<VerifyObservation>;
3
72
 
4
73
  export class FirstCutError extends Error {
5
74
  constructor(code: 1 | 2, message: string);
@@ -12,6 +81,133 @@ export class LoudnessRefusal extends FirstCutError {
12
81
  readonly measured: { i: number; tp: number } | null;
13
82
  }
14
83
 
84
+ /** The measured source-to-edit map found a required word, frame or tail it cannot hold; nothing is stretched, sped up or frozen to hide it. */
85
+ export class SourceMapRefusal extends FirstCutError {
86
+ constructor(message: string, findings: SourceMapFinding[]);
87
+ readonly findings: SourceMapFinding[];
88
+ }
89
+
90
+ export interface SourceMapFinding {
91
+ /** "refuse" stops the cut and nothing is delivered; "declared" is a measured fact the cut carries out. */
92
+ severity: "refuse" | "declared";
93
+ code: string;
94
+ scene: number | null;
95
+ detail: string;
96
+ }
97
+
98
+ /**
99
+ * Only with manifest.sourceMap === true, which auto-cut sets when the run's
100
+ * frozen payload turns sourceEditMap on.
101
+ * frames at 1/24 s and edit samples at 48 kHz (2000 a frame) from 0, before
102
+ * any loudness pass. A source picture slot n shows the last decoded frame whose
103
+ * pts (from the first decoded frame) is at or before n/24 (fps=24:round=up);
104
+ * a source sound's zero is its first decoded sample after negative-pts priming,
105
+ * and its words count from it. Sample ranges are in edit samples of the
106
+ * decoded sound as the filter counts it (priming included).
107
+ */
108
+ export interface SourceEditMap {
109
+ version: "source-edit-map.v2";
110
+ fps: 24;
111
+ sampleRate: 48000;
112
+ samplesPerFrame: 2000;
113
+ clock: string;
114
+ frames: number;
115
+ samples: number;
116
+ pieces: Array<{
117
+ /** Scene index, or `scene.n` for the n-th piece of a split take. */
118
+ piece: string;
119
+ sceneIndex: number;
120
+ route: { picture: "clip" | "still"; audio: "clip" | "narration" | "silence" | "whole-voice"; file: string; voice: string | null };
121
+ source: {
122
+ picture: { timeBase: string; originSec: number; frames: number; endSec: number; slots: number } | null;
123
+ audio: { timeBase: string; sampleRate: number; originSec: number; samples: number; primingSamples: number; decodedSec: number } | null;
124
+ /** A clip's own sound zero minus its first picture frame, on whole edit samples. */
125
+ audioMinusPictureSec: number | null;
126
+ } | null;
127
+ edit: { startFrame: number; frames: number; startSample: number; samples: number; residualFrames: number };
128
+ /** Source slots (before sentence-gap cuts) and the decoded frame indexes they show. */
129
+ picture: {
130
+ inSlot: number; lastSlot: number | null; firstFrame: number | null; lastFrame: number | null;
131
+ firstPtsSec: number | null; lastPtsSec: number | null; cutSlots: Array<[number, number]>;
132
+ /** Slots that repeat the decoded frame before (the source's own long frames), and decoded frames no slot shows. */
133
+ repeatedSlots: number; skippedFrames: number;
134
+ /** Edit frames with no decoded frame left: always a "picture-hold" refusal. */
135
+ heldFrames: number;
136
+ /** Explicit selected terminal freeze, never an accidental EOF extension. */
137
+ editorialHold?: {
138
+ sourceSceneIndex: number; sourceSlot: number; sourceFrame: number;
139
+ frames: number; boundary: "retained-end";
140
+ };
141
+ } | null;
142
+ sound: {
143
+ zeroSample: number; fromSample: number; toSample: number; available: number;
144
+ cutSamples: Array<[number, number]>; leadSilenceSamples: number; tailSilenceSamples: number;
145
+ } | null;
146
+ /** One entry per script line the piece speaks; `part` is unique across scenes and pieces. */
147
+ lineParts: Array<{
148
+ part: string; lineId: string; measured: boolean; words?: number; firstWord?: number; lastWord?: number;
149
+ sourceSpan?: { lineId: string; startChar: number; endChar: number; partId: string } | null;
150
+ src?: { startSec: number; endSec: number };
151
+ edit?: { startSec: number; endSec: number; startFrame: number; lastFrame: number };
152
+ /** "phoneme" only when the scribe's words carried phoneme times; an ASR word end proves no last phoneme. */
153
+ endEvidence?: "phoneme" | "asr-word-end";
154
+ }>;
155
+ /** Kept only on a picture event measured on the clip's decoded clock (the manifest scene's actionEvidence). */
156
+ action: Record<"lead" | "tail", {
157
+ wantedSec: number; status: "not-asked" | "unproven" | "kept" | "short";
158
+ eventSec?: number | null; shownSec?: { fromSec: number; toSec: number };
159
+ }>;
160
+ }>;
161
+ overlays: Array<{
162
+ scene: number; source: string; method: string | null; onPiece: number | null; startFrame: number; frames: number;
163
+ startSec: number; seconds: number; picture: { firstFrame: number; lastFrame: number } | null;
164
+ }>;
165
+ wholeVoice: {
166
+ file: string; startFrame: number; startSample: number; declaredSec: number;
167
+ /** Each sung scene's stretch, in frames into the song. */
168
+ intervals: Array<{ scene: number; fromFrame: number; toFrame: number }>;
169
+ sampleRate?: number; primingSamples?: number; decodedSec?: number; samples?: number; endSample?: number; pictureEndSample?: number;
170
+ } | null;
171
+ /** The bytes each measured clock was read from. */
172
+ sources?: Array<{ file: string; bytes: number; sha256: string }>;
173
+ /**
174
+ * What the delivered cut lets be heard, from each piece's actual route and sample windows (edit and
175
+ * source), never from which sounds or songs exist. owner/storageId/acceptedLineIds are only the pull's
176
+ * manifest.sourceMeta for that exact file, else null: unknown, never inferred. sha256 from `sources`.
177
+ */
178
+ audibleSources: Array<{
179
+ file: string; sha256?: string | null; route: "clip" | "narration" | "whole-voice";
180
+ /** null for whole-voice, which is one input across `sceneIndexes`. */
181
+ sceneIndex: number | null; sceneIndexes: number[]; piece: string;
182
+ edit: { fromSample: number; toSample: number };
183
+ source: { fromSample: number; toSample: number; cutSamples: Array<[number, number]> };
184
+ tail?: { editFromSample: number; samples: number };
185
+ lineParts: string[];
186
+ /** sourceMeta[file].kind of the producing artifact; null when the pull does not say (never inferred from route). */
187
+ kind: "native-clip" | "voiceover" | "song-master" | null;
188
+ owner: string | null; acceptedLineIds: string[] | null; storageId: string | null;
189
+ }>;
190
+ /** Picture clips whose own sound the cut does not play: no listen to a source counts for these. */
191
+ mutedPictures: Array<{ file: string; sha256?: string | null; sceneIndex: number | null; piece: string | null }>;
192
+ findings: SourceMapFinding[];
193
+ /** Set after the render, from the finished cut's decoded frames and samples. */
194
+ render?: { frames: number | null; frameDelta: number | null; samples: number | null; sampleDelta: number | null; soundStartSamples: number | null };
195
+ /** Selected frozen maximum checked only against the final decoded picture clock, never generated source sums. */
196
+ planningTiming?: FinalPlanningTiming;
197
+ mix?: {
198
+ fallback: "brown-noise" | "none"; effects: CutSound["effects"]; beds: CutSound["beds"];
199
+ music?: { file: string; sourceSha256: string; sourcePrimingSamples: number; sourceSamples: number; sourceOriginSec: number; loop: true };
200
+ };
201
+ text?: {
202
+ source: SourceIdentity; report: string; permissions: TextPlan["permissions"]; fulfillment: FinishFulfillment;
203
+ styleVersion: "literal-ass.v1"; assSha256: string | null; rasters: TextRasterEvidence[]; readouts: TextPlan["readouts"];
204
+ };
205
+ temporal?: TemporalFinishEvidence;
206
+ /** Original source-clock uncertainty, resolved ONLY by the linked exact-pretext temporal receipt. */
207
+ semanticPlanningFindings?: SourceMapFinding[];
208
+ final?: { sha256: string };
209
+ }
210
+
15
211
  /** The pace record first-cut writes beside the cut when a finishing setting is on. */
16
212
  export interface CutPace {
17
213
  seconds: { ours: number; source: number | null; ratio: number | null };
@@ -23,16 +219,59 @@ export interface CutPace {
23
219
  wordsPerMin: { ours: number | null; source: number | null };
24
220
  deadAir: { over03s: number; longestSec: number };
25
221
  /** The settings the cut was made with, from the manifest's `finishing`. */
26
- finishing: { cutPace: boolean; captions: boolean; cards: boolean; finishLoudness: boolean; targetSeconds?: number };
27
- loudness?: { lufs: number; truePeak: number; passes: 1 | 2 };
222
+ finishing: {
223
+ cutPace: boolean;
224
+ captions: boolean;
225
+ cards: boolean;
226
+ finishLoudness: boolean;
227
+ targetSeconds?: number;
228
+ /** Each setting below is present only when it is on. */
229
+ captionsByLine?: true;
230
+ cleanVoice?: true;
231
+ limitPeaks?: true;
232
+ brollMinSec?: number;
233
+ speedUpSlowBroll?: true;
234
+ cutChecks?: true;
235
+ };
236
+ /** `limited`: limitPeaks' limiter ran after the loudness pass. */
237
+ loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true };
238
+ /** Present only with cutChecks. */
239
+ checks?: CutChecks;
28
240
  notes?: string[];
29
241
  }
30
242
 
243
+ /** What cutChecks measured on the finished cut, and what fails its bars. */
244
+ export interface CutChecks {
245
+ /** Caption screens holding words of two script lines, in the cut's time before any speed-up; null when no captions were burned. */
246
+ lineMixes: Array<{ s: number; text: string }> | null;
247
+ /** The voice's loudness over everything under it; null with a song laid whole or a silent voice. */
248
+ voiceOverBedDb: number | null;
249
+ voiceLufs: number | null;
250
+ bedLufs: number | null;
251
+ repeats: Array<{ phrase: string; firstAt: number; againAt: number }>;
252
+ shortShots: Array<{ n: number; role: string; at: number; sec: number }>;
253
+ /** null when ffmpeg could not read the cut's motion. */
254
+ slowShots: Array<{ n: number; role: string; at: number; sec: number; motion: number; median: number }> | null;
255
+ lufs: number | null;
256
+ truePeak: number | null;
257
+ verdict: { pass: boolean; fails: string[] };
258
+ }
259
+
31
260
  /** What the cut did with the manifest's `sound`: where each sound and bed played and how loud, and what it left out. */
32
261
  export interface CutSound {
33
262
  voiceLufs: number | null;
34
- effects: Array<{ file: string; cueLineId: string; atSec: number; gainDb: number }>;
35
- beds: Array<{ file: string; fromScene: number; startSec: number; seconds: number; gainDb: number }>;
263
+ effects: Array<{
264
+ file: string; cueLineId: string; atSec: number; gainDb: number; source?: SoundSource;
265
+ /** Intended heard cue, independent from the actual file placement/event offset. */
266
+ plannedOnsetSec?: number;
267
+ sourceSha256?: string; placementOffsetSec?: number; editStartSample?: number; sourceStartSample?: number; servedStorageId?: string;
268
+ sourcePrimingSamples?: number; sourceSamples?: number; sourceOriginSec?: number;
269
+ }>;
270
+ beds: Array<{
271
+ file: string; fromScene: number; startSec: number; seconds: number; gainDb: number; source?: SoundSource;
272
+ sourceSha256?: string; loop?: true; editStartSample?: number; samples?: number; servedStorageId?: string;
273
+ sourcePrimingSamples?: number; sourceSamples?: number; sourceOriginSec?: number;
274
+ }>;
36
275
  music?: { gainDb: number; duck: { threshold: number; ratio: number; attack: number; release: number } };
37
276
  /** The music-only master's file name, beside the cut. */
38
277
  master?: string;
@@ -49,6 +288,8 @@ export interface FirstCutOptions {
49
288
  music?: boolean;
50
289
  /** #3365: hold a scene's keyframe where it has no clip, instead of refusing. Defaults to off. */
51
290
  stillFill?: boolean;
291
+ /** With the measured map only: render immutable pre-text pixels, then complete with completeFirstCutText. */
292
+ prepareText?: boolean;
52
293
  }
53
294
 
54
295
  export interface FirstCut {
@@ -57,15 +298,51 @@ export interface FirstCut {
57
298
  /** The music file the cut used, or null. */
58
299
  music: string | null;
59
300
  timeline: { spine: Array<{ sceneIndex: number }>; left: string[] };
301
+ /** Budget-only decoded receipt; also supported when sourceEditMap is absent. */
302
+ planningTiming?: FinalPlanningTiming;
60
303
  /** Present only when the manifest turned a finishing setting on. */
61
304
  pace?: CutPace;
62
305
  /** Present only when the manifest names sounds, beds, a ducked music bed or a music-only master. */
63
306
  sound?: CutSound;
64
307
  /** The music-only master's path, when one was made. */
65
308
  musicOnlyMaster?: string;
309
+ /** Present only when the manifest asked for the measured map.
310
+ * Authored picture time is reserved once per take; only its final split piece
311
+ * may extend, so earlier pieces never replay the resumed piece's source audio.
312
+ * A frozen finalWordTailSec stays in that final voiced take after its complete
313
+ * final heard word, with visible living-tail observation, never silent fill. */
314
+ sourceMap?: SourceEditMap;
315
+ /** Internal prepared artifact; cannot be attached as a completed text finish. */
316
+ textStage?: { dir: string; board: unknown; policy: unknown };
317
+ text?: TextPlan;
66
318
  }
67
319
 
320
+ /** The map's file beside the cut: <name>.source-map.json. */
321
+ export function sourceMapPath(outPath: string): string;
322
+
68
323
  export function firstCut(options: FirstCutOptions): FirstCut;
324
+ /** Measures the actual final file without constructing a source map or changing media. */
325
+ export function measureCutPlanningTiming(file: string, planningBudget: PlanningBudget): {
326
+ planningTiming: FinalPlanningTiming;
327
+ findings: SourceMapFinding[];
328
+ };
329
+
330
+ export interface TextRenderer {
331
+ libass: boolean;
332
+ measureText?: MeasureText;
333
+ assertFont?: () => boolean;
334
+ }
335
+
336
+ /** Observes the exact prepared pixels, measures/renders literal text, stream-copies sound and re-probes the final target. */
337
+ export function completeFirstCutText(cut: FirstCut, options?: {
338
+ out?: string;
339
+ prepareReadoutVerifier?: ReadoutPreparer;
340
+ observeTemporalAction?: (args: never) => Promise<unknown>;
341
+ checkTemporalRetention?: (args: never) => unknown;
342
+ renderer?: TextRenderer;
343
+ }): Promise<FirstCut>;
344
+ /** Decodes final mixed sound, never a separated cue; no causal attribution. */
345
+ export function measureCutAudio(file: string): { windowSec: number; db: number[] } | null;
69
346
 
70
347
  /** #3365: the scenes the cut cannot be made without, by number. */
71
348
  export function scenesWithNoClip(options: {