@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.
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +28 -4
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +311 -34
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
- package/dist-package/packages/runtime/src/index.js +7 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
- package/dist-package/packages/runtime/src/runtime.js +5 -2
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createHash, randomUUID } from "node:crypto";
|
|
2
2
|
import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
|
|
3
3
|
import { dirname, join } from "node:path";
|
|
4
|
-
import { timelineIrDigest } from "../../../packages/runtime/src/index.js";
|
|
4
|
+
import { timelineIrDigest, validateTimelineIr } from "../../../packages/runtime/src/index.js";
|
|
5
5
|
import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
6
|
export class SessionMaterializationJobs {
|
|
7
7
|
directory;
|
|
@@ -25,6 +25,8 @@ export class SessionMaterializationJobs {
|
|
|
25
25
|
destination: artifact.destination,
|
|
26
26
|
collisionPolicy: "create-only",
|
|
27
27
|
artifactDigest: artifact.digest,
|
|
28
|
+
coverage: artifact.coverage,
|
|
29
|
+
provenance: artifact.provenance,
|
|
28
30
|
evidence: { artifact: { verified: true, format: "fcpxml", digest: artifact.digest } },
|
|
29
31
|
};
|
|
30
32
|
}
|
|
@@ -43,7 +45,7 @@ export class SessionMaterializationJobs {
|
|
|
43
45
|
session.markWaitingForMaterialization();
|
|
44
46
|
await this.sessions.checkpoint(sessionId, session);
|
|
45
47
|
let job = {
|
|
46
|
-
schemaVersion:
|
|
48
|
+
schemaVersion: 2,
|
|
47
49
|
jobId,
|
|
48
50
|
sessionId,
|
|
49
51
|
state: "blocked",
|
|
@@ -54,6 +56,10 @@ export class SessionMaterializationJobs {
|
|
|
54
56
|
destination: artifact.destination,
|
|
55
57
|
desired: structuredClone(desired),
|
|
56
58
|
desiredDigest: timelineIrDigest(desired),
|
|
59
|
+
baseDigest: timelineIrDigest(session.base()),
|
|
60
|
+
baseRevision: structuredClone(session.base().revision),
|
|
61
|
+
coverage: artifact.coverage,
|
|
62
|
+
provenance: artifact.provenance,
|
|
57
63
|
sessionDigest: digestSession(session),
|
|
58
64
|
evidence: {
|
|
59
65
|
artifact: { verified: true, format: "fcpxml", digest: artifact.digest },
|
|
@@ -61,6 +67,13 @@ export class SessionMaterializationJobs {
|
|
|
61
67
|
canonicalReadback: false,
|
|
62
68
|
headedNative: false,
|
|
63
69
|
},
|
|
70
|
+
verification: {
|
|
71
|
+
tier: "artifact",
|
|
72
|
+
status: "blocked",
|
|
73
|
+
artifactDigest: artifact.digest,
|
|
74
|
+
desiredDigest: timelineIrDigest(desired),
|
|
75
|
+
reason: "No Final Cut materialization publisher is configured; retry when a provider is available",
|
|
76
|
+
},
|
|
64
77
|
error: {
|
|
65
78
|
code: "MATERIALIZATION_PROVIDER_UNAVAILABLE",
|
|
66
79
|
message: "No Final Cut materialization publisher is configured; retry when a provider is available",
|
|
@@ -73,9 +86,10 @@ export class SessionMaterializationJobs {
|
|
|
73
86
|
async status(jobId) {
|
|
74
87
|
try {
|
|
75
88
|
const job = JSON.parse(await readFile(this.jobPath(jobId), "utf8"));
|
|
76
|
-
if (job.schemaVersion !== 1
|
|
89
|
+
if (job.jobId !== jobId || (job.schemaVersion !== 1 && job.schemaVersion !== 2)) {
|
|
77
90
|
throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
|
|
78
|
-
|
|
91
|
+
}
|
|
92
|
+
return structuredClone(normalizePersistedJob(job));
|
|
79
93
|
}
|
|
80
94
|
catch (error) {
|
|
81
95
|
if (error.code === "ENOENT") {
|
|
@@ -92,6 +106,59 @@ export class SessionMaterializationJobs {
|
|
|
92
106
|
throw new Error(`MATERIALIZATION_NOT_RETRYABLE: job ${jobId} cannot be retried`);
|
|
93
107
|
return this.attempt(job);
|
|
94
108
|
}
|
|
109
|
+
async resync(jobId, sessionId) {
|
|
110
|
+
const job = await this.status(jobId);
|
|
111
|
+
if (job.state !== "completed") {
|
|
112
|
+
throw new Error("MATERIALIZATION_NOT_COMPLETED: canonical continuation requires a completed handoff");
|
|
113
|
+
}
|
|
114
|
+
const verification = job.verification;
|
|
115
|
+
const target = verification?.canonicalTarget;
|
|
116
|
+
if (!target) {
|
|
117
|
+
throw new Error("MATERIALIZATION_TARGET_UNAVAILABLE: completed handoff has no verified target identity");
|
|
118
|
+
}
|
|
119
|
+
if (!this.publisher?.readCanonicalTarget) {
|
|
120
|
+
throw new Error("MATERIALIZATION_CANONICAL_RESYNC_UNAVAILABLE: no target-bound canonical readback capability is configured");
|
|
121
|
+
}
|
|
122
|
+
const result = await this.publisher.readCanonicalTarget({ target: structuredClone(target) });
|
|
123
|
+
validateTimelineIr(result.canonicalReadback);
|
|
124
|
+
if (!sameTarget(result.canonicalTarget, target)
|
|
125
|
+
|| result.canonicalReadback.project.id !== target.projectUid
|
|
126
|
+
|| result.canonicalReadback.sequence.id !== target.sequenceUid) {
|
|
127
|
+
throw new Error("MATERIALIZATION_RESYNC_TARGET_MISMATCH: canonical readback does not identify the completed handoff target");
|
|
128
|
+
}
|
|
129
|
+
const readbackDigest = timelineIrDigest(result.canonicalReadback);
|
|
130
|
+
const changeSinceHandoff = verification.canonicalReadbackDigest
|
|
131
|
+
? readbackDigest === verification.canonicalReadbackDigest ? "unchanged" : "changed"
|
|
132
|
+
: "unknown";
|
|
133
|
+
const created = await this.sessions.create({
|
|
134
|
+
sessionId,
|
|
135
|
+
base: result.canonicalReadback,
|
|
136
|
+
provider: { id: job.target.provider },
|
|
137
|
+
});
|
|
138
|
+
const continuation = {
|
|
139
|
+
state: "resynced",
|
|
140
|
+
reason: changeSinceHandoff === "changed"
|
|
141
|
+
? "Canonical state changed after handoff; a fresh session was created from the current target readback."
|
|
142
|
+
: changeSinceHandoff === "unchanged"
|
|
143
|
+
? "Canonical state matches the handoff readback; a fresh session was created from the current target readback."
|
|
144
|
+
: "A fresh session was created from target-bound canonical readback; comparison with the handoff snapshot was unavailable.",
|
|
145
|
+
sessionId,
|
|
146
|
+
readbackDigest,
|
|
147
|
+
changeSinceHandoff,
|
|
148
|
+
...(result.delivery ? { delivery: result.delivery } : {}),
|
|
149
|
+
};
|
|
150
|
+
await this.save({ ...job, continuation });
|
|
151
|
+
return {
|
|
152
|
+
jobId,
|
|
153
|
+
state: continuation.state,
|
|
154
|
+
sessionId,
|
|
155
|
+
changeSinceHandoff,
|
|
156
|
+
canonicalTarget: structuredClone(result.canonicalTarget),
|
|
157
|
+
readbackDigest,
|
|
158
|
+
document: created.document,
|
|
159
|
+
...(result.delivery ? { delivery: result.delivery } : {}),
|
|
160
|
+
};
|
|
161
|
+
}
|
|
95
162
|
async attempt(job) {
|
|
96
163
|
if (!this.publisher || job.state === "publishing")
|
|
97
164
|
return job;
|
|
@@ -115,6 +182,10 @@ export class SessionMaterializationJobs {
|
|
|
115
182
|
collisionPolicy: "create-only",
|
|
116
183
|
desired: structuredClone(claimed.desired),
|
|
117
184
|
desiredDigest: claimed.desiredDigest,
|
|
185
|
+
baseDigest: claimed.baseDigest,
|
|
186
|
+
baseRevision: structuredClone(claimed.baseRevision),
|
|
187
|
+
coverage: structuredClone(claimed.coverage),
|
|
188
|
+
provenance: structuredClone(claimed.provenance),
|
|
118
189
|
});
|
|
119
190
|
if (result.state === "blocked") {
|
|
120
191
|
const blocked = {
|
|
@@ -123,6 +194,14 @@ export class SessionMaterializationJobs {
|
|
|
123
194
|
nextAction: "retry",
|
|
124
195
|
claim: undefined,
|
|
125
196
|
evidence: { ...claimed.evidence, providerRequested: true },
|
|
197
|
+
verification: {
|
|
198
|
+
tier: verificationTierForBlockedCode(result.code),
|
|
199
|
+
status: "blocked",
|
|
200
|
+
artifactDigest: claimed.verification?.artifactDigest ?? claimed.artifactDigest,
|
|
201
|
+
desiredDigest: claimed.verification?.desiredDigest ?? claimed.desiredDigest,
|
|
202
|
+
reason: result.message,
|
|
203
|
+
...(result.delivery ? { delivery: result.delivery } : { delivery: deliveryEvidenceForBlockedCode(result.code) }),
|
|
204
|
+
},
|
|
126
205
|
error: { code: result.code, message: result.message, retryable: result.retryable },
|
|
127
206
|
};
|
|
128
207
|
await this.save(blocked);
|
|
@@ -134,6 +213,8 @@ export class SessionMaterializationJobs {
|
|
|
134
213
|
message: "Canonical provider readback does not match the desired Timeline IR",
|
|
135
214
|
retryable: false,
|
|
136
215
|
providerRequested: true,
|
|
216
|
+
verificationTier: "delivery",
|
|
217
|
+
structuralDiff: createMaterializationStructuralDiff(claimed.desired, result.canonicalReadback),
|
|
137
218
|
});
|
|
138
219
|
}
|
|
139
220
|
const expectedTarget = {
|
|
@@ -162,6 +243,22 @@ export class SessionMaterializationJobs {
|
|
|
162
243
|
headedNative: result.headedNativeVerified,
|
|
163
244
|
},
|
|
164
245
|
error: undefined,
|
|
246
|
+
verification: {
|
|
247
|
+
tier: "canonical-verified",
|
|
248
|
+
status: "verified",
|
|
249
|
+
artifactDigest: claimed.artifactDigest,
|
|
250
|
+
desiredDigest: claimed.desiredDigest,
|
|
251
|
+
canonicalReadbackDigest: timelineIrDigest(result.canonicalReadback),
|
|
252
|
+
canonicalTarget: structuredClone(result.canonicalTarget),
|
|
253
|
+
delivery: result.delivery ?? {
|
|
254
|
+
state: result.headedNativeVerified ? "activated" : "background",
|
|
255
|
+
route: result.headedNativeVerified ? "headed" : "background",
|
|
256
|
+
},
|
|
257
|
+
},
|
|
258
|
+
continuation: {
|
|
259
|
+
state: "canonical-resync-required",
|
|
260
|
+
reason: "Canonical readback verified this handoff once. Re-read the materialized target before later edits to detect subsequent manual Final Cut changes.",
|
|
261
|
+
},
|
|
165
262
|
};
|
|
166
263
|
await this.save(completed);
|
|
167
264
|
return completed;
|
|
@@ -181,6 +278,40 @@ export class SessionMaterializationJobs {
|
|
|
181
278
|
retryable: false,
|
|
182
279
|
};
|
|
183
280
|
}
|
|
281
|
+
if (!job.coverage || !job.provenance) {
|
|
282
|
+
return {
|
|
283
|
+
code: "MATERIALIZATION_JOB_METADATA_UNAVAILABLE",
|
|
284
|
+
message: "This persisted materialization job predates target-bound coverage and provenance; execute a new preview before retrying",
|
|
285
|
+
retryable: false,
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
if (job.provenance.timelineDigest !== job.desiredDigest
|
|
289
|
+
|| job.provenance.projectId !== job.desired.project.id
|
|
290
|
+
|| job.provenance.sequenceId !== job.desired.sequence.id
|
|
291
|
+
|| job.provenance.revision?.id !== job.desired.revision.id
|
|
292
|
+
|| job.provenance.revision?.sequence !== job.desired.revision.sequence
|
|
293
|
+
|| job.provenance.revision?.timestamp !== job.desired.revision.timestamp
|
|
294
|
+
|| job.provenance.target?.libraryUid !== job.target.libraryUid
|
|
295
|
+
|| job.provenance.target?.eventUid !== job.target.eventUid
|
|
296
|
+
|| job.provenance.target?.projectUid !== job.target.projectUid
|
|
297
|
+
|| job.provenance.target?.sequenceUid !== job.target.sequenceUid
|
|
298
|
+
|| job.provenance.destination?.projectUid !== job.destination.projectUid
|
|
299
|
+
|| job.provenance.destination?.sequenceUid !== job.destination.sequenceUid) {
|
|
300
|
+
return {
|
|
301
|
+
code: "MATERIALIZATION_PROVENANCE_INVALID",
|
|
302
|
+
message: "The persisted materialization provenance does not bind to the desired revision and target",
|
|
303
|
+
retryable: false,
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
if (!Array.isArray(job.coverage.exact) || !Array.isArray(job.coverage.degraded) || !Array.isArray(job.coverage.unsupported)
|
|
307
|
+
|| ![...job.coverage.exact, ...job.coverage.degraded, ...job.coverage.unsupported].every((value) => typeof value === "string" && value.trim())
|
|
308
|
+
|| job.coverage.unsupported.length > 0) {
|
|
309
|
+
return {
|
|
310
|
+
code: "MATERIALIZATION_COVERAGE_INVALID",
|
|
311
|
+
message: "The persisted materialization coverage is unsupported or malformed",
|
|
312
|
+
retryable: false,
|
|
313
|
+
};
|
|
314
|
+
}
|
|
184
315
|
if (!job.sessionDigest) {
|
|
185
316
|
return {
|
|
186
317
|
code: "MATERIALIZATION_SESSION_SNAPSHOT_INVALID",
|
|
@@ -188,8 +319,31 @@ export class SessionMaterializationJobs {
|
|
|
188
319
|
retryable: false,
|
|
189
320
|
};
|
|
190
321
|
}
|
|
322
|
+
if (!job.baseDigest || !job.baseRevision) {
|
|
323
|
+
return {
|
|
324
|
+
code: "MATERIALIZATION_BASE_PROVENANCE_INVALID",
|
|
325
|
+
message: "The materialization job has no immutable canonical base digest and revision",
|
|
326
|
+
retryable: false,
|
|
327
|
+
};
|
|
328
|
+
}
|
|
329
|
+
if (!this.sessions.hasChangeSource()) {
|
|
330
|
+
return {
|
|
331
|
+
code: "MATERIALIZATION_BASE_UNAVAILABLE",
|
|
332
|
+
message: "A canonical session change source is required to verify the staged base before publication",
|
|
333
|
+
retryable: false,
|
|
334
|
+
};
|
|
335
|
+
}
|
|
191
336
|
try {
|
|
192
337
|
const session = await this.sessions.loadForMaterialization(job.sessionId);
|
|
338
|
+
if (session.state() === "possibly_stale" || session.state() === "conflicted"
|
|
339
|
+
|| timelineIrDigest(session.base()) !== job.baseDigest
|
|
340
|
+
|| !sameRevision(session.base().revision, job.baseRevision)) {
|
|
341
|
+
return {
|
|
342
|
+
code: "MATERIALIZATION_BASE_CHANGED",
|
|
343
|
+
message: "The bound canonical base project, sequence, or revision changed after materialization staging",
|
|
344
|
+
retryable: false,
|
|
345
|
+
};
|
|
346
|
+
}
|
|
193
347
|
if (digestSession(session) !== job.sessionDigest) {
|
|
194
348
|
return {
|
|
195
349
|
code: "MATERIALIZATION_SESSION_CHANGED",
|
|
@@ -279,6 +433,15 @@ export class SessionMaterializationJobs {
|
|
|
279
433
|
message: failure.message,
|
|
280
434
|
retryable: failure.retryable,
|
|
281
435
|
},
|
|
436
|
+
verification: {
|
|
437
|
+
tier: failure.verificationTier ?? "artifact",
|
|
438
|
+
status: "failed",
|
|
439
|
+
artifactDigest: job.artifactDigest,
|
|
440
|
+
desiredDigest: job.desiredDigest,
|
|
441
|
+
reason: failure.message,
|
|
442
|
+
...(failure.structuralDiff ? { structuralDiff: failure.structuralDiff } : {}),
|
|
443
|
+
...(failure.delivery ? { delivery: failure.delivery } : {}),
|
|
444
|
+
},
|
|
282
445
|
};
|
|
283
446
|
await this.save(failed);
|
|
284
447
|
return failed;
|
|
@@ -313,11 +476,77 @@ function compileTimelineIrToFcxmlVersioned(desired, target) {
|
|
|
313
476
|
}
|
|
314
477
|
return compileTimelineIrToFcpxml(desired, { target: { ...target, materialization: "versioned" } });
|
|
315
478
|
}
|
|
479
|
+
function normalizePersistedJob(job) {
|
|
480
|
+
if (job.schemaVersion === 2)
|
|
481
|
+
return job;
|
|
482
|
+
if (job.coverage && job.provenance)
|
|
483
|
+
return { ...job, schemaVersion: 2 };
|
|
484
|
+
return {
|
|
485
|
+
...job,
|
|
486
|
+
schemaVersion: 2,
|
|
487
|
+
state: "failed",
|
|
488
|
+
nextAction: "none",
|
|
489
|
+
claim: undefined,
|
|
490
|
+
error: {
|
|
491
|
+
code: "MATERIALIZATION_JOB_METADATA_UNAVAILABLE",
|
|
492
|
+
message: "This persisted materialization job predates target-bound coverage and provenance; execute a new preview before retrying",
|
|
493
|
+
retryable: false,
|
|
494
|
+
},
|
|
495
|
+
};
|
|
496
|
+
}
|
|
316
497
|
function materializationFailure(error, providerRequested) {
|
|
317
498
|
const message = error instanceof Error ? error.message : String(error);
|
|
318
499
|
const code = message.match(/^([A-Z][A-Z0-9_]*):/)?.[1] ?? "MATERIALIZATION_PUBLISH_FAILED";
|
|
319
500
|
return { code, message, retryable: false, providerRequested };
|
|
320
501
|
}
|
|
502
|
+
function verificationTierForBlockedCode(code) {
|
|
503
|
+
return /INTERACTION_REQUIRED|CONSOLE_LOCKED|PROMPT/i.test(code) ? "interaction-required" : "artifact";
|
|
504
|
+
}
|
|
505
|
+
function deliveryEvidenceForBlockedCode(code) {
|
|
506
|
+
if (/INTERACTION_REQUIRED/i.test(code))
|
|
507
|
+
return { state: "interaction-required", route: "headed" };
|
|
508
|
+
if (/PROMPT/i.test(code))
|
|
509
|
+
return { state: "prompted", route: "headed" };
|
|
510
|
+
return { state: "failed", route: "unknown" };
|
|
511
|
+
}
|
|
512
|
+
function createMaterializationStructuralDiff(desired, actual) {
|
|
513
|
+
const changes = [];
|
|
514
|
+
collectStructuralChanges(desired, actual, "", changes);
|
|
515
|
+
return {
|
|
516
|
+
target: { projectId: desired.project.id, sequenceId: desired.sequence.id },
|
|
517
|
+
desiredDigest: timelineIrDigest(desired),
|
|
518
|
+
actualDigest: timelineIrDigest(actual),
|
|
519
|
+
changes,
|
|
520
|
+
};
|
|
521
|
+
}
|
|
522
|
+
function collectStructuralChanges(before, after, path, changes) {
|
|
523
|
+
if (JSON.stringify(before) === JSON.stringify(after))
|
|
524
|
+
return;
|
|
525
|
+
if (Array.isArray(before) && Array.isArray(after)) {
|
|
526
|
+
const length = Math.max(before.length, after.length);
|
|
527
|
+
for (let index = 0; index < length; index += 1) {
|
|
528
|
+
collectStructuralChanges(before[index], after[index], `${path}[${index}]`, changes);
|
|
529
|
+
}
|
|
530
|
+
return;
|
|
531
|
+
}
|
|
532
|
+
if (isRecord(before) && isRecord(after)) {
|
|
533
|
+
const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
|
|
534
|
+
for (const key of keys) {
|
|
535
|
+
collectStructuralChanges(before[key], after[key], path ? `${path}.${key}` : key, changes);
|
|
536
|
+
}
|
|
537
|
+
return;
|
|
538
|
+
}
|
|
539
|
+
changes.push({ path, ...(before !== undefined ? { before } : {}), ...(after !== undefined ? { after } : {}) });
|
|
540
|
+
}
|
|
541
|
+
function isRecord(value) {
|
|
542
|
+
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
543
|
+
}
|
|
544
|
+
function sameRevision(left, right) {
|
|
545
|
+
return right !== undefined
|
|
546
|
+
&& left.id === right.id
|
|
547
|
+
&& left.sequence === right.sequence
|
|
548
|
+
&& left.timestamp === right.timestamp;
|
|
549
|
+
}
|
|
321
550
|
function sameTarget(actual, expected) {
|
|
322
551
|
return actual?.libraryUid === expected.libraryUid
|
|
323
552
|
&& actual.eventUid === expected.eventUid
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export function chooseTimelineReadback(request) {
|
|
2
|
+
if (!request.hasCanonicalBase)
|
|
3
|
+
return { route: "canonical-resync", reason: "no target-bound canonical base is available" };
|
|
4
|
+
if (request.requestedCanonical || request.finalVerification)
|
|
5
|
+
return { route: "canonical-resync", reason: "the caller requires a canonical checkpoint" };
|
|
6
|
+
if (request.sessionState === "possibly_stale" || request.sessionState === "conflicted") {
|
|
7
|
+
return { route: "canonical-resync", reason: "the editing session requires canonical resync" };
|
|
8
|
+
}
|
|
9
|
+
const fast = request.fastObservation;
|
|
10
|
+
if (fast?.available && (!fast.coverageComplete
|
|
11
|
+
|| fast.status === "possibly-stale"
|
|
12
|
+
|| fast.status === "canonical-resync-required"
|
|
13
|
+
|| fast.status === "target-mismatch"
|
|
14
|
+
|| fast.status === "provider-incompatible")) {
|
|
15
|
+
return { route: "canonical-resync", reason: "fast observation is incomplete or stale" };
|
|
16
|
+
}
|
|
17
|
+
if (fast?.available && fast.status === "conflicted")
|
|
18
|
+
return { route: "canonical-resync", reason: "fast observation reported a conflict" };
|
|
19
|
+
if (fast?.available && fast.coverageComplete
|
|
20
|
+
&& (fast.status === "unchanged"
|
|
21
|
+
|| fast.status === "advanced-by-framekit"
|
|
22
|
+
|| fast.status === "proven-structural-delta")) {
|
|
23
|
+
return { route: "fast-observation", reason: "fast observation is complete and reconciled" };
|
|
24
|
+
}
|
|
25
|
+
return { route: "session", reason: "the bound session remains usable without a fresh observation" };
|
|
26
|
+
}
|
|
@@ -1,3 +1,26 @@
|
|
|
1
|
+
export const HEADLESS_TIMELINE_EDIT_TYPES = [
|
|
2
|
+
"insert-occurrence",
|
|
3
|
+
"rename-occurrence",
|
|
4
|
+
"trim-occurrence",
|
|
5
|
+
"move-occurrence",
|
|
6
|
+
"split-occurrence",
|
|
7
|
+
"set-gain",
|
|
8
|
+
"set-transform",
|
|
9
|
+
"remove-occurrence",
|
|
10
|
+
"add-marker",
|
|
11
|
+
"add-title",
|
|
12
|
+
"remove-title",
|
|
13
|
+
"add-transition",
|
|
14
|
+
"remove-transition",
|
|
15
|
+
];
|
|
16
|
+
export const EDITING_ROUTE_EDIT_TYPES = [
|
|
17
|
+
...HEADLESS_TIMELINE_EDIT_TYPES,
|
|
18
|
+
"rename-clip",
|
|
19
|
+
"trim-clip",
|
|
20
|
+
"reduce-noise",
|
|
21
|
+
"set-color-correction",
|
|
22
|
+
"ripple-delete",
|
|
23
|
+
];
|
|
1
24
|
export const EDITOR_FIRST_WORKFLOW = [
|
|
2
25
|
"connection.status",
|
|
3
26
|
"editor.inspect",
|
|
@@ -10,6 +33,14 @@ export const EDITOR_FIRST_WORKFLOW = [
|
|
|
10
33
|
"edit.diff",
|
|
11
34
|
"edit.verify",
|
|
12
35
|
];
|
|
36
|
+
export const HEADLESS_FIRST_WORKFLOW = [
|
|
37
|
+
"connection.status",
|
|
38
|
+
"editing.route",
|
|
39
|
+
"headless.project.open",
|
|
40
|
+
"headless.edit.preview",
|
|
41
|
+
"headless.edit.execute",
|
|
42
|
+
"headless.project.inspect",
|
|
43
|
+
];
|
|
13
44
|
export const BACKGROUND_LIBRARY_WORKFLOW = [
|
|
14
45
|
"connection.status",
|
|
15
46
|
"editor.inspect",
|
|
@@ -38,9 +69,20 @@ export const EDITOR_FIRST_MCP_INSTRUCTIONS = [
|
|
|
38
69
|
"5. Resolve intent when needed, then preview before execute; never mutate on an unavailable capability.",
|
|
39
70
|
"6. Observe the result, then use edit.diff and edit.verify to confirm the change.",
|
|
40
71
|
"Background project and live metadata may use project.list and editor.live.inspect without canonical timeline proof.",
|
|
72
|
+
"For repeated agent readback, use the bound session or complete fast observation; force canonical resync for initial binding, stale/conflicted state, incomplete evidence, explicit canonical inspection, and final verification.",
|
|
41
73
|
"For an explicit FCPXML artifact, select artifact.edit; its background workflow uses artifact.inspect, artifact.edit.preview, artifact.edit.execute, artifact.edit.diff, artifact.edit.verify, and artifact.edit.undo, and never claims to change the open Final Cut timeline.",
|
|
42
74
|
"An external renderer is never an implicit substitute for a connected editor. Select fallback: external-renderer explicitly and report the structured reason returned by editing.route.",
|
|
43
75
|
].join("\n");
|
|
76
|
+
export const HEADLESS_FIRST_MCP_INSTRUCTIONS = [
|
|
77
|
+
"Framekit uses the headless Framekit-owned project as the default editing path.",
|
|
78
|
+
"1. Call connection.status only for diagnostics; Final Cut availability is not required for headless editing.",
|
|
79
|
+
"2. Call editing.route for the intended operation and follow the selected path and reason.",
|
|
80
|
+
"3. For a headless route, use headless.project.open or headless.project.inspect, then preview before execute.",
|
|
81
|
+
"4. Reopen and inspect the exact project revision before rendering; independently verify the render result.",
|
|
82
|
+
"5. Headed/native execution requires an explicit path: headed selection and the native operation tools; it is never an implicit fallback.",
|
|
83
|
+
"An unavailable headless capability returns structured evidence and does not launch or activate Final Cut.",
|
|
84
|
+
"An external renderer is never an implicit substitute. Select fallback: external-renderer explicitly and report the structured reason.",
|
|
85
|
+
].join("\n");
|
|
44
86
|
const operationRequirements = {
|
|
45
87
|
"project.list": [backgroundLibraryRequirement()],
|
|
46
88
|
"project.select": [editorRequirement("projectSelection", "native-ui")],
|
|
@@ -100,11 +142,14 @@ export function resolveEditingRoute(request, context) {
|
|
|
100
142
|
const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
|
|
101
143
|
const editor = context.editor?.identity;
|
|
102
144
|
const readiness = routingReadiness(context);
|
|
103
|
-
const
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
145
|
+
const headlessDefault = request.operation === "timeline.edit" && context.headless && request.path !== "headed";
|
|
146
|
+
const workflow = request.operation === "timeline.edit" && headlessDefault
|
|
147
|
+
? HEADLESS_FIRST_WORKFLOW
|
|
148
|
+
: request.operation === "artifact.edit"
|
|
149
|
+
? BACKGROUND_ARTIFACT_WORKFLOW
|
|
150
|
+
: request.operation === "project.list"
|
|
151
|
+
? BACKGROUND_LIBRARY_WORKFLOW
|
|
152
|
+
: EDITOR_FIRST_WORKFLOW;
|
|
108
153
|
if (request.fallback === "external-renderer") {
|
|
109
154
|
const cause = externalFallbackCause(context, missingCapabilities);
|
|
110
155
|
return {
|
|
@@ -124,6 +169,31 @@ export function resolveEditingRoute(request, context) {
|
|
|
124
169
|
},
|
|
125
170
|
};
|
|
126
171
|
}
|
|
172
|
+
const headlessRequested = request.path === "headless";
|
|
173
|
+
if (headlessRequested || (headlessDefault && request.path !== "headed")) {
|
|
174
|
+
if (context.headless?.available && headlessSupportsRequest(request, context)) {
|
|
175
|
+
return {
|
|
176
|
+
operation: request.operation,
|
|
177
|
+
status: "headless-selected",
|
|
178
|
+
selectedPath: "headless",
|
|
179
|
+
requiredCapabilities: [headlessCapability(request)],
|
|
180
|
+
missingCapabilities: [],
|
|
181
|
+
provider: {
|
|
182
|
+
backend: context.headless.backend,
|
|
183
|
+
guarantee: context.headless.guarantee,
|
|
184
|
+
},
|
|
185
|
+
...(editor ? { editor } : {}),
|
|
186
|
+
...(readiness ? { readiness } : {}),
|
|
187
|
+
workflow: [...HEADLESS_FIRST_WORKFLOW],
|
|
188
|
+
reason: {
|
|
189
|
+
code: "HEADLESS_SELECTED",
|
|
190
|
+
message: "The Framekit-owned headless project is the default SSoT path; Final Cut will not be contacted.",
|
|
191
|
+
connectionState: context.connection.state,
|
|
192
|
+
},
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
return headlessUnavailableRoute(request, context, editor, readiness, workflow);
|
|
196
|
+
}
|
|
127
197
|
const offlineArtifactEdit = (request.operation === "artifact.edit" || request.operation === "timeline.edit")
|
|
128
198
|
&& Boolean(context.editor?.capabilities.editor.timelineArtifactWrite
|
|
129
199
|
&& (context.editor.capabilities.families?.canonicalDocument.artifactWrite.available ?? true));
|
|
@@ -319,6 +389,65 @@ function selectedPath(operation, provider) {
|
|
|
319
389
|
return "native";
|
|
320
390
|
return "editor";
|
|
321
391
|
}
|
|
392
|
+
function headlessUnavailableRoute(request, context, editor, readiness, workflow) {
|
|
393
|
+
const capability = headlessCapability(request);
|
|
394
|
+
return {
|
|
395
|
+
operation: request.operation,
|
|
396
|
+
status: "unavailable",
|
|
397
|
+
selectedPath: "none",
|
|
398
|
+
requiredCapabilities: [capability],
|
|
399
|
+
missingCapabilities: [capability],
|
|
400
|
+
...(editor ? { editor } : {}),
|
|
401
|
+
...(readiness ? { readiness } : {}),
|
|
402
|
+
workflow: [...workflow],
|
|
403
|
+
reason: {
|
|
404
|
+
code: "HEADLESS_UNAVAILABLE",
|
|
405
|
+
message: "The requested Framekit headless SSoT capability is unavailable; no headed or native fallback was selected.",
|
|
406
|
+
connectionState: context.connection.state,
|
|
407
|
+
unavailable: {
|
|
408
|
+
category: "background-api",
|
|
409
|
+
capability,
|
|
410
|
+
backend: context.headless?.backend ?? "framekit-headless-project",
|
|
411
|
+
guarantee: context.headless?.guarantee ?? "none",
|
|
412
|
+
message: context.headless
|
|
413
|
+
? "the configured headless project service does not advertise this operation"
|
|
414
|
+
: "no headless project service is configured",
|
|
415
|
+
},
|
|
416
|
+
},
|
|
417
|
+
};
|
|
418
|
+
}
|
|
419
|
+
function headlessSupportsRequest(request, context) {
|
|
420
|
+
if (!context.headless)
|
|
421
|
+
return false;
|
|
422
|
+
if (request.operation !== "timeline.edit") {
|
|
423
|
+
return context.headless.supportedOperations.includes(request.operation);
|
|
424
|
+
}
|
|
425
|
+
// A bare timeline.edit request is intentionally not a headless capability:
|
|
426
|
+
// the legacy surface also contains operations that Timeline IR cannot apply.
|
|
427
|
+
const editType = canonicalHeadlessEditType(request.editType);
|
|
428
|
+
return editType !== undefined
|
|
429
|
+
&& context.headless.supportedOperations.includes(`timeline.edit:${editType}`);
|
|
430
|
+
}
|
|
431
|
+
function headlessCapability(request) {
|
|
432
|
+
if (request.operation !== "timeline.edit")
|
|
433
|
+
return `headless.${request.operation}`;
|
|
434
|
+
const editType = canonicalHeadlessEditType(request.editType);
|
|
435
|
+
return request.editType
|
|
436
|
+
? `headless.timeline.edit.${editType ?? request.editType}`
|
|
437
|
+
: "headless.timeline.edit";
|
|
438
|
+
}
|
|
439
|
+
function canonicalHeadlessEditType(editType) {
|
|
440
|
+
if (!editType)
|
|
441
|
+
return undefined;
|
|
442
|
+
switch (editType) {
|
|
443
|
+
case "rename-clip": return "rename-occurrence";
|
|
444
|
+
case "trim-clip": return "trim-occurrence";
|
|
445
|
+
default:
|
|
446
|
+
return HEADLESS_TIMELINE_EDIT_TYPES.includes(editType)
|
|
447
|
+
? editType
|
|
448
|
+
: undefined;
|
|
449
|
+
}
|
|
450
|
+
}
|
|
322
451
|
function selectedMessage(operation) {
|
|
323
452
|
if (operation === "project.list" || operation === "editor.live.inspect") {
|
|
324
453
|
return "The background observation provider satisfies the requested metadata fields; no canonical timeline proof is implied.";
|