@morshoto/framekit 0.1.14 → 0.1.17

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 (36) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
  4. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
  6. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  8. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  9. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  10. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  12. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  14. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
  15. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  16. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  17. package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
  18. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  19. package/dist-package/apps/mcp-server/src/main.js +28 -4
  20. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  21. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  23. package/dist-package/apps/mcp-server/src/server.js +311 -34
  24. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  25. package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
  26. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  27. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  28. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  29. package/dist-package/packages/runtime/src/index.js +7 -0
  30. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  31. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  32. package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
  33. package/dist-package/packages/runtime/src/runtime.js +5 -2
  34. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  35. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  36. package/package.json +2 -1
@@ -0,0 +1,181 @@
1
+ import { createHash } from "node:crypto";
2
+ import { execFile } from "node:child_process";
3
+ import { createReadStream } from "node:fs";
4
+ import { lstat, stat } from "node:fs/promises";
5
+ import { resolve } from "node:path";
6
+ import { promisify } from "node:util";
7
+ const execFileAsync = promisify(execFile);
8
+ /** Independently verifies the committed output; it does not trust provider metadata. */
9
+ export class FfmpegRenderVerifier {
10
+ ffprobePath;
11
+ durationToleranceSeconds;
12
+ environment;
13
+ constructor(options = {}) {
14
+ this.ffprobePath = options.ffprobePath ?? process.env.FFPROBE_BIN ?? "ffprobe";
15
+ this.durationToleranceSeconds = options.durationToleranceSeconds;
16
+ this.environment = { ...process.env, ...options.env };
17
+ }
18
+ async verify(plan, result) {
19
+ const outputPath = resolve(result.output.path);
20
+ const checks = [];
21
+ let details;
22
+ try {
23
+ details = await lstat(outputPath);
24
+ }
25
+ catch {
26
+ return failed([], `render output does not exist: ${outputPath}`, "RENDER_OUTPUT_MISSING");
27
+ }
28
+ if (!details.isFile() || details.isSymbolicLink()) {
29
+ return failed(checks, "render output is not a regular file", "RENDER_OUTPUT_INVALID");
30
+ }
31
+ const fileStats = await stat(outputPath);
32
+ const fileDigest = await digestFile(outputPath);
33
+ const fileIdentity = { device: fileStats.dev, inode: fileStats.ino, size: fileStats.size };
34
+ checks.push({ name: "output-exists", passed: true, detail: "render output is a regular file", observed: { path: outputPath } });
35
+ checks.push({ name: "output-digest", passed: /^[a-f0-9]{64}$/.test(fileDigest), detail: "render output has a SHA-256 digest", observed: fileDigest });
36
+ let probe;
37
+ try {
38
+ probe = await this.probe(outputPath);
39
+ }
40
+ catch (error) {
41
+ if (error.code === "ENOENT" || (error instanceof Error && /spawn ffprobe ENOENT/.test(error.message))) {
42
+ return unavailable("ffprobe is not configured", "RENDER_VERIFIER_UNAVAILABLE");
43
+ }
44
+ return failed(checks, error instanceof Error ? error.message : String(error), "RENDER_OUTPUT_UNPLAYABLE");
45
+ }
46
+ let finalDetails;
47
+ try {
48
+ finalDetails = await lstat(outputPath);
49
+ }
50
+ catch {
51
+ return failed(checks, `render output changed during verification: ${outputPath}`, "RENDER_OUTPUT_CHANGED");
52
+ }
53
+ if (!finalDetails.isFile() || finalDetails.isSymbolicLink()) {
54
+ return failed(checks, "render output changed into a non-regular file during verification", "RENDER_OUTPUT_CHANGED");
55
+ }
56
+ const finalDigest = await digestFile(outputPath);
57
+ if (finalDetails.dev !== fileIdentity.device || finalDetails.ino !== fileIdentity.inode || finalDetails.size !== fileIdentity.size || finalDigest !== fileDigest) {
58
+ return failed(checks, "render output bytes or file identity changed during verification", "RENDER_OUTPUT_CHANGED");
59
+ }
60
+ checks.push({ name: "output-stability", passed: true, detail: "the verified metadata and digest refer to one unchanged output file" });
61
+ const video = probe.streams.find((stream) => stream.codec_type === "video");
62
+ if (!video || video.width === undefined || video.height === undefined || !video.r_frame_rate) {
63
+ return failed(checks, "render output has no complete video stream", "RENDER_OUTPUT_UNPLAYABLE");
64
+ }
65
+ const expectedFrameRate = parseRational(plan.parameters.frameRate);
66
+ const expectedAudio = expectedAudioStream(plan);
67
+ const audio = probe.streams.find((stream) => stream.codec_type === "audio");
68
+ const observedFrameRate = parseFfmpegRate(video.r_frame_rate);
69
+ const expectedDuration = rationalSeconds(plan.timeline.sequence.durationTime);
70
+ const tolerance = this.durationToleranceSeconds ?? Math.max(0.05, rationalSeconds(plan.timeline.sequence.frameDuration) * 1.5);
71
+ const durationPassed = Number.isFinite(probe.format.duration)
72
+ && Math.abs(probe.format.duration - expectedDuration) <= tolerance;
73
+ const frameRatePassed = observedFrameRate !== undefined && sameRational(observedFrameRate, expectedFrameRate);
74
+ const formatPassed = probe.format.format_name.split(",").some((format) => format === plan.parameters.format);
75
+ checks.push({ name: "playable", passed: true, detail: "ffprobe read the output streams and duration" });
76
+ checks.push({ name: "format", passed: formatPassed, detail: "output container matches the explicit request", expected: plan.parameters.format, observed: probe.format.format_name });
77
+ checks.push({ name: "dimensions", passed: video.width === plan.parameters.width && video.height === plan.parameters.height, detail: "output dimensions match the explicit request", expected: { width: plan.parameters.width, height: plan.parameters.height }, observed: { width: video.width, height: video.height } });
78
+ checks.push({ name: "frame-rate", passed: frameRatePassed, detail: "output rational frame rate matches the explicit request", expected: expectedFrameRate, observed: observedFrameRate });
79
+ const audioPassed = expectedAudio === undefined || (audio !== undefined
80
+ && (expectedAudio.sampleRate === undefined || Number(audio.sample_rate) === expectedAudio.sampleRate)
81
+ && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels));
82
+ checks.push({ name: "audio-stream", passed: audioPassed, detail: "canonical audio stream presence and metadata are preserved", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
83
+ checks.push({ name: "duration", passed: durationPassed, detail: `output duration is within ${tolerance} seconds of the canonical sequence`, expected: expectedDuration, observed: probe.format.duration });
84
+ const artifact = {
85
+ path: result.output.path,
86
+ format: probe.format.format_name,
87
+ sizeBytes: fileStats.size,
88
+ fileDigest,
89
+ durationSeconds: probe.format.duration,
90
+ width: video.width,
91
+ height: video.height,
92
+ frameRate: observedFrameRate ?? expectedFrameRate,
93
+ streams: probe.streams.map(toArtifactStream),
94
+ };
95
+ const passed = checks.every((check) => check.passed);
96
+ return { status: passed ? "passed" : "failed", checks, artifact };
97
+ }
98
+ async probe(path) {
99
+ const result = await execFileAsync(this.ffprobePath, [
100
+ "-v", "error",
101
+ "-show_entries", "stream=codec_type,codec_name,width,height,r_frame_rate,sample_rate,channels",
102
+ "-show_entries", "format=format_name,duration",
103
+ "-of", "json",
104
+ path,
105
+ ], { env: this.environment, maxBuffer: 2 * 1024 * 1024 });
106
+ const parsed = JSON.parse(result.stdout);
107
+ if (!Array.isArray(parsed.streams) || !parsed.format || typeof parsed.format.duration !== "string" || !Number.isFinite(Number(parsed.format.duration))) {
108
+ throw new Error("ffprobe returned incomplete output metadata");
109
+ }
110
+ return {
111
+ streams: parsed.streams,
112
+ format: { format_name: String(parsed.format.format_name ?? ""), duration: Number(parsed.format.duration) },
113
+ };
114
+ }
115
+ }
116
+ function expectedAudioStream(plan) {
117
+ const resources = new Map(plan.timeline.resources.map((resource) => [resource.id, resource]));
118
+ for (const occurrence of plan.timeline.sequence.occurrences) {
119
+ const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
120
+ const stream = resource?.metadata?.streams.find((candidate) => candidate.kind === "audio");
121
+ if (stream)
122
+ return { sampleRate: stream.sampleRate, channels: stream.channels };
123
+ }
124
+ return undefined;
125
+ }
126
+ function toArtifactStream(stream) {
127
+ return {
128
+ kind: stream.codec_type,
129
+ ...(stream.codec_name ? { codec: stream.codec_name } : {}),
130
+ ...(stream.width !== undefined ? { width: stream.width } : {}),
131
+ ...(stream.height !== undefined ? { height: stream.height } : {}),
132
+ ...(stream.r_frame_rate ? { frameRate: parseFfmpegRate(stream.r_frame_rate) } : {}),
133
+ ...(stream.sample_rate ? { sampleRate: Number(stream.sample_rate) } : {}),
134
+ ...(stream.channels !== undefined ? { channels: stream.channels } : {}),
135
+ };
136
+ }
137
+ function parseFfmpegRate(value) {
138
+ if (!value || !/^\d+\/\d+$/.test(value))
139
+ return undefined;
140
+ const [numerator, denominator] = value.split("/").map(BigInt);
141
+ if (denominator <= 0n)
142
+ return undefined;
143
+ const divisor = gcd(numerator, denominator);
144
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
145
+ }
146
+ function parseRational(value) {
147
+ const numerator = BigInt(value.value);
148
+ const denominator = BigInt(value.timescale);
149
+ const divisor = gcd(numerator < 0n ? -numerator : numerator, denominator);
150
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
151
+ }
152
+ function sameRational(left, right) {
153
+ return left.value === right.value && left.timescale === right.timescale;
154
+ }
155
+ function rationalSeconds(value) {
156
+ return Number(BigInt(value.value)) / Number(BigInt(value.timescale));
157
+ }
158
+ function gcd(left, right) {
159
+ while (right !== 0n) {
160
+ const remainder = left % right;
161
+ left = right;
162
+ right = remainder;
163
+ }
164
+ return left || 1n;
165
+ }
166
+ async function digestFile(path) {
167
+ const digest = createHash("sha256");
168
+ await new Promise((resolvePromise, reject) => {
169
+ const stream = createReadStream(path);
170
+ stream.on("data", (chunk) => digest.update(chunk));
171
+ stream.once("error", reject);
172
+ stream.once("end", resolvePromise);
173
+ });
174
+ return digest.digest("hex");
175
+ }
176
+ function failed(checks, message, code) {
177
+ return { status: "failed", checks: [...checks, { name: code.toLowerCase(), passed: false, detail: message }], error: { code, message } };
178
+ }
179
+ function unavailable(message, code) {
180
+ return { status: "unavailable", checks: [{ name: code.toLowerCase(), passed: false, detail: message }], error: { code, message } };
181
+ }
@@ -0,0 +1,3 @@
1
+ export * from "./ffmpeg-renderer.js";
2
+ export * from "./ffmpeg-verifier.js";
3
+ export * from "./ffmpeg-media-probe.js";
@@ -0,0 +1,370 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { readdir, readFile, rename, writeFile, mkdir } from "node:fs/promises";
3
+ import { dirname, join } from "node:path";
4
+ import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, } from "../../../packages/runtime/src/index.js";
5
+ import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ export class HeadlessProjectService {
7
+ directory;
8
+ mediaProbe;
9
+ renderer;
10
+ verifier;
11
+ clock;
12
+ constructor(options) {
13
+ this.directory = options.directory;
14
+ this.mediaProbe = options.mediaProbe;
15
+ this.renderer = options.renderer;
16
+ this.verifier = options.verifier;
17
+ this.clock = options.clock ?? (() => new Date().toISOString());
18
+ }
19
+ async create(timeline) {
20
+ const store = this.store(timeline.project.id);
21
+ const timestamp = this.clock();
22
+ return store.create({
23
+ schemaVersion: 1,
24
+ metadata: { createdAt: timestamp, updatedAt: timestamp },
25
+ timeline,
26
+ });
27
+ }
28
+ async list() {
29
+ await mkdir(this.directory, { recursive: true });
30
+ const entries = await readdir(this.directory, { withFileTypes: true });
31
+ const summaries = [];
32
+ for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith(".json") && !candidate.name.startsWith("render-"))) {
33
+ const projectId = entry.name.slice(0, -".json".length);
34
+ const project = await this.store(projectId).load();
35
+ summaries.push(toSummary(project, this.projectPath(projectId)));
36
+ }
37
+ return summaries.sort((left, right) => left.projectId.localeCompare(right.projectId));
38
+ }
39
+ async open(projectId) {
40
+ const project = await this.store(projectId).load();
41
+ const hasLocalMedia = project.timeline.resources.some((resource) => resource.sourceKind === "local-file");
42
+ if (hasLocalMedia && !this.mediaProbe) {
43
+ throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: local-file resources require a configured media probe");
44
+ }
45
+ if (this.mediaProbe)
46
+ await new LocalMediaRegistrar(this.store(projectId), this.mediaProbe).reopen();
47
+ return project;
48
+ }
49
+ async inspect(projectId) {
50
+ return this.open(projectId);
51
+ }
52
+ async registerMedia(projectId, sourcePath, expectedRevision) {
53
+ if (!this.mediaProbe)
54
+ throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: no local media metadata probe is configured");
55
+ return new LocalMediaRegistrar(this.store(projectId), this.mediaProbe, { clock: this.clock }).register(sourcePath, expectedRevision);
56
+ }
57
+ async previewEdit(projectId, command, sequenceId) {
58
+ await this.open(projectId);
59
+ const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
60
+ return transaction.preview({
61
+ ...command,
62
+ target: command.target ?? { projectId, sequenceId },
63
+ });
64
+ }
65
+ async executeEdit(projectId, command, sequenceId) {
66
+ await this.open(projectId);
67
+ const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
68
+ return transaction.execute({
69
+ ...command,
70
+ target: command.target ?? { projectId, sequenceId },
71
+ });
72
+ }
73
+ async previewRoughCut(request) {
74
+ const prepared = await this.prepareRoughCut(request);
75
+ const transaction = new ProjectTransactionService(this.store(request.projectId), { clock: this.clock });
76
+ const preview = await transaction.preview(prepared.command);
77
+ const fcpxml = compileTimelineIrToFcpxml(preview.after.timeline, { target: request.fcpxml.target });
78
+ return {
79
+ ...preview,
80
+ plan: structuredClone(request.plan),
81
+ planDigest: prepared.planDigest,
82
+ provenance: prepared.provenance,
83
+ outputIntent: prepared.outputIntent,
84
+ fcpxml: selectFcpxmlMetadata(fcpxml),
85
+ };
86
+ }
87
+ async executeRoughCut(request) {
88
+ if (request.approved !== true) {
89
+ throw new Error("HEADLESS_ROUGH_CUT_APPROVAL_REQUIRED: set approved=true after reviewing the preview");
90
+ }
91
+ const prepared = await this.prepareRoughCut(request);
92
+ if (request.planDigest !== prepared.planDigest) {
93
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: planDigest does not match the submitted rough-cut plan");
94
+ }
95
+ const transaction = new ProjectTransactionService(this.store(request.projectId), { clock: this.clock });
96
+ const preview = await transaction.preview(prepared.command);
97
+ const fcpxml = compileTimelineIrToFcpxml(preview.after.timeline, { target: request.fcpxml.target });
98
+ const renderRequest = createFramekitRenderRequest({
99
+ timeline: preview.after.timeline,
100
+ target: { projectId: request.projectId, sequenceId: request.sequenceId },
101
+ revision: preview.after.timeline.revision,
102
+ parameters: request.render,
103
+ });
104
+ if (!this.renderer || !this.verifier) {
105
+ throw new Error("HEADLESS_ROUGH_CUT_RENDER_UNAVAILABLE: renderer and verifier are not configured");
106
+ }
107
+ const outcome = await renderAndVerifyFramekitProject(renderRequest, this.renderer, this.verifier);
108
+ const renderId = `render-${randomUUID()}`;
109
+ const renderRecord = {
110
+ renderId,
111
+ projectId: request.projectId,
112
+ sequenceId: request.sequenceId,
113
+ requestedRevision: renderRequest.projectRevision,
114
+ createdAt: this.clock(),
115
+ status: outcome.status,
116
+ outcome,
117
+ };
118
+ await this.saveRender(renderRecord);
119
+ if (outcome.status !== "passed") {
120
+ throw new Error(`HEADLESS_ROUGH_CUT_RENDER_FAILED: render verification status was ${outcome.status}; inspect ${renderId}`);
121
+ }
122
+ const fcpxmlArtifact = await writeVerifiedFcpxml(request.fcpxml.path, fcpxml.xml, fcpxml.digest, request.fcpxml.overwrite === true);
123
+ const committed = await transaction.execute(prepared.command);
124
+ return {
125
+ ...preview,
126
+ plan: structuredClone(request.plan),
127
+ planDigest: prepared.planDigest,
128
+ provenance: prepared.provenance,
129
+ outputIntent: prepared.outputIntent,
130
+ fcpxml: selectFcpxmlMetadata(fcpxml),
131
+ committed: true,
132
+ render: { renderId, status: "passed", outcome },
133
+ fcpxmlArtifact,
134
+ transaction: committed,
135
+ };
136
+ }
137
+ async render(projectId, sequenceId, parameters, expectedRevision) {
138
+ if (!this.renderer || !this.verifier)
139
+ throw new Error("HEADLESS_RENDER_UNAVAILABLE: renderer and verifier are not configured");
140
+ const project = await this.open(projectId);
141
+ const request = createFramekitRenderRequest({
142
+ timeline: project.timeline,
143
+ target: { projectId, sequenceId },
144
+ ...(expectedRevision ? { revision: expectedRevision } : {}),
145
+ parameters,
146
+ });
147
+ const outcome = await renderAndVerifyFramekitProject(request, this.renderer, this.verifier);
148
+ const renderId = `render-${randomUUID()}`;
149
+ const record = {
150
+ renderId,
151
+ projectId,
152
+ sequenceId,
153
+ requestedRevision: request.projectRevision,
154
+ createdAt: this.clock(),
155
+ status: outcome.status,
156
+ outcome,
157
+ };
158
+ await this.saveRender(record);
159
+ return record;
160
+ }
161
+ async inspectRender(renderId) {
162
+ validateRenderId(renderId);
163
+ try {
164
+ return JSON.parse(await readFile(join(this.directory, `${renderId}.json`), "utf8"));
165
+ }
166
+ catch (error) {
167
+ if (error.code === "ENOENT")
168
+ throw new Error(`HEADLESS_RENDER_NOT_FOUND: render record does not exist: ${renderId}`);
169
+ throw error;
170
+ }
171
+ }
172
+ store(projectId) {
173
+ return new FramekitProjectStore(this.projectPath(projectId));
174
+ }
175
+ projectPath(projectId) {
176
+ validateProjectId(projectId);
177
+ return join(this.directory, `${projectId}.json`);
178
+ }
179
+ async saveRender(record) {
180
+ await mkdir(this.directory, { recursive: true });
181
+ const path = join(this.directory, `${record.renderId}.json`);
182
+ const temporary = `${path}.${randomUUID()}.tmp`;
183
+ await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "wx" });
184
+ await rename(temporary, path);
185
+ }
186
+ async prepareRoughCut(request) {
187
+ await this.open(request.projectId);
188
+ const project = await this.store(request.projectId).load();
189
+ if (project.timeline.sequence.id !== request.sequenceId) {
190
+ throw new Error("HEADLESS_ROUGH_CUT_TARGET_MISMATCH: sequenceId does not match the persisted project");
191
+ }
192
+ if (!sameRevision(project.timeline.revision, request.plan.revision)) {
193
+ throw new Error("HEADLESS_ROUGH_CUT_STALE_REVISION: rough-cut plan revision does not match the persisted project");
194
+ }
195
+ if (!request.plan.shots.length)
196
+ throw new Error("HEADLESS_ROUGH_CUT_EMPTY_PLAN: rough-cut plan must contain at least one shot");
197
+ const operations = structuredClone(request.operations ?? []);
198
+ const sourceAudioPolicy = request.sourceAudioPolicy ?? "preserve-and-mix";
199
+ const outputIntent = {
200
+ sourceAudioPolicy,
201
+ render: structuredClone(request.render),
202
+ fcpxml: {
203
+ path: request.fcpxml.path,
204
+ target: structuredClone(request.fcpxml.target),
205
+ overwrite: request.fcpxml.overwrite === true,
206
+ },
207
+ };
208
+ const planDigest = digestRoughCutPlan(request.plan, operations, outputIntent);
209
+ const existingOccurrenceIds = new Set(project.timeline.sequence.occurrences.map(({ id }) => id));
210
+ const resourceByMediaId = new Map(project.timeline.resources.map((resource) => [resource.id, resource]));
211
+ const provenance = [];
212
+ const planOperations = [];
213
+ for (const shot of request.plan.shots) {
214
+ const shotWithEvidence = shot;
215
+ const occurrenceId = `rough-cut-${shot.order}`;
216
+ if (existingOccurrenceIds.has(occurrenceId)) {
217
+ throw new Error(`HEADLESS_ROUGH_CUT_OCCURRENCE_COLLISION: ${occurrenceId} already exists`);
218
+ }
219
+ existingOccurrenceIds.add(occurrenceId);
220
+ const resource = resourceByMediaId.get(shot.sourceIdentity.mediaId);
221
+ if (!resource)
222
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_NOT_FOUND: ${shot.sourceIdentity.mediaId}`);
223
+ assertSourceIdentity(resource, shot.sourceIdentity);
224
+ const sourceStartTime = shot.range.startTime ?? secondsToRational(shot.range.start);
225
+ const durationTime = shot.range.durationTime ?? secondsToRational(shot.range.end - shot.range.start);
226
+ assertSourceRange(resource, shot.range, sourceStartTime, durationTime);
227
+ planOperations.push({
228
+ type: "insert-occurrence",
229
+ placement: "append",
230
+ occurrence: {
231
+ id: occurrenceId,
232
+ name: `Rough cut ${shot.order}: ${shot.rationale}`,
233
+ startTime: { value: "0", timescale: "1" },
234
+ durationTime,
235
+ sourceStartTime,
236
+ track: 0,
237
+ role: "video",
238
+ mediaId: resource.id,
239
+ binding: { provider: "framekit.rough-cut", kind: "occurrence", identity: `${planDigest}:${shot.order}` },
240
+ },
241
+ });
242
+ provenance.push({
243
+ order: shot.order,
244
+ occurrenceId,
245
+ mediaId: resource.id,
246
+ sourceIdentity: structuredClone(shot.sourceIdentity),
247
+ sourceRange: structuredClone(shot.range),
248
+ confidence: shot.confidence,
249
+ matchedProperties: [...shot.matchedProperties],
250
+ rationale: shot.rationale,
251
+ ...(shotWithEvidence.evidence ? { evidence: structuredClone(shotWithEvidence.evidence) } : {}),
252
+ });
253
+ }
254
+ const editOperations = [...planOperations, ...operations];
255
+ const command = {
256
+ schemaVersion: 1,
257
+ target: { projectId: request.projectId, sequenceId: request.sequenceId },
258
+ expectedRevision: structuredClone(request.plan.revision),
259
+ operations: editOperations,
260
+ };
261
+ return { command, planDigest, provenance, outputIntent };
262
+ }
263
+ }
264
+ function digestRoughCutPlan(plan, operations, outputIntent) {
265
+ return createHash("sha256").update(stableJson({ plan, operations, outputIntent })).digest("hex");
266
+ }
267
+ function stableJson(value) {
268
+ if (value === null || typeof value !== "object")
269
+ return JSON.stringify(value);
270
+ if (Array.isArray(value))
271
+ return `[${value.map(stableJson).join(",")}]`;
272
+ return `{${Object.entries(value).filter(([, child]) => child !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
273
+ }
274
+ function assertSourceIdentity(resource, source) {
275
+ if (resource.source !== source.source)
276
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source path differs for ${source.mediaId}`);
277
+ if (source.sourceDigest !== undefined && resource.sourceDigest !== source.sourceDigest) {
278
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source digest differs for ${source.mediaId}`);
279
+ }
280
+ if (source.mediaKind !== undefined && resource.mediaKind !== source.mediaKind) {
281
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: media kind differs for ${source.mediaId}`);
282
+ }
283
+ if (resource.mediaKind !== "video")
284
+ throw new Error(`HEADLESS_ROUGH_CUT_VIDEO_REQUIRED: ${source.mediaId}`);
285
+ if (source.duration !== undefined && resource.metadata?.durationTime !== undefined
286
+ && Math.abs(source.duration - rationalSeconds(resource.metadata.durationTime)) > 0.01) {
287
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source duration differs for ${source.mediaId}`);
288
+ }
289
+ }
290
+ function assertSourceRange(resource, range, sourceStartTime, durationTime) {
291
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.start < 0 || range.end <= range.start) {
292
+ throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: source range must be finite and non-empty");
293
+ }
294
+ if (resource.metadata?.durationTime !== undefined && range.end > rationalSeconds(resource.metadata.durationTime) + 0.001) {
295
+ throw new Error(`HEADLESS_ROUGH_CUT_RANGE_INVALID: source range exceeds ${resource.id}`);
296
+ }
297
+ if (rationalSeconds(sourceStartTime) < 0 || rationalSeconds(durationTime) <= 0
298
+ || Math.abs(rationalSeconds(sourceStartTime) - range.start) > 0.001
299
+ || Math.abs(rationalSeconds(durationTime) - (range.end - range.start)) > 0.001) {
300
+ throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: rational source range must be non-negative and non-empty");
301
+ }
302
+ }
303
+ function secondsToRational(seconds) {
304
+ const timescale = 1_000_000;
305
+ const value = Math.round(seconds * timescale);
306
+ const divisor = greatestCommonDivisor(Math.abs(value), timescale);
307
+ return { value: String(value / divisor), timescale: String(timescale / divisor) };
308
+ }
309
+ function rationalSeconds(time) {
310
+ return Number(time.value) / Number(time.timescale);
311
+ }
312
+ function greatestCommonDivisor(left, right) {
313
+ while (right !== 0) {
314
+ const remainder = left % right;
315
+ left = right;
316
+ right = remainder;
317
+ }
318
+ return left || 1;
319
+ }
320
+ function sameRevision(left, right) {
321
+ return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
322
+ }
323
+ function selectFcpxmlMetadata(result) {
324
+ return {
325
+ digest: result.digest,
326
+ target: structuredClone(result.target),
327
+ destination: structuredClone(result.destination),
328
+ coverage: structuredClone(result.coverage),
329
+ provenance: structuredClone(result.provenance),
330
+ };
331
+ }
332
+ async function writeVerifiedFcpxml(path, xml, digest, overwrite) {
333
+ await mkdir(dirname(path), { recursive: true });
334
+ if (!overwrite) {
335
+ try {
336
+ await readFile(path);
337
+ throw new Error(`HEADLESS_ROUGH_CUT_FCPXML_EXISTS: refusing to overwrite ${path}`);
338
+ }
339
+ catch (error) {
340
+ if (error.code !== "ENOENT")
341
+ throw error;
342
+ }
343
+ }
344
+ const temporary = `${path}.${randomUUID()}.tmp`;
345
+ await writeFile(temporary, xml, { encoding: "utf8", flag: "wx" });
346
+ await rename(temporary, path);
347
+ const persisted = await readFile(path, "utf8");
348
+ const persistedDigest = createHash("sha256").update(persisted).digest("hex");
349
+ if (persistedDigest !== digest)
350
+ throw new Error("HEADLESS_ROUGH_CUT_FCPXML_VERIFY_FAILED: persisted XML digest differs from the compiled artifact");
351
+ return { path, digest, bytes: Buffer.byteLength(persisted), verified: true };
352
+ }
353
+ function toSummary(project, path) {
354
+ return {
355
+ projectId: project.timeline.project.id,
356
+ projectName: project.timeline.project.name,
357
+ sequenceId: project.timeline.sequence.id,
358
+ sequenceName: project.timeline.sequence.name,
359
+ revision: project.timeline.revision,
360
+ path,
361
+ };
362
+ }
363
+ function validateProjectId(projectId) {
364
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(projectId))
365
+ throw new Error("HEADLESS_PROJECT_INVALID: projectId must be a safe logical identifier");
366
+ }
367
+ function validateRenderId(renderId) {
368
+ if (!/^render-[0-9a-f-]{36}$/.test(renderId))
369
+ throw new Error("HEADLESS_RENDER_INVALID: renderId is invalid");
370
+ }
@@ -99,6 +99,9 @@ export class EditingSessionRepository {
99
99
  await this.refreshLoaded(sessionId, session);
100
100
  return session;
101
101
  }
