@morshoto/framekit 0.1.18 → 0.2.3

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 (192) hide show
  1. package/README.md +17 -12
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  4. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  6. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  7. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  11. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  12. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  13. package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
  14. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  15. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  16. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  17. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  18. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  19. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  20. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  21. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  22. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  23. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  24. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  25. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
  26. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  27. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  28. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  29. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  30. package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
  31. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  32. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  33. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  34. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  35. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  36. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  37. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  38. package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
  39. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  40. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  41. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
  42. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  43. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  44. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  45. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  46. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  47. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  48. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  49. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  50. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  51. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  52. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
  53. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  54. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  55. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  56. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  57. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  58. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  59. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
  60. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  61. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  62. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  63. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  64. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  65. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  66. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  67. package/dist-package/apps/cli/src/main.d.ts +10 -0
  68. package/dist-package/apps/cli/src/main.js +42 -0
  69. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  70. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  71. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
  72. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  73. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  74. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  75. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  76. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  77. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  78. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  79. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  80. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  81. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  82. package/dist-package/apps/mcp-server/src/main.js +24 -19
  83. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  84. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  85. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  86. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  87. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  88. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  89. package/dist-package/apps/mcp-server/src/server.js +813 -158
  90. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  91. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  92. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  93. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  94. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  95. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  96. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  97. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  98. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  99. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  100. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
  101. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  102. package/dist-package/packages/headless-application/src/index.js +2 -0
  103. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  104. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  105. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  106. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  107. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  108. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  109. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  110. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  111. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  112. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  113. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  114. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  115. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  116. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  118. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  119. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  120. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  121. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  122. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  123. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  124. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  125. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  126. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  127. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  128. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  129. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  130. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  131. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  132. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  133. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  134. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  135. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  136. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  137. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  138. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  139. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  140. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  141. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  142. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  143. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  144. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  145. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  146. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  147. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  148. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  149. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  150. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  151. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  152. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  153. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  154. package/dist-package/packages/runtime/src/index.js +2 -0
  155. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  156. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  157. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  158. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  159. package/dist-package/packages/runtime/src/runtime.js +16 -7
  160. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  161. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  162. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  163. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  164. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  165. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  166. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  167. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  168. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  169. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  170. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  171. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  172. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  173. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  174. package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
  175. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  176. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  177. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  178. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  179. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  180. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  181. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  182. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  183. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  184. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  185. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  186. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  187. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  188. package/dist-package/packages/testkit/src/index.js +1 -0
  189. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  190. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  191. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  192. package/package.json +41 -14
@@ -1,6 +1,7 @@
1
1
  import { execFile as execFileCallback } from "node:child_process";
