@morshoto/framekit 0.1.16 → 0.1.18

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 (30) hide show
  1. package/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +13 -8
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +147 -34
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +293 -59
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +137 -19
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +473 -3
  20. package/dist-package/apps/mcp-server/src/main.js +33 -6
  21. package/dist-package/apps/mcp-server/src/server.js +367 -52
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +360 -30
  24. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  25. package/dist-package/packages/runtime/src/index.js +1 -0
  26. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  27. package/dist-package/packages/runtime/src/render/render-contract.js +3 -0
  28. package/dist-package/packages/runtime/src/runtime.js +11 -2
  29. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  30. package/package.json +9 -9
@@ -1,7 +1,8 @@
1
- import { randomUUID } from "node:crypto";
1
+ import { createHash, randomUUID } from "node:crypto";
2
2
  import { readdir, readFile, rename, writeFile, mkdir } from "node:fs/promises";
3
- import { join } from "node:path";
4
- import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, } from "../../../packages/runtime/src/index.js";
3
+ import { dirname, join, resolve } from "node:path";
4
+ import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, timelineIrDigest, } from "../../../packages/runtime/src/index.js";
5
+ import { FcpxmlDocumentAdapter, compileTimelineIrToFcpxml, resolveMediaSource, } from "../../../adapters/final-cut/typescript/src/index.js";
5
6
  export class HeadlessProjectService {
6
7
  directory;
7
8
  mediaProbe;
@@ -69,6 +70,239 @@ export class HeadlessProjectService {
69
70
  target: command.target ?? { projectId, sequenceId },
70
71
  });
71
72
  }
