@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
@@ -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: 1,
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 || job.jobId !== jobId)
89
+ if (job.jobId !== jobId || (job.schemaVersion !== 1 && job.schemaVersion !== 2)) {
77
90
  throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
78
- return structuredClone(job);
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 workflow = request.operation === "artifact.edit"
104
- ? BACKGROUND_ARTIFACT_WORKFLOW
105
- : request.operation === "project.list"
106
- ? BACKGROUND_LIBRARY_WORKFLOW
107
- : EDITOR_FIRST_WORKFLOW;
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.";