102
+ hasChangeSource() {
103
+ return this.changeSource !== undefined;
104
+ }
102
105
  checkpoint(sessionId, session) {
103
106
  return this.save(sessionId, session);
104
107
  }
@@ -4,9 +4,11 @@ import { join } from "node:path";
4
4
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
5
5
  import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, FinalCutSqliteInspectionProvider, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
6
6
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
7
- import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
7
+ import { AgentVideoRuntime, JsonSemanticMediaIndexStore } from "../../../packages/runtime/src/index.js";
8
8
  import { createMcpServer } from "./server.js";
9
9
  import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
10
+ import { HeadlessProjectService } from "./headless-projects.js";
11
+ import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
10
12
  const fixture = new InMemoryEditorAdapter({
11
13
  projectId: "project-1",
12
14
  projectName: "Phase 2 Fixture",
@@ -90,6 +92,9 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
90
92
  nativeOperationLease,
91
93
  })
92
94
  : nativeEditor;
95
+ const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
96
+ ? createFinalCutNativeTargetResolver(nativeEditor)
97
+ : undefined;
93
98
  const canonicalNativeProvider = canonicalNativeProviderEnabled
94
99
  ? new FinalCutCanonicalNativeProvider({
95
100
  live: liveAdapter,
@@ -131,7 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
131
136
  target: { projectId, projectUid: projectId, sequenceId },
132
137
  }).readSnapshot();