2
- import { chmodSync, constants, createReadStream, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
3
- import { access, lstat, mkdtemp, open, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
2
+ import { AsyncLocalStorage } from "node:async_hooks";
3
+ import { chmodSync, closeSync, constants, createReadStream, fsyncSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
4
+ import { access, lstat, mkdir, mkdtemp, open, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
4
5
  import { createHash, randomUUID } from "node:crypto";
5
6
  import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
6
7
  import { tmpdir } from "node:os";
@@ -19,8 +20,10 @@ export function parseFinalCutProjectPublishRoute(value, backgroundDeliveryAvaila
19
20
  }
20
21
  /** Imports a validated FCPXML artifact as a new Final Cut project. */
21
22
  export class FinalCutProjectPublisher {
23
+ dispatchContext = new AsyncLocalStorage();
22
24
  enabled;
23
25
  sourcePath;
26
+ publishJobDirectory;
24
27
  executor;
25
28
  liveState;
26
29
  targetBinding;
@@ -36,6 +39,7 @@ export class FinalCutProjectPublisher {
36
39
  constructor(options) {
37
40
  this.enabled = options.enabled ?? false;
38
41
  this.sourcePath = options.sourcePath;
42
+ this.publishJobDirectory = options.publishJobDirectory;
39
43
  this.executor = options.executor ?? runAppleScript;
40
44
  this.liveState = options.liveState;
41
45
  this.targetBinding = options.targetBinding;
@@ -48,6 +52,9 @@ export class FinalCutProjectPublisher {
48
52
  this.pollIntervalMs = Math.max(0, options.pollIntervalMs ?? options.waitMs ?? 100);
49
53
  this.loadPersistedPublishJobs();
50
54
  }
55
+ async trackNativeDispatch(operation, onDispatch) {
56
+ return this.dispatchContext.run(onDispatch, operation);
57
+ }
51
58
  isAvailable() {
52
59
  return this.inspectReadiness().available;
53
60
  }
@@ -123,10 +130,67 @@ export class FinalCutProjectPublisher {
123
130
  throw new Error(`PUBLISH_JOB_NOT_FOUND: unknown publish job ${jobId}`);
124
131
  return clonePublishJob(job);
125
132
  }
126
- async executePublishJob(jobId, confirm) {
127
- const storedJob = this.publishJobs.get(jobId);
128
- if (!storedJob)
133
+ async loadPublishJob(jobId) {
134
+ const current = this.publishJobs.get(jobId);
135
+ if (current)
136
+ return clonePublishJob(current);
137
+ if (!this.publishJobDirectory) {
129
138
  throw new Error(`PUBLISH_JOB_NOT_FOUND: unknown publish job ${jobId}`);
139
+ }
140
+ let persisted;
141
+ try {
142
+ persisted = JSON.parse(await readFile(this.publishJobPath(jobId), "utf8"));
143
+ }
144
+ catch (error) {
145
+ if (error.code === "ENOENT") {
146
+ throw new Error(`PUBLISH_JOB_NOT_FOUND: unknown publish job ${jobId}`);
147
+ }
148
+ throw new Error(`PUBLISH_JOB_STATE_INVALID: could not read verified publish job ${jobId}`);
149
+ }
150
+ if (!isVerifiedPublishJob(persisted, jobId)) {
151
+ throw new Error(`PUBLISH_JOB_STATE_INVALID: verified publish job ${jobId} has incomplete target proof`);
152
+ }
153
+ const job = clonePublishJob(persisted);
154
+ this.publishJobs.set(jobId, job);
155
+ return clonePublishJob(job);
156
+ }
157
+ /** Revalidate a persisted native target against the live catalog and active project. */
158
+ async verifyCreatedTarget(jobId) {
159
+ const job = await this.loadPublishJob(jobId);
160
+ const createdTarget = job.result?.createdTarget;
161
+ if (job.state !== "verified" || !job.result?.verified || !createdTarget) {
162
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_UNVERIFIED: publish job ${jobId} has no verified native target`);
163
+ }
164
+ const libraryPath = job.targetLibraryPath ?? createdTarget.libraryPath;
165
+ if (!libraryPath || !createdTarget.libraryId || !createdTarget.eventId || !this.targetBinding) {
166
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_REBIND_UNAVAILABLE: publish job ${jobId} has no live library binding provider`);
167
+ }
168
+ if (!this.liveState) {
169
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_REBIND_UNAVAILABLE: publish job ${jobId} has no live active-target provider`);
170
+ }
171
+ const observed = await this.targetBinding(libraryPath, {
172
+ projectName: createdTarget.projectName,
173
+ sequenceName: createdTarget.sequenceName ?? job.sequenceName,
174
+ });
175
+ if (observed.projectId !== createdTarget.projectId
176
+ || observed.sequenceId !== createdTarget.sequenceId
177
+ || observed.libraryId !== createdTarget.libraryId
178
+ || observed.eventId !== createdTarget.eventId
179
+ || !observed.libraryPath
180
+ || normalizeLibraryPath(libraryPath) !== normalizeLibraryPath(observed.libraryPath)) {
181
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_REBIND_MISMATCH: catalog target ${observed.libraryId}/${observed.eventId}/${observed.projectId}/${observed.sequenceId} does not match persisted ${createdTarget.libraryId}/${createdTarget.eventId}/${createdTarget.projectId}/${createdTarget.sequenceId}`);
182
+ }
183
+ const live = await readLiveState(this.liveState, "after publisher restart");
184
+ if (live.project?.id !== createdTarget.projectId
185
+ || live.project?.name !== createdTarget.projectName
186
+ || live.sequence?.id !== createdTarget.sequenceId
187
+ || live.sequence?.name !== createdTarget.sequenceName) {
188
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_REBIND_MISMATCH: active target ${live.project?.id ?? "<unavailable>"}/${live.sequence?.id ?? "<unavailable>"} does not match persisted ${createdTarget.projectId}/${createdTarget.sequenceId}`);
189
+ }
190
+ return structuredClone(createdTarget);
191
+ }
192
+ async executePublishJob(jobId, confirm, confirmVerification = false) {
193
+ const storedJob = this.publishJobs.get(jobId) ?? await this.loadPublishJob(jobId);
130
194
  const job = clonePublishJob(storedJob);
131
195
  if (job.state === "verified")
132
196
  return clonePublishJob(job);
@@ -134,6 +198,27 @@ export class FinalCutProjectPublisher {
134
198
  return clonePublishJob(job);
135
199
  if (!confirm)
136
200
  throw new Error("PUBLISH_CONFIRMATION_REQUIRED: set confirm=true to create a new Final Cut project");
201
+ // Once a dispatch may have occurred, unavailable providers must never
202
+ // transition the job back to a state that can dispatch again.
203
+ if (job.state === "verification-pending") {
204
+ if (!confirmVerification) {
205
+ job.nextAction = "confirm-verification";
206
+ job.retryable = false;
207
+ this.persistPublishJob(job);
208
+ return clonePublishJob(job);
209
+ }
210
+ if (!this.enabled || !this.liveState || !this.targetBinding || !this.readCanonicalSnapshot) {
211
+ job.nextAction = "retry";
212
+ job.retryable = true;
213
+ job.error = {
214
+ code: "FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE",
215
+ message: "Verification is unavailable; retain this job and resume verification without dispatching again",
216
+ };
217
+ this.persistPublishJob(job);
218
+ return clonePublishJob(job);
219
+ }
220
+ return this.resumePublishVerification(job);
221
+ }
137
222
  if (!this.enabled) {
138
223
  job.state = "awaiting-final-cut";
139
224
  job.nextAction = "retry";
@@ -150,8 +235,6 @@ export class FinalCutProjectPublisher {
150
235
  if (!this.readCanonicalSnapshot) {
151
236
  return this.markFailed(job, new Error("FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE: headed canonical timeline readback is not configured; no import was attempted"));
152
237
  }
153
- if (job.state === "verification-pending")
154
- return this.resumePublishVerification(job);
155
238
  let validated;
156
239
  try {
157
240
  validated = await this.readValidatedSource({
@@ -206,6 +289,14 @@ export class FinalCutProjectPublisher {
206
289
  ...(job.targetLibraryPath ? { targetLibraryPath: job.targetLibraryPath } : {}),
207
290
  confirm: true,
208
291
  }, validated.source, validated.identity, beforeLive, runtime, job);
292
+ if (!result) {
293
+ job.state = "verification-pending";
294
+ job.nextAction = "confirm-verification";
295
+ job.retryable = false;
296
+ delete job.error;
297
+ this.persistPublishJob(job);
298
+ return clonePublishJob(job);
299
+ }
209
300
  return this.markVerified(job, result);
210
301
  }
211
302
  catch (error) {
@@ -219,6 +310,7 @@ export class FinalCutProjectPublisher {
219
310
  job.state = "verification-pending";
220
311
  job.nextAction = "retry";
221
312
  job.retryable = true;
313
+ job.dispatchError = structuredClone(normalized);
222
314
  job.error = normalized;
223
315
  this.persistPublishJob(job);
224
316
  return clonePublishJob(job);
@@ -229,6 +321,8 @@ export class FinalCutProjectPublisher {
229
321
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing is disabled; configure FRAMEKIT_EDITOR=final-cut-live and FRAMEKIT_FCPXML_PATH, and ensure Final Cut is reachable through FRAMEKIT_FINAL_CUT_SOCKET");
230
322
  if (!request.confirm)
231
323
  throw new Error("PUBLISH_CONFIRMATION_REQUIRED: set confirm=true to create a new Final Cut project");
324
+ if (!request.confirmVerification)
325
+ throw new Error("PUBLISH_VERIFICATION_CONFIRMATION_REQUIRED: separately confirm headed semantic readback before direct publish");
232
326
  if (request.sourceTransactionId.startsWith("headless-rough-cut:")) {
233
327
  throw new Error("HEADLESS_ROUGH_CUT_PUBLISH_JOB_REQUIRED: use artifact.publish.preview and artifact.publish.execute to preserve the approved target binding");
234
328
  }
@@ -250,7 +344,10 @@ export class FinalCutProjectPublisher {
250
344
  ...(targetLibraryPath ? { targetLibraryPath } : {}),
251
345
  };
252
346
  try {
253
- return await this.importAndVerify({ ...request, ...(targetLibraryPath ? { targetLibraryPath } : {}) }, source, identity, beforeLive, runtime);
347
+ const result = await this.importAndVerify({ ...request, ...(targetLibraryPath ? { targetLibraryPath } : {}) }, source, identity, beforeLive, runtime);
348
+ if (!result)
349
+ throw new Error("FINAL_CUT_PUBLISH_VERIFICATION_PENDING: separate verification is required");
350
+ return result;
254
351
  }
255
352
  catch (error) {
256
353
  if (!runtime.importAttempted)
@@ -263,13 +360,16 @@ export class FinalCutProjectPublisher {
263
360
  retryable: true,
264
361
  executionMode: "headed-only",
265
362
  sourceTransactionId: request.sourceTransactionId,
266
- sourcePath: this.sourcePath,
267
- sourceTarget: { kind: "artifact", artifactPath: this.sourcePath },
363
+ sourcePath: this.sourcePath ?? request.artifactPath,
364
+ sourceTarget: { kind: "artifact", artifactPath: this.sourcePath ?? request.artifactPath },
268
365
  artifactDigest: request.artifactDigest,
269
366
  ...(targetLibraryPath ? { targetLibraryPath } : {}),
270
367
  projectName: identity.projectName,
271
368
  sequenceName: identity.sequenceName,
272
369
  confirmationRequired: false,
370
+ ...(runtime.delivery ? { delivery: structuredClone(runtime.delivery) } : {}),
371
+ ...(!runtime.delivery ? { dispatchError: structuredClone(normalized) } : {}),
372
+ ...(runtime.observedTarget ? { observedTarget: structuredClone(runtime.observedTarget) } : {}),
273
373
  handoff: {
274
374
  mode: "headed-only",
275
375
  route: this.publishRoute,
@@ -299,6 +399,9 @@ export class FinalCutProjectPublisher {
299
399
  }
300
400
  validateApprovedSourceMediaDigests(sourceProof.sourceMediaDigests);
301
401
  }
402
+ else if (!this.sourcePath) {
403
+ throw new Error("PUBLISH_SOURCE_UNAVAILABLE: a managed FCPXML path is required for non-headless publishing");
404
+ }
302
405
  else if (request.artifactPath !== this.sourcePath) {
303
406
  throw new Error(`PUBLISH_TARGET_MISMATCH: requested artifact ${request.artifactPath} is not managed by this publisher`);
304
407
  }
@@ -349,6 +452,7 @@ export class FinalCutProjectPublisher {
349
452
  if (runtime)
350
453
  runtime.importedDigest = importedDigest;
351
454
  let delivery;
455
+ let completed = false;
352
456
  try {
353
457
  await writeFile(importedPath, importedSource, "utf8");
354
458
  await validateTargetLibraryPath(targetLibraryPath, Boolean(this.documentDelivery));
@@ -404,15 +508,22 @@ export class FinalCutProjectPublisher {
404
508
  }
405
509
  if (runtime)
406
510
  runtime.delivery = delivery;
511
+ if (publishJob)
512
+ publishJob.delivery = structuredClone(delivery);
407
513
  this.persistRuntimeForJob(publishJob, runtime);
514
+ if (publishJob)
515
+ return undefined;
408
516
  const verifiedTarget = await waitForImportedProject(this.liveState, async (targetPath, targetIdentity) => {
409
517
  return this.targetBinding(targetPath, targetIdentity);
410
518
  }, targetLibraryPath, identity, beforeLive, this.verificationTimeoutMs, this.pollIntervalMs);
519
+ if (runtime)
520
+ runtime.observedTarget = structuredClone(verifiedTarget.targetBinding);
411
521
  await assertSourceMediaUnchanged(sourceMediaDigests);
412
522
  const semanticReadback = await this.readAndVerifyCanonicalTarget(expectedSnapshot, sourceMediaDigests, verifiedTarget.targetBinding, identity);
413
523
  const result = publishResult(request, importedPath, importedDigest, identity, beforeLive, verifiedTarget.live, verifiedTarget.targetBinding, delivery, semanticReadback, sourceMediaDigests);
414
524
  if (runtime)
415
525
  await releaseTargetLibraryReservation(runtime);
526
+ completed = true;
416
527
  return result;
417
528
  }
418
529
  catch (error) {
@@ -423,7 +534,8 @@ export class FinalCutProjectPublisher {
423
534
  throw error;
424
535
  }
425
536
  finally {
426
- await rm(directory, { recursive: true, force: true });
537
+ if (completed || !runtime?.importAttempted)
538
+ await rm(directory, { recursive: true, force: true });
427
539
  }
428
540
  }
429
541
  async resumePublishVerification(job) {
@@ -439,6 +551,8 @@ export class FinalCutProjectPublisher {
439
551
  }
440
552
  try {
441
553
  const verifiedTarget = await waitForImportedProject(this.liveState, (targetPath, identity) => this.targetBinding(targetPath, identity), runtime.targetLibraryPath, runtime.identity, runtime.beforeLive, this.verificationTimeoutMs, this.pollIntervalMs);
554
+ job.observedTarget = structuredClone(verifiedTarget.targetBinding);
555
+ this.persistPublishJob(job);
442
556
  await assertSourceMediaUnchanged(runtime.sourceMediaDigests);
443
557
  const semanticReadback = await this.readAndVerifyCanonicalTarget(runtime.expectedSnapshot, runtime.sourceMediaDigests, verifiedTarget.targetBinding, runtime.identity);
444
558
  const result = publishResult({
@@ -449,6 +563,7 @@ export class FinalCutProjectPublisher {
449
563
  confirm: true,
450
564
  }, runtime.importedPath ?? job.sourcePath, runtime.importedDigest ?? job.artifactDigest, runtime.identity, runtime.beforeLive, verifiedTarget.live, verifiedTarget.targetBinding, runtime.delivery, semanticReadback, runtime.sourceMediaDigests);
451
565
  await releaseTargetLibraryReservation(runtime);
566
+ await removeCompletedImportArtifact(runtime);
452
567
  return this.markVerified(job, result);
453
568
  }
454
569
  catch (error) {
@@ -460,16 +575,54 @@ export class FinalCutProjectPublisher {
460
575
  return clonePublishJob(job);
461
576
  }
462
577
  }
463
- markVerified(job, result) {
578
+ async markVerified(job, result) {
464
579
  job.state = "verified";
465
580
  job.nextAction = "none";
466
581
  job.retryable = false;
467
582
  job.createdTarget = structuredClone(result.createdTarget);
468
583
  job.result = structuredClone(result);
469
584
  delete job.error;
470
- this.persistPublishJob(job);
585
+ try {
586
+ await this.persistVerifiedPublishJob(job);
587
+ this.persistPublishJob(job);
588
+ }
589
+ catch (error) {
590
+ job.state = "verification-pending";
591
+ job.nextAction = "retry";
592
+ job.retryable = true;
593
+ delete job.createdTarget;
594
+ delete job.result;
595
+ job.error = {
596
+ code: "FINAL_CUT_PUBLISH_JOB_PERSISTENCE_FAILED",
597
+ message: error instanceof Error ? error.message : String(error),
598
+ };
599
+ }
600
+ this.publishJobs.set(job.jobId, job);
471
601
  return clonePublishJob(job);
472
602
  }
603
+ async persistVerifiedPublishJob(job) {
604
+ if (!this.publishJobDirectory)
605
+ return;
606
+ const path = this.publishJobPath(job.jobId);
607
+ const temporaryPath = `${path}.${randomUUID()}.tmp`;
608
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 });
609
+ try {
610
+ await writeFile(temporaryPath, `${JSON.stringify(job)}\n`, {
611
+ encoding: "utf8",
612
+ flag: "wx",
613
+ mode: 0o600,
614
+ });
615
+ await rename(temporaryPath, path);
616
+ }
617
+ catch (error) {
618
+ await rm(temporaryPath, { force: true }).catch(() => undefined);
619
+ throw error;
620
+ }
621
+ }
622
+ publishJobPath(jobId) {
623
+ const key = createHash("sha256").update(jobId).digest("hex");
624
+ return join(this.publishJobDirectory, `${key}.json`);
625
+ }
473
626
  async readAndVerifyCanonicalTarget(expected, expectedMediaDigests, targetBinding, identity) {
474
627
  if (!this.liveState || !this.readCanonicalSnapshot) {
475
628
  throw new Error("FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE: headed canonical timeline readback is not configured");
@@ -519,6 +672,23 @@ export class FinalCutProjectPublisher {
519
672
  if (!name.endsWith(".json"))
520
673
  continue;
521
674
  const path = join(this.publishJobsDirectory, name);
675
+ if (/^[a-f0-9]{64}\.json$/i.test(name)) {
676
+ let legacyJob;
677
+ try {
678
+ legacyJob = JSON.parse(readFileSync(path, "utf8"));
679
+ }
680
+ catch (error) {
681
+ throw new Error(`PUBLISH_JOB_STORE_INVALID: could not read ${path}`, { cause: error });
682
+ }
683
+ const jobId = legacyJob && typeof legacyJob === "object"
684
+ ? legacyJob.jobId
685
+ : undefined;
686
+ if (typeof jobId !== "string" || !isVerifiedPublishJob(legacyJob, jobId)
687
+ || name !== `${createHash("sha256").update(jobId).digest("hex")}.json`) {
688
+ throw new Error(`PUBLISH_JOB_STORE_INVALID: invalid legacy verified publish job ${path}`);
689
+ }
690
+ continue;
691
+ }
522
692
  let persisted;
523
693
  try {
524
694
  persisted = JSON.parse(readFileSync(path, "utf8"));
@@ -542,10 +712,18 @@ export class FinalCutProjectPublisher {
542
712
  if (job.state === "verification-pending" && !persisted.runtime) {
543
713
  throw new Error(`PUBLISH_JOB_STORE_INVALID: pending job is missing recovery state ${path}`);
544
714
  }
715
+ if (persisted.runtime?.importAttempted === true && job.state !== "verification-pending" && job.state !== "verified") {
716
+ throw new Error(`PUBLISH_JOB_STORE_INVALID: spent import has a re-dispatchable state ${path}`);
717
+ }
718
+ if (job.state === "verified" && !isVerifiedPublishJob(job, job.jobId)) {
719
+ throw new Error(`PUBLISH_JOB_STORE_INVALID: verified job is missing consistent native target proof ${path}`);
720
+ }
545
721
  job.handoff.route ??= "background-document-open";
546
722
  if (job.handoff.route !== "background-document-open" && job.handoff.route !== "headed-apple-event") {
547
723
  throw new Error(`PUBLISH_JOB_STORE_INVALID: invalid publish route in ${path}`);
548
724
  }
725
+ if (!job.delivery && persisted.runtime?.delivery)
726
+ job.delivery = structuredClone(persisted.runtime.delivery);
549
727
  this.publishJobs.set(job.jobId, job);
550
728
  if (persisted.runtime)
551
729
  this.publishJobRuntime.set(job.jobId, persisted.runtime);
@@ -567,6 +745,8 @@ export class FinalCutProjectPublisher {
567
745
  runtime.importAttempted = false;
568
746
  throw error;
569
747
  }
748
+ this.dispatchContext.getStore()?.();
749
+ markReservationDispatchAttempt(runtime);
570
750
  }
571
751
  persistPublishJob(job) {
572
752
  if (!this.publishJobsDirectory) {
@@ -730,6 +910,7 @@ async function reserveTargetLibraryPath(targetLibraryPath) {
730
910
  const reservationContents = JSON.stringify({
731
911
  reservationId,
732
912
  targetLibraryPath: canonicalTarget,
913
+ phase: "reserved",
733
914
  pid: process.pid,
734
915
  createdAt: new Date().toISOString(),
735
916
  });
@@ -807,7 +988,8 @@ async function reclaimAbandonedTargetLibraryReservation(reservationPath, request
807
988
  catch {
808
989
  return false;
809
990
  }
810
- if (typeof reservation.reservationId !== "string" || !reservation.reservationId
991
+ if (reservation.phase !== "reserved"
992
+ || typeof reservation.reservationId !== "string" || !reservation.reservationId
811
993
  || typeof reservation.targetLibraryPath !== "string"
812
994
  || resolve(reservation.targetLibraryPath) !== requestedTarget
813
995
  || !Number.isSafeInteger(reservation.pid) || reservation.pid <= 0
@@ -857,6 +1039,30 @@ function processIsRunning(pid) {
857
1039
  return error?.code !== "ESRCH";
858
1040
  }
859
1041
  }
1042
+ function markReservationDispatchAttempt(runtime) {
1043
+ if (!runtime.reservationPath || !runtime.reservationId)
1044
+ return;
1045
+ const fd = openSync(runtime.reservationPath, constants.O_RDWR | constants.O_NOFOLLOW);
1046
+ try {
1047
+ const reservation = JSON.parse(readFileSync(fd, "utf8"));
1048
+ if (reservation.reservationId !== runtime.reservationId || reservation.phase !== "reserved") {
1049
+ throw new Error("PUBLISH_TARGET_LIBRARY_RESERVED: reservation changed before dispatch");
1050
+ }
1051
+ const content = Buffer.from(JSON.stringify({ ...reservation, phase: "dispatch-attempted" }));
1052
+ ftruncateSync(fd, 0);
1053
+ let written = 0;
1054
+ while (written < content.length) {
1055
+ const count = writeSync(fd, content, written, content.length - written, written);
1056
+ if (count <= 0)
1057
+ throw new Error("PUBLISH_TARGET_RESERVATION_WRITE_FAILED: unable to persist dispatch marker");
1058
+ written += count;
1059
+ }
1060
+ fsyncSync(fd);
1061
+ }
1062
+ finally {
1063
+ closeSync(fd);
1064
+ }
1065
+ }
860
1066
  async function releaseTargetLibraryReservation(runtime) {
861
1067
  if (!runtime.reservationPath || !runtime.reservationId)
862
1068
  return;
@@ -875,6 +1081,14 @@ async function releaseTargetLibraryReservation(runtime) {
875
1081
  delete runtime.reservationPath;
876
1082
  delete runtime.reservationId;
877
1083
  }
1084
+ async function removeCompletedImportArtifact(runtime) {
1085
+ if (!runtime.importedPath)
1086
+ return;
1087
+ const directory = dirname(resolve(runtime.importedPath));
1088
+ if (dirname(directory) !== resolve(tmpdir()) || !basename(directory).startsWith("framekit-finalcut-publish-"))
1089
+ return;
1090
+ await rm(directory, { recursive: true, force: true }).catch(() => { });
1091
+ }
878
1092
  async function validateTargetLibraryPath(path, required) {
879
1093
  if (!path?.trim()) {
880
1094
  if (required)
@@ -969,6 +1183,33 @@ function normalizeLibraryPath(path) {
969
1183
  function clonePublishJob(job) {
970
1184
  return structuredClone(job);
971
1185
  }
1186
+ function isVerifiedPublishJob(value, jobId) {
1187
+ if (!value || typeof value !== "object")
1188
+ return false;
1189
+ const job = value;
1190
+ return job.jobId === jobId
1191
+ && job.state === "verified"
1192
+ && job.result?.verified === true
1193
+ && sameNativeTargetIdentity(job.createdTarget, job.result.createdTarget);
1194
+ }
1195
+ function sameNativeTargetIdentity(left, right) {
1196
+ if (!hasStableNativeTargetIds(left) || !hasStableNativeTargetIds(right))
1197
+ return false;
1198
+ return left.kind === right.kind
1199
+ && left.projectId === right.projectId
1200
+ && left.sequenceId === right.sequenceId
1201
+ && left.libraryId === right.libraryId
1202
+ && left.eventId === right.eventId;
1203
+ }
1204
+ function hasStableNativeTargetIds(value) {
1205
+ return value?.kind === "editor.project"
1206
+ && typeof value.projectId === "string"
1207
+ && value.projectId.trim().length > 0
1208
+ && typeof value.sequenceId === "string"
1209
+ && value.sequenceId.trim().length > 0
1210
+ && (value.libraryId === undefined || (typeof value.libraryId === "string" && value.libraryId.trim().length > 0))
1211
+ && (value.eventId === undefined || (typeof value.eventId === "string" && value.eventId.trim().length > 0));
1212
+ }
972
1213
  function publishResult(request, importedPath, importedDigest, identity, beforeLive, live, targetBinding, delivery, semanticReadback, sourceMediaDigests = []) {
973
1214
  return {
974
1215
  sourceTransactionId: request.sourceTransactionId,
@@ -0,0 +1,43 @@
1
+ import type { ContextRevision, CapabilityInspectionOptions, EditOperation, EditorAsset, EditorIdentity, EditorPort, EditorLiveState, EditorChange, AssetSearchQuery, MediaContext, MediaSearchQuery, LiveEditorStatePort, ProjectSnapshot, ProjectCatalog, ProjectSelection, ProjectSelectionResult, RuntimeCapabilities, ManagedArtifact, WorkflowOperation } from "../../../../packages/runtime/src/index.js";
2
+ interface FinalCutSessionOptions {
3
+ snapshot?: EditorPort;
4
+ mutation?: EditorPort;
5
+ live?: LiveEditorStatePort & Partial<Pick<EditorPort, "readProject" | "apply" | "restore" | "previewTransaction" | "applyTransaction" | "withCanonicalReadScope">> & {
6
+ getIdentity(): Promise<EditorIdentity>;
7
+ getCapabilities(options?: CapabilityInspectionOptions): Promise<RuntimeCapabilities>;
8
+ listProjects?(): Promise<ProjectCatalog>;
9
+ selectProject?(selection: ProjectSelection): Promise<ProjectSelectionResult>;
10
+ };
11
+ assets?: Pick<EditorPort, "listAssets">;
12
+ media?: Pick<EditorPort, "listMedia">;
13
+ backgroundCatalog?: {
14
+ listProjects(): Promise<ProjectCatalog>;
15
+ backend?: string;
16
+ };
17
+ }
18
+ /** Composes the independent Final Cut live, snapshot, and mutation surfaces. */
19
+ export declare class FinalCutSessionAdapter implements EditorPort, LiveEditorStatePort {
20
+ private readonly options;
21
+ constructor(options: FinalCutSessionOptions);
22
+ withCanonicalReadScope<T>(operation: () => Promise<T>): Promise<T>;
23
+ getIdentity(): Promise<EditorIdentity>;
24
+ getManagedArtifact(): Promise<ManagedArtifact>;
25
+ getManagedArtifactDigest(): Promise<string | undefined>;
26
+ getCapabilities(options?: CapabilityInspectionOptions): Promise<RuntimeCapabilities>;
27
+ previewTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<ProjectSnapshot>;
28
+ applyTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<void>;
29
+ read(): Promise<ProjectSnapshot>;
30
+ readProject(): Promise<ProjectSnapshot>;
31
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
32
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
33
+ listAssets(query?: AssetSearchQuery): Promise<EditorAsset[]>;
34
+ listMedia(query?: MediaSearchQuery): Promise<MediaContext[]>;
35
+ listProjects(): Promise<ProjectCatalog>;
36
+ private readBackgroundCatalog;
37
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
38
+ readLiveState(): Promise<EditorLiveState>;
39
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
40
+ private pureLiveProvider;
41
+ private routedTransactionProvider;
42
+ }
43
+ export {};
@@ -5,6 +5,10 @@ export class FinalCutSessionAdapter {
5
5
  constructor(options) {
6
6
  this.options = options;
7
7
  }
8
+ withCanonicalReadScope(operation) {
9
+ const provider = this.options.snapshot ?? this.options.live;
10
+ return provider?.withCanonicalReadScope?.(operation) ?? operation();
11
+ }
8
12
  async getIdentity() {
9
13
  if (this.options.snapshot && this.options.live) {
10
14
  try {
@@ -67,6 +71,7 @@ export class FinalCutSessionAdapter {
67
71
  ? live
68
72
  : snapshot;
69
73
  const operationCapabilities = operationRuntimeCapabilities?.editor;
74
+ const projectSelectionCapabilities = snapshot?.editor.projectSelection ? snapshot.editor : live?.editor;
70
75
  const operationAdapter = hasExplicitDocumentPair
71
76
  ? this.options.mutation
72
77
  : liveMutation
@@ -104,6 +109,18 @@ export class FinalCutSessionAdapter {
104
109
  guarantee: "observed",
105
110
  }
106
111
  : false;
112
+ const snapshotSelection = Boolean(snapshot?.editor.projectSelection
113
+ && this.options.snapshot?.selectProject
114
+ && projectSelectionMode(snapshot.editor) !== "unavailable");
115
+ const liveSelection = Boolean(!this.options.snapshot
116
+ && live?.editor.projectSelection
117
+ && this.options.live?.selectProject
118
+ && projectSelectionMode(live.editor) !== "unavailable");
119
+ const projectSelection = snapshotSelection || liveSelection;
120
+ const selectionCapabilities = this.options.snapshot ? snapshot?.editor : live?.editor;
121
+ const selectionMode = projectSelection && selectionCapabilities
122
+ ? projectSelectionMode(selectionCapabilities)
123
+ : "unavailable";
107
124
  return withCapabilityFamilies({
108
125
  editor: {
109
126
  ...operationCapabilities,
@@ -125,7 +142,8 @@ export class FinalCutSessionAdapter {
125
142
  projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead
126
143
  || (!this.options.snapshot && live?.editor.projectCatalogRead)
127
144
  || this.options.backgroundCatalog),
128
- projectSelection: Boolean(snapshot?.editor.projectSelection || (!this.options.snapshot && live?.editor.projectSelection)),
145
+ projectSelection,
146
+ projectSelectionMode: selectionMode,
129
147
  compositeTransactions,
130
148
  },
131
149
  analyzers: {
@@ -181,14 +199,16 @@ export class FinalCutSessionAdapter {
181
199
  async readProject() {
182
200
  if (this.options.snapshot)
183
201
  return this.options.snapshot.readProject();
184
- const liveCapabilities = await optionalCapabilities(this.options.live);
185
- if (liveCapabilities?.editor.canonicalTimelineMode !== "metadata-only"
186
- && !this.options.mutation
187
- && liveCapabilities?.editor.timelineSnapshotRead
188
- && this.options.live?.readProject) {
189
- return this.options.live.readProject();
190
- }
191
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut session has no snapshot provider");
202
+ return this.withCanonicalReadScope(async () => {
203
+ const liveCapabilities = await optionalCapabilities(this.options.live);
204
+ if (liveCapabilities?.editor.canonicalTimelineMode !== "metadata-only"
205
+ && !this.options.mutation
206
+ && liveCapabilities?.editor.timelineSnapshotRead
207
+ && this.options.live?.readProject) {
208
+ return this.options.live.readProject();
209
+ }
210
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut session has no snapshot provider");
211
+ });
192
212
  }
193
213
  async apply(operation, expectedRevision) {
194
214
  if (this.options.snapshot && this.options.mutation) {
@@ -299,6 +319,14 @@ export class FinalCutSessionAdapter {
299
319
  validateProjectCatalog(catalog);
300
320
  const after = await optionalLiveState(this.options.live);
301
321
  const identity = before && after ? await optionalIdentity(this.options.live) : undefined;
322
+ const selectionProvider = this.options.snapshot ?? this.options.live;
323
+ const selectionCapabilities = await optionalCapabilities(selectionProvider, { probeCanonicalSnapshot: false });
324
+ const selectionMode = selectionCapabilities
325
+ ? projectSelectionMode(selectionCapabilities.editor)
326
+ : "unavailable";
327
+ const selectionAvailable = Boolean(selectionProvider?.selectProject
328
+ && selectionCapabilities?.editor.projectSelection
329
+ && selectionMode !== "unavailable");
302
330
  return reconcileProjectCatalog(catalog, {
303
331
  ...(before && after ? { before, after } : {}),
304
332
  provenance: {
@@ -315,9 +343,11 @@ export class FinalCutSessionAdapter {
315
343
  },
316
344
  } : {}),
317
345
  selection: {
318
- available: false,
319
- mode: "unavailable",
320
- unavailableReason: "project selection is not exposed by the background provider",
346
+ available: selectionAvailable,
347
+ mode: selectionAvailable ? selectionMode : "unavailable",
348
+ ...(!selectionAvailable ? {
349
+ unavailableReason: "project selection is not exposed by the background provider",
350
+ } : {}),
321
351
  },
322
352
  },
323
353
  });
@@ -391,7 +421,7 @@ async function optionalIdentity(live) {
391
421
  }
392
422
  async function optionalProjectSelectionCapability(live) {
393
423
  try {
394
- return Boolean((await live?.getCapabilities())?.editor.projectSelection);
424
+ return Boolean((await live?.getCapabilities({ probeCanonicalSnapshot: false }))?.editor.projectSelection);
395
425
  }
396
426
  catch {
397
427
  return false;