73
+ async previewRoughCut(request) {
74
+ const prepared = await this.prepareRoughCut(request);
75
+ const timestamp = this.clock();
76
+ const { preview, fcpxml } = await this.previewPreparedRoughCut(request, prepared, timestamp);
77
+ const approval = createRoughCutApproval({
78
+ inputDigest: prepared.inputDigest,
79
+ projectId: request.projectId,
80
+ sequenceId: request.sequenceId,
81
+ sourceRevision: request.plan.revision,
82
+ canonicalRevision: preview.after.timeline.revision,
83
+ artifactPath: resolve(request.fcpxml.path),
84
+ artifactDigest: fcpxml.digest,
85
+ outputIntent: prepared.outputIntent,
86
+ });
87
+ await this.saveRoughCutApproval(approval);
88
+ return {
89
+ ...preview,
90
+ plan: structuredClone(request.plan),
91
+ planDigest: approval.planDigest,
92
+ provenance: prepared.provenance,
93
+ outputIntent: prepared.outputIntent,
94
+ fcpxml: selectFcpxmlMetadata(fcpxml),
95
+ };
96
+ }
97
+ async executeRoughCut(request) {
98
+ if (request.approved !== true) {
99
+ throw new Error("HEADLESS_ROUGH_CUT_APPROVAL_REQUIRED: set approved=true after reviewing the preview");
100
+ }
101
+ const prepared = await this.prepareRoughCut(request);
102
+ if (!/^[a-f0-9]{64}$/.test(request.planDigest)) {
103
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: planDigest does not match the submitted rough-cut plan");
104
+ }
105
+ let approval;
106
+ try {
107
+ approval = await this.readRoughCutApproval(request.planDigest);
108
+ }
109
+ catch (error) {
110
+ if (error.code === "ENOENT") {
111
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: planDigest has no persisted preview approval");
112
+ }
113
+ throw error;
114
+ }
115
+ if (approval.inputDigest !== prepared.inputDigest
116
+ || approval.projectId !== request.projectId
117
+ || approval.sequenceId !== request.sequenceId
118
+ || !sameRevision(approval.sourceRevision, request.plan.revision)
119
+ || approval.artifactPath !== resolve(request.fcpxml.path)
120
+ || stableJson(approval.outputIntent) !== stableJson(prepared.outputIntent)) {
121
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: planDigest does not match the submitted rough-cut plan");
122
+ }
123
+ const transaction = new ProjectTransactionService(this.store(request.projectId), {
124
+ clock: () => approval.canonicalRevision.timestamp,
125
+ });
126
+ const { preview, fcpxml } = await this.previewPreparedRoughCut(request, prepared, approval.canonicalRevision.timestamp, transaction);
127
+ if (!sameRevision(preview.after.timeline.revision, approval.canonicalRevision)
128
+ || fcpxml.digest !== approval.artifactDigest) {
129
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: replayed preview differs from the approved revision or FCPXML digest");
130
+ }
131
+ const renderRequest = createFramekitRenderRequest({
132
+ timeline: preview.after.timeline,
133
+ target: { projectId: request.projectId, sequenceId: request.sequenceId },
134
+ revision: preview.after.timeline.revision,
135
+ parameters: request.render,
136
+ });
137
+ if (!this.renderer || !this.verifier) {
138
+ throw new Error("HEADLESS_ROUGH_CUT_RENDER_UNAVAILABLE: renderer and verifier are not configured");
139
+ }
140
+ const outcome = await renderAndVerifyFramekitProject(renderRequest, this.renderer, this.verifier);
141
+ const renderId = `render-${randomUUID()}`;
142
+ const renderRecord = {
143
+ renderId,
144
+ projectId: request.projectId,
145
+ sequenceId: request.sequenceId,
146
+ requestedRevision: renderRequest.projectRevision,
147
+ createdAt: this.clock(),
148
+ status: outcome.status,
149
+ outcome,
150
+ };
151
+ await this.saveRender(renderRecord);
152
+ if (outcome.status !== "passed") {
153
+ throw new Error(`HEADLESS_ROUGH_CUT_RENDER_FAILED: render verification status was ${outcome.status}; inspect ${renderId}`);
154
+ }
155
+ const fcpxmlArtifact = await writeVerifiedFcpxml(request.fcpxml.path, fcpxml.xml, fcpxml.digest, request.fcpxml.overwrite === true);
156
+ const committed = await transaction.execute(prepared.command);
157
+ const executionId = `rough-cut-${randomUUID()}`;
158
+ await this.saveRoughCutExecution({
159
+ schemaVersion: 1,
160
+ executionId,
161
+ approved: true,
162
+ projectId: request.projectId,
163
+ sequenceId: request.sequenceId,
164
+ sourceRevision: structuredClone(request.plan.revision),
165
+ canonicalRevision: structuredClone(committed.after.timeline.revision),
166
+ plan: structuredClone(request.plan),
167
+ operations: structuredClone(request.operations ?? []),
168
+ outputIntent: structuredClone(prepared.outputIntent),
169
+ planDigest: approval.planDigest,
170
+ inputDigest: prepared.inputDigest,
171
+ renderId,
172
+ artifactPath: resolve(fcpxmlArtifact.path),
173
+ artifactDigest: fcpxmlArtifact.digest,
174
+ artifactBytes: fcpxmlArtifact.bytes,
175
+ fcpxml: selectFcpxmlMetadata(fcpxml),
176
+ provenance: structuredClone(prepared.provenance),
177
+ });
178
+ return {
179
+ ...preview,
180
+ after: committed.after,
181
+ plan: structuredClone(request.plan),
182
+ planDigest: approval.planDigest,
183
+ provenance: prepared.provenance,
184
+ outputIntent: prepared.outputIntent,
185
+ fcpxml: selectFcpxmlMetadata(fcpxml),
186
+ executionId,
187
+ committed: true,
188
+ render: { renderId, status: "passed", outcome },
189
+ fcpxmlArtifact,
190
+ transaction: committed,
191
+ };
192
+ }
193
+ async verifyPublishableRoughCut(executionId, artifactPath, artifactDigest) {
194
+ validateExecutionId(executionId);
195
+ let record;
196
+ try {
197
+ record = JSON.parse(await readFile(this.executionPath(executionId), "utf8"));
198
+ }
199
+ catch (error) {
200
+ if (error.code === "ENOENT") {
201
+ throw new Error(`HEADLESS_ROUGH_CUT_EXECUTION_NOT_FOUND: unknown approved rough-cut execution ${executionId}`);
202
+ }
203
+ throw error;
204
+ }
205
+ const { evidenceDigest, ...unsignedRecord } = record;
206
+ if (record.schemaVersion !== 1 || record.executionId !== executionId || record.approved !== true
207
+ || !evidenceDigest || hash(stableJson(unsignedRecord)) !== evidenceDigest) {
208
+ throw new Error(`HEADLESS_ROUGH_CUT_EXECUTION_INVALID: approved rough-cut provenance is invalid for ${executionId}`);
209
+ }
210
+ const expectedInputDigest = digestRoughCutPlan(record.plan, record.operations, record.outputIntent);
211
+ if (expectedInputDigest !== record.inputDigest) {
212
+ throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: persisted rough-cut input digest does not match its plan and output intent");
213
+ }
214
+ const approval = await this.readRoughCutApproval(record.planDigest);
215
+ if (approval.inputDigest !== record.inputDigest
216
+ || approval.projectId !== record.projectId
217
+ || approval.sequenceId !== record.sequenceId
218
+ || !sameRevision(approval.sourceRevision, record.sourceRevision)
219
+ || !sameRevision(approval.canonicalRevision, record.canonicalRevision)
220
+ || approval.artifactPath !== record.artifactPath
221
+ || approval.artifactDigest !== record.artifactDigest
222
+ || stableJson(approval.outputIntent) !== stableJson(record.outputIntent)) {
223
+ throw new Error("HEADLESS_ROUGH_CUT_EXECUTION_INVALID: persisted execution differs from its approved preview");
224
+ }
225
+ if (!sameRevision(record.sourceRevision, record.plan.revision)) {
226
+ throw new Error("HEADLESS_ROUGH_CUT_EXECUTION_INVALID: source revision differs from the approved plan revision");
227
+ }
228
+ if (!sameRevision(record.canonicalRevision, record.fcpxml.provenance.revision)) {
229
+ throw new Error("HEADLESS_ROUGH_CUT_REVISION_MISMATCH: FCPXML provenance differs from the committed canonical revision");
230
+ }
231
+ if (record.fcpxml.destination.mode !== "versioned") {
232
+ throw new Error("HEADLESS_ROUGH_CUT_TARGET_NOT_CREATE_ONLY: native delivery requires a versioned create-only project target");
233
+ }
234
+ if (resolve(artifactPath) !== record.artifactPath) {
235
+ throw new Error("HEADLESS_ROUGH_CUT_ARTIFACT_TARGET_MISMATCH: requested path differs from the approved artifact path");
236
+ }
237
+ if (artifactDigest !== undefined && artifactDigest !== record.artifactDigest) {
238
+ throw new Error("HEADLESS_ROUGH_CUT_ARTIFACT_CHANGED: requested digest differs from the approved artifact digest");
239
+ }
240
+ const project = await this.open(record.projectId);
241
+ if (project.timeline.sequence.id !== record.sequenceId
242
+ || !sameRevision(project.timeline.revision, record.canonicalRevision)) {
243
+ throw new Error("HEADLESS_ROUGH_CUT_STALE_REVISION: canonical project changed after the approved rough cut");
244
+ }
245
+ const approvedSnapshot = await new FcpxmlDocumentAdapter(record.artifactPath, undefined, {
246
+ allowMissingImmutableIdsForReadback: true,
247
+ }).readProject();
248
+ const referencedMediaIds = new Set([
249
+ ...approvedSnapshot.timeline.clips.map(({ mediaId }) => mediaId),
250
+ ...approvedSnapshot.timeline.storyElements.map(({ mediaId }) => mediaId),
251
+ ].filter((mediaId) => mediaId !== undefined));
252
+ const approvedSources = approvedSnapshot.media
253
+ .filter(({ mediaId }) => referencedMediaIds.has(mediaId))
254
+ .map(({ source }) => resolve(source));
255
+ const digestBySource = new Map(project.timeline.resources
256
+ .filter((resource) => resource.source && resource.sourceDigest)
257
+ .map((resource) => [resolveMediaSource(resource.source, record.artifactPath), resource.sourceDigest]));
258
+ const sourceMediaDigests = [...new Set(approvedSources)].sort().map((source) => {
259
+ const sha256 = digestBySource.get(source);
260
+ if (!sha256) {
261
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MEDIA_DIGEST_UNAVAILABLE: no approved source digest is bound to ${source}`);
262
+ }
263
+ return { source, sha256 };
264
+ });
265
+ const render = await this.inspectRender(record.renderId);
266
+ if (render.status !== "passed" || render.projectId !== record.projectId || render.sequenceId !== record.sequenceId
267
+ || !sameRevision(render.requestedRevision, record.canonicalRevision)) {
268
+ throw new Error("HEADLESS_ROUGH_CUT_RENDER_EVIDENCE_MISMATCH: render evidence does not match the approved revision");
269
+ }
270
+ const artifact = await readFile(record.artifactPath, "utf8");
271
+ if (hash(artifact) !== record.artifactDigest || Buffer.byteLength(artifact) !== record.artifactBytes) {
272
+ throw new Error("HEADLESS_ROUGH_CUT_ARTIFACT_CHANGED: approved FCPXML no longer matches its recorded digest");
273
+ }
274
+ if (!record.fcpxml.target.libraryUid?.trim()
275
+ || !record.fcpxml.destination.projectUid?.trim()
276
+ || !record.fcpxml.destination.sequenceUid?.trim()) {
277
+ throw new Error("HEADLESS_ROUGH_CUT_TARGET_INVALID: approved FCPXML has no explicit library, project, and sequence target");
278
+ }
279
+ return {
280
+ executionId,
281
+ sourceTransactionId: `headless-rough-cut:${executionId}`,
282
+ projectId: record.projectId,
283
+ sequenceId: record.sequenceId,
284
+ sourceRevision: structuredClone(record.sourceRevision),
285
+ canonicalRevision: structuredClone(record.canonicalRevision),
286
+ planDigest: record.planDigest,
287
+ renderId: record.renderId,
288
+ artifactPath: record.artifactPath,
289
+ artifactDigest: record.artifactDigest,
290
+ sourceAudioPolicy: record.outputIntent.sourceAudioPolicy,
291
+ target: structuredClone(record.fcpxml.target),
292
+ destination: structuredClone(record.fcpxml.destination),
293
+ coverage: structuredClone(record.fcpxml.coverage),
294
+ provenance: structuredClone(record.provenance),
295
+ targetLibraryUid: record.fcpxml.target.libraryUid,
296
+ sourceMediaDigests,
297
+ };
298
+ }
299
+ async verifyPublishableRoughCutTransaction(request) {
300
+ const prefix = "headless-rough-cut:";
301
+ if (!request.sourceTransactionId.startsWith(prefix)) {
302
+ throw new Error("HEADLESS_ROUGH_CUT_EXECUTION_INVALID: source transaction is not a rough-cut execution");
303
+ }
304
+ return this.verifyPublishableRoughCut(request.sourceTransactionId.slice(prefix.length), request.artifactPath, request.artifactDigest);
305
+ }
72
306
  async render(projectId, sequenceId, parameters, expectedRevision) {
73
307
  if (!this.renderer || !this.verifier)
74
308
  throw new Error("HEADLESS_RENDER_UNAVAILABLE: renderer and verifier are not configured");
@@ -111,6 +345,14 @@ export class HeadlessProjectService {
111
345
  validateProjectId(projectId);
112
346
  return join(this.directory, `${projectId}.json`);
113
347
  }
348
+ executionPath(executionId) {
349
+ validateExecutionId(executionId);
350
+ return join(this.directory, `${executionId}.json`);
351
+ }
352
+ approvalPath(planDigest) {
353
+ validatePlanDigest(planDigest);
354
+ return join(this.directory, `${planDigest}.approval.json`);
355
+ }
114
356
  async saveRender(record) {
115
357
  await mkdir(this.directory, { recursive: true });
116
358
  const path = join(this.directory, `${record.renderId}.json`);
@@ -118,6 +360,223 @@ export class HeadlessProjectService {
118
360
  await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "wx" });
119
361
  await rename(temporary, path);
120
362
  }
363
+ async saveRoughCutExecution(record) {
364
+ await mkdir(this.directory, { recursive: true });
365
+ const execution = { ...record, evidenceDigest: hash(stableJson(record)) };
366
+ const path = this.executionPath(record.executionId);
367
+ const temporary = `${path}.${randomUUID()}.tmp`;
368
+ await writeFile(temporary, `${JSON.stringify(execution)}\n`, { encoding: "utf8", flag: "wx" });
369
+ await rename(temporary, path);
370
+ }
371
+ async saveRoughCutApproval(record) {
372
+ await mkdir(this.directory, { recursive: true });
373
+ const approval = { ...record, evidenceDigest: hash(stableJson(record)) };
374
+ const path = this.approvalPath(record.planDigest);
375
+ const temporary = `${path}.${randomUUID()}.tmp`;
376
+ await writeFile(temporary, `${JSON.stringify(approval)}\n`, { encoding: "utf8", flag: "wx" });
377
+ await rename(temporary, path);
378
+ }
379
+ async readRoughCutApproval(planDigest) {
380
+ const approval = JSON.parse(await readFile(this.approvalPath(planDigest), "utf8"));
381
+ const { evidenceDigest, ...unsignedApproval } = approval;
382
+ const { planDigest: storedDigest, ...digestFields } = unsignedApproval;
383
+ if (approval.schemaVersion !== 1 || storedDigest !== planDigest
384
+ || !evidenceDigest || hash(stableJson(unsignedApproval)) !== evidenceDigest
385
+ || hash(stableJson(digestFields)) !== planDigest) {
386
+ throw new Error(`HEADLESS_ROUGH_CUT_APPROVAL_INVALID: persisted approval is invalid for ${planDigest}`);
387
+ }
388
+ return approval;
389
+ }
390
+ async prepareRoughCut(request) {
391
+ await this.open(request.projectId);
392
+ const project = await this.store(request.projectId).load();
393
+ if (project.timeline.sequence.id !== request.sequenceId) {
394
+ throw new Error("HEADLESS_ROUGH_CUT_TARGET_MISMATCH: sequenceId does not match the persisted project");
395
+ }
396
+ if (!sameRevision(project.timeline.revision, request.plan.revision)) {
397
+ throw new Error("HEADLESS_ROUGH_CUT_STALE_REVISION: rough-cut plan revision does not match the persisted project");
398
+ }
399
+ if (!request.plan.shots.length)
400
+ throw new Error("HEADLESS_ROUGH_CUT_EMPTY_PLAN: rough-cut plan must contain at least one shot");
401
+ const operations = structuredClone(request.operations ?? []);
402
+ const sourceAudioPolicy = request.sourceAudioPolicy ?? "preserve-and-mix";
403
+ const outputIntent = {
404
+ sourceAudioPolicy,
405
+ render: structuredClone(request.render),
406
+ fcpxml: {
407
+ path: request.fcpxml.path,
408
+ target: structuredClone(request.fcpxml.target),
409
+ overwrite: request.fcpxml.overwrite === true,
410
+ },
411
+ };
412
+ const inputDigest = digestRoughCutPlan(request.plan, operations, outputIntent);
413
+ const existingOccurrenceIds = new Set(project.timeline.sequence.occurrences.map(({ id }) => id));
414
+ const resourceByMediaId = new Map(project.timeline.resources.map((resource) => [resource.id, resource]));
415
+ const hasPrimaryStoryContent = project.timeline.sequence.occurrences.some(({ track }) => track === 0)
416
+ || project.timeline.sequence.storyElements.length > 0;
417
+ const provenance = [];
418
+ const planOperations = [];
419
+ for (const shot of request.plan.shots) {
420
+ const shotWithEvidence = shot;
421
+ const occurrenceId = `rough-cut-${shot.order}`;
422
+ if (existingOccurrenceIds.has(occurrenceId)) {
423
+ throw new Error(`HEADLESS_ROUGH_CUT_OCCURRENCE_COLLISION: ${occurrenceId} already exists`);
424
+ }
425
+ existingOccurrenceIds.add(occurrenceId);
426
+ const resource = resourceByMediaId.get(shot.sourceIdentity.mediaId);
427
+ if (!resource)
428
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_NOT_FOUND: ${shot.sourceIdentity.mediaId}`);
429
+ assertSourceIdentity(resource, shot.sourceIdentity);
430
+ const sourceStartTime = shot.range.startTime ?? secondsToRational(shot.range.start);
431
+ const durationTime = shot.range.durationTime ?? secondsToRational(shot.range.end - shot.range.start);
432
+ assertSourceRange(resource, shot.range, sourceStartTime, durationTime);
433
+ const appendToPrimaryStoryline = hasPrimaryStoryContent || planOperations.length > 0;
434
+ planOperations.push({
435
+ type: "insert-occurrence",
436
+ ...(appendToPrimaryStoryline ? { placement: "append" } : {}),
437
+ occurrence: {
438
+ id: occurrenceId,
439
+ name: `Rough cut ${shot.order}: ${shot.rationale}`,
440
+ startTime: { value: "0", timescale: "1" },
441
+ durationTime,
442
+ sourceStartTime,
443
+ track: 0,
444
+ role: "video",
445
+ mediaId: resource.id,
446
+ binding: { provider: "framekit.rough-cut", kind: "occurrence", identity: `${inputDigest}:${shot.order}` },
447
+ },
448
+ });
449
+ provenance.push({
450
+ order: shot.order,
451
+ occurrenceId,
452
+ mediaId: resource.id,
453
+ sourceIdentity: structuredClone(shot.sourceIdentity),
454
+ sourceRange: structuredClone(shot.range),
455
+ confidence: shot.confidence,
456
+ matchedProperties: [...shot.matchedProperties],
457
+ rationale: shot.rationale,
458
+ ...(shotWithEvidence.evidence ? { evidence: structuredClone(shotWithEvidence.evidence) } : {}),
459
+ });
460
+ }
461
+ const editOperations = [...planOperations, ...operations];
462
+ const command = {
463
+ schemaVersion: 1,
464
+ target: { projectId: request.projectId, sequenceId: request.sequenceId },
465
+ expectedRevision: structuredClone(request.plan.revision),
466
+ operations: editOperations,
467
+ };
468
+ return { command, inputDigest, provenance, outputIntent };
469
+ }
470
+ async previewPreparedRoughCut(request, prepared, timestamp, transaction = new ProjectTransactionService(this.store(request.projectId), { clock: () => timestamp })) {
471
+ const rawPreview = await transaction.preview(prepared.command);
472
+ const canonicalRevision = {
473
+ id: `ir:${timelineIrDigest(rawPreview.after.timeline)}`,
474
+ sequence: rawPreview.before.timeline.revision.sequence + 1,
475
+ timestamp,
476
+ };
477
+ const canonicalTimeline = structuredClone(rawPreview.after.timeline);
478
+ canonicalTimeline.revision = canonicalRevision;
479
+ const preview = {
480
+ ...rawPreview,
481
+ after: { ...rawPreview.after, timeline: canonicalTimeline },
482
+ };
483
+ const fcpxml = compileTimelineIrToFcpxml(canonicalTimeline, { target: request.fcpxml.target });
484
+ return { preview, fcpxml };
485
+ }
486
+ }
487
+ function createRoughCutApproval(fields) {
488
+ const digestFields = { schemaVersion: 1, ...fields };
489
+ const planDigest = hash(stableJson(digestFields));
490
+ return { ...digestFields, planDigest };
491
+ }
492
+ function digestRoughCutPlan(plan, operations, outputIntent) {
493
+ return createHash("sha256").update(stableJson({ plan, operations, outputIntent })).digest("hex");
494
+ }
495
+ function stableJson(value) {
496
+ if (value === null || typeof value !== "object")
497
+ return JSON.stringify(value);
498
+ if (Array.isArray(value))
499
+ return `[${value.map(stableJson).join(",")}]`;
500
+ return `{${Object.entries(value).filter(([, child]) => child !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
501
+ }
502
+ function assertSourceIdentity(resource, source) {
503
+ if (resource.source !== source.source)
504
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source path differs for ${source.mediaId}`);
505
+ if (source.sourceDigest !== undefined && resource.sourceDigest !== source.sourceDigest) {
506
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source digest differs for ${source.mediaId}`);
507
+ }
508
+ if (source.mediaKind !== undefined && resource.mediaKind !== source.mediaKind) {
509
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: media kind differs for ${source.mediaId}`);
510
+ }
511
+ if (resource.mediaKind !== "video")
512
+ throw new Error(`HEADLESS_ROUGH_CUT_VIDEO_REQUIRED: ${source.mediaId}`);
513
+ if (source.duration !== undefined && resource.metadata?.durationTime !== undefined
514
+ && Math.abs(source.duration - rationalSeconds(resource.metadata.durationTime)) > 0.01) {
515
+ throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source duration differs for ${source.mediaId}`);
516
+ }
517
+ }
518
+ function assertSourceRange(resource, range, sourceStartTime, durationTime) {
519
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.start < 0 || range.end <= range.start) {
520
+ throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: source range must be finite and non-empty");
521
+ }
522
+ if (resource.metadata?.durationTime !== undefined && range.end > rationalSeconds(resource.metadata.durationTime) + 0.001) {
523
+ throw new Error(`HEADLESS_ROUGH_CUT_RANGE_INVALID: source range exceeds ${resource.id}`);
524
+ }
525
+ if (rationalSeconds(sourceStartTime) < 0 || rationalSeconds(durationTime) <= 0
526
+ || Math.abs(rationalSeconds(sourceStartTime) - range.start) > 0.001
527
+ || Math.abs(rationalSeconds(durationTime) - (range.end - range.start)) > 0.001) {
528
+ throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: rational source range must be non-negative and non-empty");
529
+ }
530
+ }
531
+ function secondsToRational(seconds) {
532
+ const timescale = 1_000_000;
533
+ const value = Math.round(seconds * timescale);
534
+ const divisor = greatestCommonDivisor(Math.abs(value), timescale);
535
+ return { value: String(value / divisor), timescale: String(timescale / divisor) };
536
+ }
537
+ function rationalSeconds(time) {
538
+ return Number(time.value) / Number(time.timescale);
539
+ }
540
+ function greatestCommonDivisor(left, right) {
541
+ while (right !== 0) {
542
+ const remainder = left % right;
543
+ left = right;
544
+ right = remainder;
545
+ }
546
+ return left || 1;
547
+ }
548
+ function sameRevision(left, right) {
549
+ return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
550
+ }
551
+ function selectFcpxmlMetadata(result) {
552
+ return {
553
+ digest: result.digest,
554
+ target: structuredClone(result.target),
555
+ destination: structuredClone(result.destination),
556
+ coverage: structuredClone(result.coverage),
557
+ provenance: structuredClone(result.provenance),
558
+ };
559
+ }
560
+ async function writeVerifiedFcpxml(path, xml, digest, overwrite) {
561
+ await mkdir(dirname(path), { recursive: true });
562
+ if (!overwrite) {
563
+ try {
564
+ await readFile(path);
565
+ throw new Error(`HEADLESS_ROUGH_CUT_FCPXML_EXISTS: refusing to overwrite ${path}`);
566
+ }
567
+ catch (error) {
568
+ if (error.code !== "ENOENT")
569
+ throw error;
570
+ }
571
+ }
572
+ const temporary = `${path}.${randomUUID()}.tmp`;
573
+ await writeFile(temporary, xml, { encoding: "utf8", flag: "wx" });
574
+ await rename(temporary, path);
575
+ const persisted = await readFile(path, "utf8");
576
+ const persistedDigest = createHash("sha256").update(persisted).digest("hex");
577
+ if (persistedDigest !== digest)
578
+ throw new Error("HEADLESS_ROUGH_CUT_FCPXML_VERIFY_FAILED: persisted XML digest differs from the compiled artifact");
579
+ return { path, digest, bytes: Buffer.byteLength(persisted), verified: true };
121
580
  }
122
581
  function toSummary(project, path) {
123
582
  return {
@@ -137,3 +596,14 @@ function validateRenderId(renderId) {
137
596
  if (!/^render-[0-9a-f-]{36}$/.test(renderId))
138
597
  throw new Error("HEADLESS_RENDER_INVALID: renderId is invalid");
139
598
  }
599
+ function validateExecutionId(executionId) {
600
+ if (!/^rough-cut-[0-9a-f-]{36}$/.test(executionId))
601
+ throw new Error("HEADLESS_ROUGH_CUT_EXECUTION_INVALID: executionId is invalid");
602
+ }
603
+ function validatePlanDigest(planDigest) {
604
+ if (!/^[a-f0-9]{64}$/.test(planDigest))
605
+ throw new Error("HEADLESS_ROUGH_CUT_APPROVAL_INVALID: planDigest is invalid");
606
+ }
607
+ function hash(value) {
608
+ return createHash("sha256").update(value).digest("hex");
609
+ }
@@ -2,9 +2,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
2
2
  import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
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";
5
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, 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
10
  import { HeadlessProjectService } from "./headless-projects.js";
@@ -164,6 +164,7 @@ const editor = liveMode
164
164
  : {}),
165
165
  })
166
166
  : fixture;
167
+ const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
167
168
  const analyzers = liveMode
168
169
  ? createCommandAnalyzers({
169
170
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
@@ -180,8 +181,10 @@ const analyzers = liveMode
180
181
  visualAnalyzer: new FixtureVisualAnalyzer(),
181
182
  metadataAnalyzer: new FixtureMetadataAnalyzer(),
182
183
  };
183
- const runtime = new AgentVideoRuntime(editor, analyzers);
184
- 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
+ });
185
188
  const headlessProjects = new HeadlessProjectService({
186
189
  directory: join(framekitStateDirectory, "projects"),
187
190
  mediaProbe: new FfmpegMediaMetadataProbe(),
@@ -209,10 +212,30 @@ const projectPublisher = liveMode && fcpxmlPath
209
212
  ? new FinalCutProjectPublisher({
210
213
  enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
211
214
  sourcePath: fcpxmlPath,
215
+ publishJobsDirectory: join(framekitStateDirectory, "publish-jobs"),
212
216
  documentDelivery: liveAdapter,
213
- targetLibraryUid: process.env.FRAMEKIT_FINAL_CUT_LIBRARY_UID,
214
- allowHeadedFallback: process.env.FRAMEKIT_FINAL_CUT_ALLOW_HEADED_IMPORT === "1",
217
+ publishRoute: parseFinalCutProjectPublishRoute(process.env.FRAMEKIT_FINAL_CUT_PUBLISH_ROUTE, Boolean(liveAdapter)),
215
218
  liveState: () => liveAdapter.readLiveState(),
219
+ readCanonicalSnapshot: (targetBinding, identity) => new FinalCutCanonicalSnapshotSource({
220
+ readbackTarget: { ...targetBinding, ...identity },
221
+ }).readSnapshot(),
222
+ targetBinding: (targetLibraryPath, identity) => {
223
+ if (!targetLibraryPath || !backgroundLibraryProvider) {
224
+ throw new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: a target library path and Final Cut library catalog are required");
225
+ }
226
+ return backgroundLibraryProvider.resolveProjectBinding(targetLibraryPath, identity);
227
+ },
228
+ headlessSourceVerifier: async (request) => {
229
+ const proof = await headlessProjects.verifyPublishableRoughCutTransaction({
230
+ sourceTransactionId: request.sourceTransactionId,
231
+ artifactPath: request.artifactPath,
232
+ artifactDigest: request.artifactDigest,
233
+ });
234
+ return {
235
+ targetLibraryUid: proof.targetLibraryUid,
236
+ sourceMediaDigests: proof.sourceMediaDigests,
237
+ };
238
+ },
216
239
  })
217
240
  : undefined;
218
241
  const backgroundMaterializationCommand = liveMode
@@ -241,6 +264,10 @@ const server = createMcpServer(runtime, {
241
264
  projectPublisher,
242
265
  ...(sessionMaterializationPublisher?.isAvailable() ? { sessionMaterializationPublisher } : {}),
243
266
  videoExporter,
267
+ requireBuildAlignment: process.env.FRAMEKIT_REQUIRE_BUILD_ALIGNMENT === "1",
268
+ ...(process.env.FRAMEKIT_VALIDATION_COMMIT?.trim()
269
+ ? { validationCommit: process.env.FRAMEKIT_VALIDATION_COMMIT.trim() }
270
+ : {}),
244
271
  sessionDirectory: join(framekitStateDirectory, "sessions"),
245
272
  sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
246
273
  materializationDirectory: join(framekitStateDirectory, "materializations"),