@nodaro/shared 3.21.0 → 3.23.0

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.
Files changed (84) hide show
  1. package/dist/index.cjs +2284 -195
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +1915 -75
  4. package/dist/index.d.ts +1915 -75
  5. package/dist/index.js +2117 -196
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/add-captions-plan.test.ts +33 -0
  9. package/src/__tests__/caption-plan-parse.test.ts +23 -0
  10. package/src/__tests__/caption-segment-schema.test.ts +30 -0
  11. package/src/__tests__/collections.test.ts +253 -0
  12. package/src/__tests__/dialogue-capabilities.test.ts +157 -0
  13. package/src/__tests__/edit-plan-review.test.ts +70 -0
  14. package/src/__tests__/edl-clocks.test.ts +97 -0
  15. package/src/__tests__/edl.test.ts +34 -0
  16. package/src/__tests__/execution-outcome.test.ts +44 -0
  17. package/src/__tests__/fan-out-meta.test.ts +23 -0
  18. package/src/__tests__/fan-out-rows.test.ts +36 -0
  19. package/src/__tests__/fan-out-url-item.test.ts +44 -0
  20. package/src/__tests__/fixtures/speaker-tracks.fixtures.json +622 -0
  21. package/src/__tests__/input-field-extra-keys.test.ts +34 -0
  22. package/src/__tests__/list-consumers-fan-in.test.ts +40 -0
  23. package/src/__tests__/model-tree.test.ts +7 -0
  24. package/src/__tests__/node-pass-through.test.ts +23 -0
  25. package/src/__tests__/node-runtime-keys.test.ts +1 -0
  26. package/src/__tests__/picker-restrictions.test.ts +36 -0
  27. package/src/__tests__/preview-gate.test.ts +305 -0
  28. package/src/__tests__/render-basis.test.ts +176 -0
  29. package/src/__tests__/render-nodes.test.ts +73 -0
  30. package/src/__tests__/render-output.test.ts +392 -0
  31. package/src/__tests__/run-continuation.test.ts +32 -0
  32. package/src/__tests__/speaker-tracks.test.ts +474 -0
  33. package/src/__tests__/speech-pricing.test.ts +69 -0
  34. package/src/__tests__/telegram-channel.test.ts +91 -0
  35. package/src/__tests__/tts-capabilities.test.ts +81 -4
  36. package/src/__tests__/tts-neighbour-text.test.ts +19 -0
  37. package/src/__tests__/ugc-call-body.test.ts +38 -0
  38. package/src/__tests__/ugc-run-state.test.ts +68 -0
  39. package/src/__tests__/video-character-refs.test.ts +213 -0
  40. package/src/__tests__/video-overlay-layer-plan.test.ts +94 -0
  41. package/src/add-captions-plan.ts +50 -0
  42. package/src/caption-plan.ts +45 -0
  43. package/src/caption-segment-schema.ts +82 -0
  44. package/src/collections.ts +462 -0
  45. package/src/competitors.ts +77 -0
  46. package/src/credit-estimators/index.ts +9 -0
  47. package/src/credit-estimators/speech.ts +51 -0
  48. package/src/dialogue-capabilities.ts +48 -0
  49. package/src/edit-plan-contract.ts +20 -9
  50. package/src/edit-plan-review.ts +40 -1
  51. package/src/edl.ts +27 -1
  52. package/src/execution-outcome.ts +41 -0
  53. package/src/fan-out-meta.ts +23 -0
  54. package/src/fan-out-rows.ts +74 -5
  55. package/src/gemini-omni-voices.ts +59 -0
  56. package/src/handle-aliases.ts +295 -0
  57. package/src/i18n/camera-motions.pt-BR.ts +14 -14
  58. package/src/i18n/transitions.pt-BR.ts +13 -13
  59. package/src/index.ts +179 -1
  60. package/src/model-catalog.ts +122 -13
  61. package/src/model-constants.ts +24 -4
  62. package/src/model-tree.ts +5 -1
  63. package/src/node-execution-state.ts +13 -0
  64. package/src/node-mappable-fields.ts +7 -1
  65. package/src/node-pass-through.ts +37 -0
  66. package/src/node-runtime-keys.ts +14 -0
  67. package/src/picker-restrictions.ts +49 -0
  68. package/src/presentation-types.ts +26 -2
  69. package/src/presentation-utils.ts +25 -7
  70. package/src/preview-gate.ts +279 -0
  71. package/src/producer-types.ts +58 -0
  72. package/src/render-final.ts +20 -0
  73. package/src/render-nodes.ts +92 -0
  74. package/src/render-output.ts +565 -0
  75. package/src/run-continuation.ts +39 -0
  76. package/src/speaker-tracks.ts +638 -0
  77. package/src/telegram-channel.ts +140 -0
  78. package/src/transcribe-preflight.ts +8 -4
  79. package/src/tts-capabilities.ts +19 -5
  80. package/src/tts-neighbour-text.ts +46 -0
  81. package/src/ugc-call-body.ts +86 -0
  82. package/src/ugc-run-state.ts +64 -0
  83. package/src/video-character-refs.ts +233 -0
  84. package/src/video-overlay.ts +78 -21
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The list operators consume the WHOLE list wired into them and are never run
3
+ * once per item. Both engines' fan-out planners read `FAN_IN_TARGETS` first
4
+ * (`isFanInNodeType` → no fan-out), so this table is the one rule.
5
+ *
6
+ * 2026-10-06: a Filter List fed by a Split Text (an "each" wire by default) was
7
+ * fanned out 11 times by the orchestrator; every iteration collected the same
8
+ * whole list and emitted its first match, so the stages after it ran 11 times
9
+ * on one story.
10
+ */
11
+ import { describe, it, expect } from "vitest"
12
+ import { FAN_IN_TARGETS, FAN_OUT_EACH_TYPES, isFanInEdge, isFanInNodeType } from "../producer-types.js"
13
+
14
+ const LIST_OPERATORS = ["filter-list", "deduplicate", "merge-lists", "sort-list", "selector"] as const
15
+
16
+ describe("list operators are fan-in targets", () => {
17
+ for (const type of LIST_OPERATORS) {
18
+ it(`${type} folds every wire — it is never fanned out`, () => {
19
+ expect(isFanInNodeType(type)).toBe(true)
20
+ expect(FAN_IN_TARGETS[type]).toBe("*")
21
+ for (const handle of ["in", "variables", null, undefined]) {
22
+ expect(isFanInEdge(type, handle)).toBe(true)
23
+ }
24
+ })
25
+ }
26
+
27
+ it("a list operator still fans its OWN output out per item downstream (an each source)", () => {
28
+ // Being a fan-in TARGET says nothing about the wire that leaves the node:
29
+ // Filter List → Generate Image still runs the image once per kept item.
30
+ for (const type of ["filter-list", "deduplicate", "merge-lists", "sort-list", "selector"]) {
31
+ expect(FAN_OUT_EACH_TYPES.has(type)).toBe(true)
32
+ }
33
+ })
34
+
35
+ it("the text producers that feed them are not fan-in targets", () => {
36
+ for (const type of ["split-text", "list", "llm-chat", "combine-text", "extract-field"]) {
37
+ expect(isFanInNodeType(type)).toBe(false)
38
+ }
39
+ })
40
+ })
@@ -26,6 +26,13 @@ describe("modelToNodeTarget", () => {
26
26
  it("returns a provider preset for an enum video model (gemini-omni-video is enum-valid)", () => {
27
27
  expect(modelToNodeTarget("gemini-omni-video")).toEqual({ nodeType: "generate-video", field: "provider", value: "gemini-omni-video" })
28
28
  })
29
+ // A dialogue id IS a provider-enum value (DIALOGUE_PROVIDERS), so picking a
30
+ // dialogue model in the Models tab creates a node preset to THAT model — a
31
+ // bare node would run as the default (v3 dialogue) whatever was picked.
32
+ it("a dialogue model creates a Text to Dialogue node preset to that model", () => {
33
+ expect(modelToNodeTarget("elevenlabs-dialogue-v4")).toEqual({ nodeType: "text-to-dialogue", field: "provider", value: "elevenlabs-dialogue-v4" })
34
+ expect(modelToNodeTarget("elevenlabs-dialogue")).toEqual({ nodeType: "text-to-dialogue", field: "provider", value: "elevenlabs-dialogue" })
35
+ })
29
36
  it("returns null when there is no node (video-audit) or unknown id", () => {
30
37
  expect(modelToNodeTarget("video-audit")).toBeNull()
31
38
  expect(modelToNodeTarget("totally-unknown")).toBeNull()
@@ -0,0 +1,23 @@
1
+ import { describe, expect, it } from "vitest"
2
+ import { captionPlanPassThrough, combineVideosPassThrough, videoOverlayPassThrough } from "../node-pass-through.js"
3
+
4
+ describe("pass-through rules (R14)", () => {
5
+ it("one resolved video passes Combine Videos through; two or none do not", () => {
6
+ expect(combineVideosPassThrough(["https://cdn.example/a.mp4"])).toEqual({ videoUrl: "https://cdn.example/a.mp4", warning: "single_input" })
7
+ expect(combineVideosPassThrough(["https://cdn.example/a.mp4", "", null])).toEqual({ videoUrl: "https://cdn.example/a.mp4", warning: "single_input" })
8
+ expect(combineVideosPassThrough(["https://cdn.example/a.mp4", "https://cdn.example/b.mp4"])).toBeNull()
9
+ expect(combineVideosPassThrough([])).toBeNull()
10
+ })
11
+ it("an empty wired layer plan with no other layer passes Video Overlay through", () => {
12
+ expect(videoOverlayPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: true, layerCount: 0 })).toEqual({ videoUrl: "https://cdn.example/v.mp4", warning: "no_layers" })
13
+ expect(videoOverlayPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: true, layerCount: 1 })).toBeNull()
14
+ // No plan wired: an empty overlay is still the validator's no_layers error, never a silent pass-through.
15
+ expect(videoOverlayPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: false, layerCount: 0 })).toBeNull()
16
+ expect(videoOverlayPassThrough({ videoUrl: undefined, planWired: true, layerCount: 0 })).toBeNull()
17
+ })
18
+ it("a wired caption plan with no segments passes Add Captions through", () => {
19
+ expect(captionPlanPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: true, segmentCount: 0 })).toEqual({ videoUrl: "https://cdn.example/v.mp4", warning: "no_captions" })
20
+ expect(captionPlanPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: true, segmentCount: 2 })).toBeNull()
21
+ expect(captionPlanPassThrough({ videoUrl: "https://cdn.example/v.mp4", planWired: false, segmentCount: 0 })).toBeNull()
22
+ })
23
+ })
@@ -30,6 +30,7 @@ describe("TRANSIENT_RUNTIME_KEYS", () => {
30
30
  "__listTotal",
31
31
  "__listCompleted",
32
32
  "__listRunning",
33
+ "__runSkipReason",
33
34
  "__runsInFlight",
34
35
  "_upstreamRefresh",
35
36
  "__upstreamCount",
@@ -0,0 +1,36 @@
1
+ import { describe, expect, it } from "vitest"
2
+ import { findRestrictedPickerValue } from "../picker-restrictions.js"
3
+
4
+ const nodes = [{ id: "person", type: "person" }, { id: "setting", type: "setting" }, { id: "site", type: "text-prompt" }]
5
+ const cardMeta = {
6
+ person: { pickerAllowedValuesByField: { age: ["age-20s", "age-30s"], type: ["office-worker"] } },
7
+ setting: { pickerAllowedValues: ["kitchen", "studio"] },
8
+ }
9
+
10
+ describe("server check of picker restrictions (R4)", () => {
11
+ it("passes allowed values and untouched fields", () => {
12
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { person: { age: "age-30s" }, setting: { setting: "studio" }, site: { text: "x" } } })).toBeNull()
13
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: undefined })).toBeNull()
14
+ expect(findRestrictedPickerValue({ cardMeta: undefined, nodes, inputValues: { person: { age: "anything" } } })).toBeNull()
15
+ })
16
+ it("refuses a value outside a per-field restriction, including inside a list", () => {
17
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { person: { age: "age-teen" } } })).toBe("Invalid value for age: age-teen. Allowed: age-20s, age-30s")
18
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { person: { type: ["office-worker", "princess"] } } })).toBe("Invalid value for type: princess. Allowed: office-worker")
19
+ })
20
+ it("applies a single-dimension restriction to the representative field", () => {
21
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { setting: { setting: "beach" } } })).toBe("Invalid value for setting: beach. Allowed: kitchen, studio")
22
+ })
23
+ it("treats an empty allowed list as no restriction, and ignores a node the snapshot does not hold", () => {
24
+ const empty = { person: { pickerAllowedValuesByField: { age: [] as string[] } }, ghost: { pickerAllowedValues: ["a"] } }
25
+ expect(findRestrictedPickerValue({ cardMeta: empty, nodes, inputValues: { person: { age: "age-teen" }, ghost: { x: "b" } } })).toBeNull()
26
+ })
27
+ it("refuses a non-string value where a catalog id belongs; an unset pick passes", () => {
28
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { person: { age: 30 } } })).toBe("Invalid value for age: 30. Allowed: age-20s, age-30s")
29
+ expect(findRestrictedPickerValue({ cardMeta, nodes, inputValues: { person: { age: "", type: [] } } })).toBeNull()
30
+ })
31
+ it("reads a submitted legacy spelling of a field through its canonical key", () => {
32
+ const tts = { tts: { pickerAllowedValuesByField: { similarityBoost: ["0.5"] } } }
33
+ const ttsNodes = [{ id: "tts", type: "text-to-speech" }]
34
+ expect(findRestrictedPickerValue({ cardMeta: tts, nodes: ttsNodes, inputValues: { tts: { similarity: "0.9" } } })).toBe("Invalid value for similarityBoost: 0.9. Allowed: 0.5")
35
+ })
36
+ })
@@ -0,0 +1,305 @@
1
+ import { describe, it, expect } from "vitest"
2
+ // Through the package index: the stop rule is the public surface both engines,
3
+ // the editor and SDK users decide "does this run stop at a preview?" with.
4
+ import {
5
+ PREVIEW_RENDER_NODE_TYPES,
6
+ PREVIEW_REVIEW_REQUIRED,
7
+ PREVIEW_RENDER_NESTED,
8
+ RUN_OVERRIDE_CLEARED_FIELDS,
9
+ SAVED_RENDER_STAMPS,
10
+ NO_SAVED_RENDER_STAMPS,
11
+ rendersAsPreview,
12
+ previewStops,
13
+ previewGatedNodeIds,
14
+ holdsPreviewRender,
15
+ withRunOverrides,
16
+ type PreviewGateNode,
17
+ type PreviewGateEdge,
18
+ type SavedRenderStampReader,
19
+ } from "../index.js"
20
+
21
+ const node = (id: string, type: string, data: Record<string, unknown> = {}, parentId?: string): PreviewGateNode => ({
22
+ id,
23
+ type,
24
+ data,
25
+ ...(parentId ? { parentId } : {}),
26
+ })
27
+ const edge = (source: string, target: string, extra: Partial<PreviewGateEdge> = {}): PreviewGateEdge => ({
28
+ source,
29
+ target,
30
+ ...extra,
31
+ })
32
+
33
+ /** Tighten Episode's shape: transcribe → plan → render → captions → reply. */
34
+ function tighten(quality: "proxy" | "final" | undefined) {
35
+ const nodes = [
36
+ node("rec", "upload-video"),
37
+ node("tx", "transcribe"),
38
+ node("plan", "edit-plan"),
39
+ node("cut", "apply-edl", quality ? { quality } : {}),
40
+ node("cap", "add-captions"),
41
+ node("reply", "telegram-reply"),
42
+ ]
43
+ const edges = [
44
+ edge("rec", "tx"),
45
+ edge("tx", "plan"),
46
+ edge("plan", "cut", { targetHandle: "edl" }),
47
+ edge("cut", "cap"),
48
+ edge("cap", "reply"),
49
+ ]
50
+ return { nodes, edges }
51
+ }
52
+
53
+ describe("PREVIEW_RENDER_NODE_TYPES", () => {
54
+ it("names the render nodes a run can stop at (apply-edl; speaker-view joins when it lands)", () => {
55
+ expect([...PREVIEW_RENDER_NODE_TYPES]).toEqual(["apply-edl"])
56
+ })
57
+ })
58
+
59
+ describe("stable refusal codes", () => {
60
+ it("are distinct, snake_case and stable (clients branch on them, never on text)", () => {
61
+ expect(PREVIEW_REVIEW_REQUIRED).toBe("preview_review_required")
62
+ expect(PREVIEW_RENDER_NESTED).toBe("preview_render_nested")
63
+ })
64
+ })
65
+
66
+ describe("rendersAsPreview — the render's effective quality in this run", () => {
67
+ it("is true only for a render node set to proxy", () => {
68
+ expect(rendersAsPreview(node("a", "apply-edl", { quality: "proxy" }))).toBe(true)
69
+ expect(rendersAsPreview(node("a", "apply-edl", { quality: "final" }))).toBe(false)
70
+ expect(rendersAsPreview(node("a", "apply-edl", {}))).toBe(false)
71
+ expect(rendersAsPreview(node("a", "speed-ramp", { quality: "proxy" }))).toBe(false)
72
+ })
73
+ })
74
+
75
+ describe("previewStops — the derived stop rule (TA8 a)", () => {
76
+ it("a run whose render is Proxy gates its whole forward closure, never the render itself", () => {
77
+ const { nodes, edges } = tighten("proxy")
78
+ const stops = previewStops(nodes, edges)
79
+ expect(stops.previewRenderIds).toEqual(["cut"])
80
+ expect(stops.savedPreviewRenderIds).toEqual([])
81
+ expect([...stops.gatedNodeIds].sort()).toEqual(["cap", "reply"])
82
+ })
83
+
84
+ it("a Final render gates nothing", () => {
85
+ const { nodes, edges } = tighten("final")
86
+ expect(previewGatedNodeIds(nodes, edges).size).toBe(0)
87
+ expect(holdsPreviewRender(nodes, edges)).toBe(false)
88
+ })
89
+
90
+ it("is a forward closure, not router gating: a Combine fed by the render AND an intro upload stops too", () => {
91
+ const nodes = [
92
+ node("plan", "edit-plan"),
93
+ node("cut", "apply-edl", { quality: "proxy" }),
94
+ node("intro", "upload-video"),
95
+ node("combine", "combine-videos"),
96
+ node("out", "webhook-output"),
97
+ ]
98
+ const edges = [edge("plan", "cut"), edge("cut", "combine"), edge("intro", "combine"), edge("combine", "out")]
99
+ expect([...previewGatedNodeIds(nodes, edges)].sort()).toEqual(["combine", "out"])
100
+ })
101
+
102
+ it("follows every way a node feeds another: teleports, Group membership and field mappings", () => {
103
+ const nodes = [
104
+ node("cut", "apply-edl", { quality: "proxy" }),
105
+ node("send", "teleport-send"),
106
+ node("recv", "teleport-receive"),
107
+ node("cap", "add-captions", {}, "grp"),
108
+ node("grp", "group"),
109
+ node("llm", "llm-chat", { fieldMappings: { prompt: { sourceNodeId: "cap" } } }),
110
+ ]
111
+ const edges = [edge("cut", "send"), edge("send", "recv"), edge("recv", "cap")]
112
+ expect([...previewGatedNodeIds(nodes, edges)].sort()).toEqual(["cap", "grp", "llm", "recv", "send"])
113
+ })
114
+
115
+ it("a render that does not execute in this run is not a Preview by its config (its SAVED output decides)", () => {
116
+ const { nodes, edges } = tighten("proxy")
117
+ const stops = previewStops(nodes, edges, { executes: (id) => id !== "cut" })
118
+ expect(stops.previewRenderIds).toEqual([])
119
+ expect(stops.gatedNodeIds.size).toBe(0)
120
+ })
121
+
122
+ it("a frozen (skipped) render does not execute by default", () => {
123
+ const { nodes, edges } = tighten("proxy")
124
+ const frozen = nodes.map((n) => (n.id === "cut" ? { ...n, data: { ...(n.data as object), skipped: true } } : n))
125
+ expect(previewStops(frozen, edges).previewRenderIds).toEqual([])
126
+ })
127
+
128
+ it("a render downstream of another preview is itself gated (it would consume a preview)", () => {
129
+ const nodes = [node("a", "apply-edl", { quality: "proxy" }), node("b", "apply-edl", { quality: "proxy" })]
130
+ const edges = [edge("a", "b", { targetHandle: "sources" })]
131
+ const stops = previewStops(nodes, edges)
132
+ expect(stops.previewRenderIds).toEqual(["a", "b"])
133
+ expect([...stops.gatedNodeIds]).toEqual(["b"])
134
+ })
135
+
136
+ it("ignores edges whose ends are not on the graph", () => {
137
+ const { nodes, edges } = tighten("proxy")
138
+ expect([...previewGatedNodeIds(nodes, [...edges, edge("cut", "ghost")])].sort()).toEqual(["cap", "reply"])
139
+ })
140
+ })
141
+
142
+ describe("previewStops — the saved-preview half (TA8 a, second case)", () => {
143
+ // A stand-in for the saved-output reader (`savedRenderOutput` /
144
+ // `savedRenderBatch`): the selected result is the Final, the latest batch
145
+ // holds a Preview.
146
+ const reader: SavedRenderStampReader = {
147
+ output: (data) => (data.selected === "proxy" ? { quality: "proxy" } : { quality: "final" }),
148
+ batch: (data) => (Array.isArray(data.batch) ? (data.batch as string[]).map((q) => (q ? { quality: q } : null)) : undefined),
149
+ }
150
+ const outsideRun = { executes: (id: string) => id !== "cut", savedRenders: reader }
151
+
152
+ it("a scalar edge from a saved render whose selected result is a Final stays open", () => {
153
+ const nodes = [node("cut", "apply-edl", { batch: ["proxy"] }), node("cap", "add-captions"), node("out", "webhook-output")]
154
+ const edges = [edge("cut", "cap"), edge("cap", "out")]
155
+ const stops = previewStops(nodes, edges, outsideRun)
156
+ expect(stops.savedPreviewRenderIds).toEqual([])
157
+ expect(stops.gatedNodeIds.size).toBe(0)
158
+ })
159
+
160
+ it("a scalar edge from a saved render whose selected result is a Preview is gated, with its closure", () => {
161
+ const nodes = [node("cut", "apply-edl", { selected: "proxy" }), node("cap", "add-captions"), node("out", "webhook-output")]
162
+ const edges = [edge("cut", "cap"), edge("cap", "out")]
163
+ const stops = previewStops(nodes, edges, outsideRun)
164
+ expect(stops.savedPreviewRenderIds).toEqual(["cut"])
165
+ expect([...stops.gatedNodeIds].sort()).toEqual(["cap", "out"])
166
+ })
167
+
168
+ it("an each edge reads the latest batch: one Preview row in it gates the consumer (TA6)", () => {
169
+ const nodes = [node("cut", "apply-edl", { batch: ["final", "", "proxy"] }), node("cap", "add-captions")]
170
+ const edges = [edge("cut", "cap", { data: { outputMode: "each" } })]
171
+ expect([...previewStops(nodes, edges, outsideRun).gatedNodeIds]).toEqual(["cap"])
172
+ })
173
+
174
+ it("an each edge from a render with no batch reads its one result", () => {
175
+ const nodes = [node("cut", "apply-edl", { selected: "proxy" }), node("cap", "add-captions")]
176
+ const edges = [edge("cut", "cap", { data: { outputMode: "each" } })]
177
+ expect([...previewStops(nodes, edges, outsideRun).gatedNodeIds]).toEqual(["cap"])
178
+ })
179
+
180
+ it("decides per edge: the each consumer stops while the scalar one reads the selected Final", () => {
181
+ const nodes = [node("cut", "apply-edl", { batch: ["proxy"] }), node("each", "add-captions"), node("one", "upload-post")]
182
+ const edges = [edge("cut", "each", { data: { outputMode: "each" } }), edge("cut", "one")]
183
+ expect([...previewStops(nodes, edges, outsideRun).gatedNodeIds]).toEqual(["each"])
184
+ })
185
+
186
+ it("a field mapping or Group fed by the saved render reads its one result", () => {
187
+ const nodes = [
188
+ node("cut", "apply-edl", { selected: "proxy" }, "grp"),
189
+ node("grp", "group"),
190
+ node("llm", "llm-chat", { fieldMappings: { prompt: { sourceNodeId: "cut" } } }),
191
+ ]
192
+ expect([...previewStops(nodes, [], outsideRun).gatedNodeIds].sort()).toEqual(["grp", "llm"])
193
+ })
194
+
195
+ // Through a teleport pair the resolvers read the CONSUMER's wire: its own
196
+ // outputMode, else the default for the real source (the render) on the
197
+ // render-side handle. The render → send wire's mode is never read.
198
+ it("through a teleport pair, an each consumer reads the latest batch and stops", () => {
199
+ const nodes = [
200
+ node("cut", "apply-edl", { batch: ["proxy"] }),
201
+ node("send", "teleport-send"),
202
+ node("recv", "teleport-receive"),
203
+ node("cap", "add-captions"),
204
+ node("out", "webhook-output"),
205
+ ]
206
+ const edges = [
207
+ edge("cut", "send"),
208
+ edge("send", "recv"),
209
+ edge("recv", "cap", { data: { outputMode: "each" } }),
210
+ edge("cap", "out"),
211
+ ]
212
+ const stops = previewStops(nodes, edges, outsideRun)
213
+ expect(stops.savedPreviewRenderIds).toEqual(["cut"])
214
+ expect([...stops.gatedNodeIds].sort()).toEqual(["cap", "out"])
215
+ })
216
+
217
+ it("through a teleport pair, a scalar consumer reads the selected Final even when the send wire says each", () => {
218
+ const nodes = [
219
+ node("cut", "apply-edl", { batch: ["proxy"] }),
220
+ node("send", "teleport-send"),
221
+ node("recv", "teleport-receive"),
222
+ node("cap", "add-captions"),
223
+ ]
224
+ const edges = [
225
+ edge("cut", "send", { data: { outputMode: "each" } }),
226
+ edge("send", "recv"),
227
+ edge("recv", "cap"),
228
+ ]
229
+ expect(previewStops(nodes, edges, outsideRun).gatedNodeIds.size).toBe(0)
230
+ })
231
+
232
+ it("through a teleport pair, decides per consumer: only the each one stops", () => {
233
+ const nodes = [
234
+ node("cut", "apply-edl", { batch: ["proxy"] }),
235
+ node("send", "teleport-send"),
236
+ node("recv", "teleport-receive"),
237
+ node("each", "add-captions"),
238
+ node("one", "upload-post"),
239
+ ]
240
+ const edges = [
241
+ edge("cut", "send"),
242
+ edge("send", "recv"),
243
+ edge("recv", "each", { data: { outputMode: "each" } }),
244
+ edge("recv", "one"),
245
+ ]
246
+ expect([...previewStops(nodes, edges, outsideRun).gatedNodeIds]).toEqual(["each"])
247
+ })
248
+
249
+ it("is inert in production until the saved-output reader is plugged in (no result carries a stamp yet)", () => {
250
+ expect(SAVED_RENDER_STAMPS).toBe(NO_SAVED_RENDER_STAMPS)
251
+ const nodes = [node("cut", "apply-edl", { selected: "proxy", batch: ["proxy"] }), node("cap", "add-captions")]
252
+ const edges = [edge("cut", "cap")]
253
+ expect(previewStops(nodes, edges, { executes: (id) => id !== "cut" }).gatedNodeIds.size).toBe(0)
254
+ })
255
+ })
256
+
257
+ describe("holdsPreviewRender — is there anything a reviewer would have to review?", () => {
258
+ it("true for a Preview render in the run, even with nothing downstream of it", () => {
259
+ expect(holdsPreviewRender([node("cut", "apply-edl", { quality: "proxy" })], [])).toBe(true)
260
+ })
261
+
262
+ it("true for a saved Preview the run would hand downstream", () => {
263
+ const reader: SavedRenderStampReader = { output: () => ({ quality: "proxy" }), batch: () => undefined }
264
+ const nodes = [node("cut", "apply-edl"), node("cap", "add-captions")]
265
+ expect(holdsPreviewRender(nodes, [edge("cut", "cap")], { executes: (id) => id !== "cut", savedRenders: reader })).toBe(true)
266
+ })
267
+ })
268
+
269
+ describe("withRunOverrides — the run's graph after its input overrides", () => {
270
+ it("a Final override on the render lifts the stop (Render final's one-shot override, TA18)", () => {
271
+ const { nodes, edges } = tighten("proxy")
272
+ const run = withRunOverrides(nodes, { cut: { quality: "final" } })
273
+ expect(previewGatedNodeIds(run, edges).size).toBe(0)
274
+ // The saved graph is never mutated.
275
+ expect((nodes.find((n) => n.id === "cut")!.data as { quality: string }).quality).toBe("proxy")
276
+ })
277
+
278
+ it("a proxy override on a Final render stops the run (Update preview)", () => {
279
+ const { nodes, edges } = tighten("final")
280
+ expect([...previewGatedNodeIds(withRunOverrides(nodes, { cut: { quality: "proxy" } }), edges)].sort()).toEqual(["cap", "reply"])
281
+ })
282
+
283
+ it("clears the overridden node's saved results, as the server merge does", () => {
284
+ const n = node("cut", "apply-edl", {
285
+ quality: "proxy",
286
+ generatedResults: [{ url: "u" }],
287
+ activeResultIndex: 0,
288
+ generatedVideoUrl: "u",
289
+ generatedAudioUrl: "a",
290
+ generatedImageUrl: "i",
291
+ generatedText: "t",
292
+ label: "Cut",
293
+ })
294
+ const [merged] = withRunOverrides([n], { cut: { quality: "final" } })
295
+ for (const key of RUN_OVERRIDE_CLEARED_FIELDS) expect(merged.data).not.toHaveProperty(key)
296
+ expect(merged.data).toMatchObject({ quality: "final", label: "Cut" })
297
+ })
298
+
299
+ it("leaves nodes with no override untouched (same object)", () => {
300
+ const { nodes } = tighten("proxy")
301
+ const run = withRunOverrides(nodes, { cut: { quality: "final" } })
302
+ expect(run[0]).toBe(nodes[0])
303
+ expect(withRunOverrides(nodes, undefined)).toEqual(nodes)
304
+ })
305
+ })
@@ -0,0 +1,176 @@
1
+ import { describe, it, expect } from "vitest"
2
+ // Through the package index: both engines stamp a render with these, and the
3
+ // review inspector compares a take's stamps with them.
4
+ import {
5
+ editPlanBasis,
6
+ renderClipKey,
7
+ renderPlanBasis,
8
+ renderPlanValue,
9
+ renderReadBasis,
10
+ renderResultStamp,
11
+ renderSettingsBasis,
12
+ } from "../index.js"
13
+
14
+ const HEX = /^[0-9a-f]{16}$/
15
+
16
+ const clip = (inMs: number, outMs: number, meta?: Record<string, unknown>) => ({
17
+ version: 1,
18
+ clock: "master",
19
+ sources: [{ id: "A", url: "https://media.test/a.mp4", kind: "video" }],
20
+ segments: [{ id: `s${inMs}`, inMs, outMs, video: "A" }],
21
+ ...(meta ? { meta } : {}),
22
+ })
23
+
24
+ describe("renderResultStamp — the two bases a render carries", () => {
25
+ it("keeps a plan basis and a render basis of 16 lowercase hex digits", () => {
26
+ expect(renderResultStamp({ quality: "final", planBasis: "0123456789abcdef", renderBasis: "fedcba9876543210" })).toEqual({
27
+ quality: "final",
28
+ planBasis: "0123456789abcdef",
29
+ renderBasis: "fedcba9876543210",
30
+ })
31
+ })
32
+
33
+ it("drops a basis that is not 16 lowercase hex digits", () => {
34
+ for (const bad of ["", "0123456789ABCDEF", "0123456789abcde", "0123456789abcdef0", "g123456789abcdef", 12, null]) {
35
+ expect(renderResultStamp({ planBasis: bad, renderBasis: bad })).toEqual({})
36
+ }
37
+ })
38
+ })
39
+
40
+ describe("renderReadBasis — the plan value a render read, without its meta (R2 a)", () => {
41
+ it("is the plan basis of the value with its top-level meta removed", () => {
42
+ const value = clip(0, 1000, { title: "Why remote teams fail", hook: "Nobody tells you" })
43
+ const { meta: _meta, ...rest } = value
44
+ expect(renderReadBasis(value)).toBe(editPlanBasis(rest))
45
+ expect(renderReadBasis(value)).toMatch(HEX)
46
+ })
47
+
48
+ it("ignores an edited hook, and nothing else", () => {
49
+ expect(renderReadBasis(clip(0, 1000, { hook: "a" }))).toBe(renderReadBasis(clip(0, 1000, { hook: "b" })))
50
+ expect(renderReadBasis(clip(0, 1000, { hook: "a" }))).toBe(renderReadBasis(clip(0, 1000)))
51
+ expect(renderReadBasis(clip(0, 1000))).not.toBe(renderReadBasis(clip(0, 1001)))
52
+ })
53
+
54
+ it("reads a clip given as JSON text exactly as the object, whatever its key order", () => {
55
+ const value = clip(2000, 3000, { hook: "x" })
56
+ expect(renderReadBasis(JSON.stringify(value))).toBe(renderReadBasis(value))
57
+ const reordered = JSON.parse(JSON.stringify(Object.fromEntries(Object.entries(value).reverse())))
58
+ expect(renderReadBasis(reordered)).toBe(renderReadBasis(value))
59
+ })
60
+
61
+ it("names nothing for a value that is not one plan object", () => {
62
+ expect(renderReadBasis(undefined)).toBeUndefined()
63
+ expect(renderReadBasis("")).toBeUndefined()
64
+ expect(renderReadBasis("not json")).toBeUndefined()
65
+ expect(renderReadBasis([clip(0, 1000)])).toBeUndefined()
66
+ expect(renderReadBasis(42)).toBeUndefined()
67
+ })
68
+
69
+ // Stored takes carry this value: the algorithm must never move under them.
70
+ it("is pinned", () => {
71
+ expect(renderReadBasis(clip(0, 1000, { hook: "pinned" }))).toBe("4d88472ee5ee3526")
72
+ })
73
+ })
74
+
75
+ describe("renderSettingsBasis — the render's own settings (R19 a)", () => {
76
+ const sources = ["https://media.test/a.mp4"]
77
+
78
+ it("changes with the crossfade, the output and the effective sources", () => {
79
+ const base = renderSettingsBasis({ output: "video", crossfadeMs: 0 }, sources)
80
+ expect(base).toMatch(HEX)
81
+ expect(renderSettingsBasis({ output: "video", crossfadeMs: 120 }, sources)).not.toBe(base)
82
+ expect(renderSettingsBasis({ output: "audio", crossfadeMs: 0 }, sources)).not.toBe(base)
83
+ expect(renderSettingsBasis({ output: "video", crossfadeMs: 0 }, ["https://media.test/b.mp4"])).not.toBe(base)
84
+ })
85
+
86
+ it("reads the settings as the render does: any output but audio is video, a missing crossfade is a hard cut, ms are whole", () => {
87
+ const base = renderSettingsBasis({ output: "video", crossfadeMs: 0 }, sources)
88
+ expect(renderSettingsBasis({}, sources)).toBe(base)
89
+ expect(renderSettingsBasis({ output: "gif", crossfadeMs: undefined }, sources)).toBe(base)
90
+ expect(renderSettingsBasis({ output: "video", crossfadeMs: -5 }, sources)).toBe(base)
91
+ expect(renderSettingsBasis({ output: "video", crossfadeMs: 120.4 }, sources)).toBe(
92
+ renderSettingsBasis({ output: "video", crossfadeMs: 120 }, sources),
93
+ )
94
+ })
95
+
96
+ it("is pinned", () => {
97
+ expect(renderSettingsBasis({ output: "audio", crossfadeMs: 250 }, sources)).toBe("36f72984453dd8df")
98
+ })
99
+ })
100
+
101
+ describe("renderPlanValue — the plan value a render iteration read", () => {
102
+ const PLAN = [clip(0, 1000), clip(2000, 3000), clip(4000, 5000)].map((c) => JSON.stringify(c))
103
+ const each = (data: Record<string, unknown> = {}) => ({
104
+ edge: { source: "plan", target: "render", targetHandle: "edl", data: { outputMode: "each", ...data } },
105
+ each: true,
106
+ source: "edit-plan",
107
+ })
108
+
109
+ it("is the clip the row reads, picked by the wire's selector — the clip renderClipKey names", () => {
110
+ const hops = [each({ selectorMode: "list", listExpression: "2,3" })]
111
+ expect(renderPlanValue(PLAN, 0, hops)).toBe(PLAN[1])
112
+ expect(renderPlanValue(PLAN, 1, hops)).toBe(PLAN[2])
113
+ expect(renderClipKey(PLAN, 1, hops)).toBe("4000-5000")
114
+ })
115
+
116
+ it("is a Tighten plan itself, the one EDL every wire hands on", () => {
117
+ const tighten = clip(0, 9000)
118
+ expect(renderPlanValue(tighten, undefined, [each()])).toBe(tighten)
119
+ expect(renderClipKey(tighten, undefined, [each()])).toBeUndefined()
120
+ })
121
+
122
+ it("names nothing for a dropped clip's empty row", () => {
123
+ expect(renderPlanValue(["", PLAN[1]], 0, [each()])).toBeUndefined()
124
+ })
125
+ })
126
+
127
+ describe("renderPlanBasis — stamped only when every pass-through hop ran with the render (R1 a)", () => {
128
+ const nodes = [
129
+ { id: "plan", type: "edit-plan" },
130
+ { id: "tp-send", type: "teleport-send" },
131
+ { id: "tp-recv", type: "teleport-receive" },
132
+ { id: "switch", type: "camera-switch" },
133
+ { id: "render", type: "apply-edl" },
134
+ ]
135
+ const tighten = clip(0, 9000, { title: "Episode 12" })
136
+ const PLAN = [clip(0, 1000), clip(2000, 3000)].map((c) => JSON.stringify(c))
137
+ const direct = [{ source: "plan", sourceHandle: "edl", target: "render", targetHandle: "edl" }]
138
+ const viaSwitch = [
139
+ { source: "plan", sourceHandle: "edl", target: "switch", targetHandle: "edl" },
140
+ { source: "switch", sourceHandle: "edl", target: "render", targetHandle: "edl" },
141
+ ]
142
+ const viaTeleportAndSwitch = [
143
+ { source: "plan", sourceHandle: "edl", target: "tp-send", targetHandle: "in" },
144
+ { source: "tp-send", target: "tp-recv" },
145
+ { source: "tp-recv", target: "switch", targetHandle: "edl" },
146
+ { source: "switch", sourceHandle: "edl", target: "render", targetHandle: "edl" },
147
+ ]
148
+ const none = new Set<string>()
149
+
150
+ it("a render wired straight to the plan is always stamped, with the value it read", () => {
151
+ expect(renderPlanBasis("render", nodes, direct, () => tighten, undefined, none)).toBe(renderReadBasis(tighten))
152
+ expect(renderPlanBasis("render", nodes, direct, () => PLAN, 1, none)).toBe(renderReadBasis(PLAN[1]))
153
+ })
154
+
155
+ it("behind Camera Switch, only when the switch ran in the render's run", () => {
156
+ expect(renderPlanBasis("render", nodes, viaSwitch, () => tighten, undefined, none)).toBeUndefined()
157
+ expect(renderPlanBasis("render", nodes, viaSwitch, () => tighten, undefined, new Set(["render"]))).toBeUndefined()
158
+ expect(renderPlanBasis("render", nodes, viaSwitch, () => tighten, undefined, new Set(["switch", "render"]))).toBe(
159
+ renderReadBasis(tighten),
160
+ )
161
+ expect(renderPlanBasis("render", nodes, viaSwitch, () => PLAN, 0, new Set(["switch"]))).toBe(renderReadBasis(PLAN[0]))
162
+ })
163
+
164
+ it("a teleport is not a hop that runs: the switch behind it decides", () => {
165
+ expect(renderPlanBasis("render", nodes, viaTeleportAndSwitch, () => tighten, undefined, new Set(["switch"]))).toBe(
166
+ renderReadBasis(tighten),
167
+ )
168
+ expect(renderPlanBasis("render", nodes, viaTeleportAndSwitch, () => tighten, undefined, none)).toBeUndefined()
169
+ })
170
+
171
+ it("names nothing with no plan behind the render, or no value the iteration read", () => {
172
+ expect(renderPlanBasis("render", nodes, [], () => tighten, undefined, none)).toBeUndefined()
173
+ expect(renderPlanBasis("render", nodes, direct, () => undefined, undefined, none)).toBeUndefined()
174
+ expect(renderPlanBasis("render", nodes, direct, () => ["", PLAN[1]], 0, none)).toBeUndefined()
175
+ })
176
+ })