133
138
  },
134
- resolveTarget: createFinalCutNativeTargetResolver(nativeEditor),
139
+ resolveTarget: canonicalNativeTargetResolver,
135
140
  backgroundCatalog: backgroundLibraryProvider,
136
141
  })
137
142
  : undefined;
@@ -159,6 +164,7 @@ const editor = liveMode
159
164
  : {}),
160
165
  })
161
166
  : fixture;
167
+ const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
162
168
  const analyzers = liveMode
163
169
  ? createCommandAnalyzers({
164
170
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
@@ -175,14 +181,28 @@ const analyzers = liveMode
175
181
  visualAnalyzer: new FixtureVisualAnalyzer(),
176
182
  metadataAnalyzer: new FixtureMetadataAnalyzer(),
177
183
  };
178
- const runtime = new AgentVideoRuntime(editor, analyzers);
179
- const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
184
+ const runtime = new AgentVideoRuntime(editor, {
185
+ ...analyzers,
186
+ semanticMediaIndexStore: new JsonSemanticMediaIndexStore(join(framekitStateDirectory, "semantic-media-index.json")),
187
+ });
188
+ const headlessProjects = new HeadlessProjectService({
189
+ directory: join(framekitStateDirectory, "projects"),
190
+ mediaProbe: new FfmpegMediaMetadataProbe(),
191
+ renderer: new FfmpegTimelineRenderer(),
192
+ verifier: new FfmpegRenderVerifier(),
193
+ });
180
194
  const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
181
195
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
182
196
  ? new DisposableNativeEditWorkflow({
183
197
  native: nativeEditor,
184
198
  readCanonicalSnapshot: () => runtime.inspectProject(),
185
199
  readCanonicalCapabilities: async () => (await runtime.inspectEditor()).capabilities,
200
+ ...(nativeEditor ? {
201
+ prepareTarget: async (target, snapshot) => {
202
+ const occurrenceIndex = snapshot.timeline.clips.findIndex((clip) => clip.id === target.id) + 1;
203
+ await nativeEditor.selectCanonicalOccurrence(target.name, occurrenceIndex);
204
+ },
205
+ } : {}),
186
206
  })
187
207
  : undefined;
188
208
  const nativeOperationSession = disposableNative && nativeEditor
@@ -192,6 +212,9 @@ const projectPublisher = liveMode && fcpxmlPath
192
212
  ? new FinalCutProjectPublisher({
193
213
  enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
194
214
  sourcePath: fcpxmlPath,
215
+ documentDelivery: liveAdapter,
216
+ targetLibraryUid: process.env.FRAMEKIT_FINAL_CUT_LIBRARY_UID,
217
+ allowHeadedFallback: process.env.FRAMEKIT_FINAL_CUT_ALLOW_HEADED_IMPORT === "1",
195
218
  liveState: () => liveAdapter.readLiveState(),
196
219
  })
197
220
  : undefined;
@@ -225,6 +248,7 @@ const server = createMcpServer(runtime, {
225
248
  sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
226
249
  materializationDirectory: join(framekitStateDirectory, "materializations"),
227
250
  sqliteObservationProvider,
251
+ headlessProjects,
228
252
  });
229
253
  const transport = new StdioServerTransport();
230
254
  let shuttingDown = false;