@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,16 +1,40 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
- import { resolve as resolvePath } from "node:path";
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
5
+ import { types as utilTypes } from "node:util";
6
+ import { isAbsolute, resolve as resolvePath } from "node:path";
4
7
  import { z } from "zod/v3";
5
- import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
6
- import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
8
+ import { canonicalSnapshotDigest, createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
9
+ import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, NativeFinalCutMediaImportError, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, nativeMediaSearchQueryError, FinalCutProjectPublisher, FinalCutNativeAutomationAdapter, disabledNativeFocusContext, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
10
  import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
11
  import { assessBuildAlignment } from "./build-alignment.js";
9
12
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
10
13
  import { EditingSessionRepository } from "./headless-sessions.js";
11
14
  import { SessionMaterializationJobs, } from "./materialization-jobs.js";
15
+ import { externalEditOperations, externalEditPlanDigest, verifyExternalEditExportable, } from "../../../packages/headless-application/src/index.js";
12
16
  import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
13
17
  import { chooseTimelineReadback } from "./readback-policy.js";
18
+ import { registerSkillTools, skillPreviewResult } from "./tools/skills/register.js";
19
+ const builtInPublishExecute = FinalCutProjectPublisher.prototype.executePublishJob;
20
+ const builtInPublishGetJob = FinalCutProjectPublisher.prototype.getPublishJob;
21
+ const builtInPublishTrack = FinalCutProjectPublisher.prototype.trackNativeDispatch;
22
+ const builtInPublishPersist = Reflect.get(FinalCutProjectPublisher.prototype, "persistPublishJob");
23
+ const builtInNativeMethods = new Map(Reflect.ownKeys(FinalCutNativeAutomationAdapter.prototype)
24
+ .map((key) => [key, Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value]));
25
+ const builtInMapGet = Map.prototype.get;
26
+ const builtInMapSet = Map.prototype.set;
27
+ const builtInMapHas = Map.prototype.has;
28
+ // Target identities are opaque: reject blank values without rewriting the
29
+ // caller's approval before the adapter compares it with the observed target.
30
+ const nativeImportTargetIdentity = z.string().min(1).refine((value) => value.trim().length > 0);
31
+ const nativeImportTargetSchema = z.object({
32
+ libraryId: nativeImportTargetIdentity,
33
+ eventId: nativeImportTargetIdentity,
34
+ projectId: nativeImportTargetIdentity,
35
+ sequenceId: nativeImportTargetIdentity,
36
+ revision: nativeImportTargetIdentity,
37
+ });
14
38
  const revisionValueSchema = z.object({
15
39
  id: z.string(),
16
40
  sequence: z.number().int().nonnegative(),
@@ -25,6 +49,8 @@ const timelineReadbackSchema = z.object({
25
49
  sessionId: z.string().min(1).optional(),
26
50
  requestedCanonical: z.boolean().optional().default(false),
27
51
  finalVerification: z.boolean().optional().default(false),
52
+ confirmHeadedRead: z.boolean().optional(),
53
+ expectedTarget: contextTargetSchema.optional(),
28
54
  }).strict();
29
55
  const contextCursorSchema = z.object({
30
56
  revision: revisionValueSchema,
@@ -55,6 +81,8 @@ const mediaIndexQuerySchema = z.object({
55
81
  const timelineSemanticContextQuerySchema = z.object({
56
82
  query: z.string().optional(),
57
83
  occurrenceIds: z.array(z.string().min(1)).optional(),
84
+ confirmHeadedRead: z.boolean().optional(),
85
+ expectedTarget: contextTargetSchema.optional(),
58
86
  }).strict();
59
87
  const roughCutPlanSchema = mediaIndexQuerySchema.extend({
60
88
  maxShots: z.number().int().positive().optional(),
@@ -149,7 +177,14 @@ const colorCorrectionSchema = z.object({
149
177
  }),
150
178
  baseRevision: revisionSchema,
151
179
  });
152
- const rippleDeleteSchema = z.object({ type: z.literal("ripple-delete"), timelineId: z.string().min(1), range: rangeSchema, reason: z.string().optional(), baseRevision: revisionSchema });
180
+ const rippleDeleteSchema = z.object({
181
+ type: z.literal("ripple-delete"),
182
+ timelineId: z.string().min(1),
183
+ // The editor validates this range against the active timeline and reports its actual bounds.
184
+ range: z.object({ start: z.number().finite(), end: z.number().finite() }),
185
+ reason: z.string().optional(),
186
+ baseRevision: revisionSchema,
187
+ });
153
188
  const addMarkerSchema = z.object({ type: z.literal("add-marker"), timelineId: z.string().min(1), marker: markerSchema, baseRevision: revisionSchema });
154
189
  const roughCutImportSchema = z.object({
155
190
  type: z.literal("media.import"),
@@ -325,6 +360,7 @@ const artifactPublishInputSchema = z.object({
325
360
  targetLibraryPath: z.string().trim().min(1),
326
361
  transactionId: z.string().min(1),
327
362
  confirm: z.boolean(),
363
+ confirmVerification: z.boolean().optional(),
328
364
  }).strict();
329
365
  const artifactTransactionInputSchema = z.object({
330
366
  artifactPath: z.string().trim().min(1),
@@ -760,32 +796,6 @@ function isDirectoryMediaImportError(error) {
760
796
  && typeof guidance.previewTool === "string"
761
797
  && typeof guidance.executeTool === "string";
762
798
  }
763
- function skillErrorResult(error) {
764
- const value = error && typeof error === "object" ? error : {};
765
- const message = error instanceof Error ? error.message : String(error);
766
- const code = error instanceof z.ZodError
767
- ? "SKILL_INPUT_INVALID"
768
- : typeof value.code === "string" ? value.code : message.split(":", 1)[0] || "SKILL_ERROR";
769
- return {
770
- isError: true,
771
- content: [{
772
- type: "text",
773
- text: JSON.stringify({
774
- code,
775
- message,
776
- ...(value.availability ? { availability: value.availability } : {}),
777
- }),
778
- }],
779
- };
780
- }
781
- function skillPreviewResult(preview) {
782
- const details = preview.plan.details ?? {};
783
- return jsonResult({
784
- ...preview,
785
- ...details,
786
- plan: { ...preview.plan, ...details },
787
- });
788
- }
789
799
  function normalizeConnectionStatus(value) {
790
800
  if (!value || typeof value !== "object")
791
801
  return value;
@@ -839,6 +849,9 @@ function frameResult(value) {
839
849
  };
840
850
  }
841
851
  export function createMcpServer(runtime, options = {}) {
852
+ // Inspect only inert descriptors before wrapping. Unknown providers remain
853
+ // guarded rather than being executed to determine whether dispatch is safe.
854
+ const builtinImportUnavailable = isBuiltinImportObservationUnavailable(options.nativeEditor);
842
855
  runtime.registerBuiltinSkills();
843
856
  if (options.requireBuildAlignment) {
844
857
  const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
@@ -855,7 +868,7 @@ export function createMcpServer(runtime, options = {}) {
855
868
  : {}),
856
869
  ...(options.projectPublisher
857
870
  ? {
858
- projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob"]),
871
+ projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob", "loadPublishJob"]),
859
872
  }
860
873
  : {}),
861
874
  ...(options.videoExporter
@@ -863,13 +876,51 @@ export function createMcpServer(runtime, options = {}) {
863
876
  : {}),
864
877
  };
865
878
  }
879
+ const publishRouteIsGuarded = Boolean(options.canonicalRecovery && options.projectPublisher);
880
+ if (options.canonicalRecovery) {
881
+ const recovery = options.canonicalRecovery;
882
+ options = {
883
+ ...options,
884
+ ...(options.nativeEditor
885
+ ? { nativeEditor: withRecoveryCheckpointGuard(options.nativeEditor, recovery, ["capabilities", "inspect"], [
886
+ "edit", "undo", "executeBlade", "executeMask", "executeTitleAdd", "executeTransitionAdd",
887
+ "executeAppendMedia", "executeAppendSelectedMedia", "executeInsertMedia", "executeDeleteRange",
888
+ "executeTrimToDuration", "executePictureInPicture", "importMedia", "executeImportMediaDirectory",
889
+ "focusTimeline", "selectMedia", "selectOccurrence", "selectCanonicalOccurrence", "targetMedia",
890
+ "searchMedia", "searchMediaForCanonicalTarget", "searchTitles", "searchTransitions", "locateOccurrence", "locateOccurrenceForCanonicalTarget",
891
+ "previewBlade", "previewMask", "previewDeleteRange", "previewTrimToDuration", "previewAppendMedia",
892
+ "previewAppendSelectedMedia", "previewInsertMedia", "previewTitleAdd", "previewPictureInPicture", "previewTransitionAdd",
893
+ ]) }
894
+ : {}),
895
+ ...(options.disposableNative
896
+ ? { disposableNative: withRecoveryCheckpointGuard(options.disposableNative, recovery, [], ["preview", "execute", "undo"], "disposable") }
897
+ : {}),
898
+ ...(options.nativeOperationSession
899
+ ? { nativeOperationSession: withRecoveryCheckpointGuard(options.nativeOperationSession, recovery, ["status", "cancel"]) }
900
+ : {}),
901
+ ...(options.projectPublisher
902
+ ? { projectPublisher: withPublishRecoveryGuard(options.projectPublisher, recovery, async (publisher, property) => {
903
+ if (property === "executePublishJob") {
904
+ if (publisher.isAvailable() && requiresHeadedPublishingRoute(publisher))
905
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
906
+ }
907
+ else {
908
+ if (!publisher.isAvailable())
909
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
910
+ if (requiresHeadedPublishingRoute(publisher))
911
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
912
+ }
913
+ }) }
914
+ : {}),
915
+ };
916
+ }
866
917
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
867
918
  const nativeTransitionAssets = new Map();
868
919
  const sessions = options.sessionDirectory
869
920
  ? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
870
921
  : undefined;
871
922
  const materializations = sessions && options.materializationDirectory
872
- ? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
923
+ ? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher, options.canonicalRecovery)
873
924
  : undefined;
874
925
  const requireSessions = () => {
875
926
  if (!sessions)
@@ -982,7 +1033,11 @@ export function createMcpServer(runtime, options = {}) {
982
1033
  server.registerTool("session.materialize.execute", {
983
1034
  description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
984
1035
  inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
985
- }, async ({ sessionId, target, confirm }) => sessionResult(async () => requireMaterializations().execute(sessionId, target, confirm)));
1036
+ }, async ({ sessionId, target, confirm }) => sessionResult(async () => {
1037
+ if (options.sessionMaterializationPublisher)
1038
+ await options.canonicalRecovery?.assertClear();
1039
+ return requireMaterializations().execute(sessionId, target, confirm);
1040
+ }));
986
1041
  server.registerTool("session.materialize.status", {
987
1042
  description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
988
1043
  inputSchema: { jobId: z.string().min(1) },
@@ -990,7 +1045,11 @@ export function createMcpServer(runtime, options = {}) {
990
1045
  server.registerTool("session.materialize.retry", {
991
1046
  description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
992
1047
  inputSchema: { jobId: z.string().min(1) },
993
- }, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
1048
+ }, async ({ jobId }) => sessionResult(async () => {
1049
+ if (options.sessionMaterializationPublisher)
1050
+ await options.canonicalRecovery?.assertClear();
1051
+ return requireMaterializations().retry(jobId);
1052
+ }));
994
1053
  server.registerTool("session.materialize.resync", {
995
1054
  description: "Read the completed versioned handoff target and create a fresh editing-session baseline for continuation.",
996
1055
  inputSchema: { jobId: z.string().min(1), sessionId: z.string().min(1) },
@@ -1003,71 +1062,107 @@ export function createMcpServer(runtime, options = {}) {
1003
1062
  description: "Read native Final Cut handoff readiness without launching, activating, importing, or mutating Final Cut.",
1004
1063
  inputSchema: { publishJobId: z.string().trim().min(1).optional() },
1005
1064
  }, async ({ publishJobId }) => jsonResult(await inspectNativeHandoffReadiness(runtime, options, publishJobId)));
1006
- server.registerTool("skill.list", {
1007
- description: "List registered versioned Framekit Skills with current capability availability.",
1065
+ server.registerTool("editor.native.recovery.evidence.inspect", {
1066
+ description: "Read point-in-time native reservation and sender evidence without changing state or proving receiver quiescence. Recovery eligibility is unavailable.",
1008
1067
  inputSchema: {},
1009
- }, async () => {
1010
- try {
1011
- return jsonResult((await runtime.listSkillAvailability()).map(({ manifest, availability }) => ({
1012
- ...manifest,
1013
- availability,
1014
- })));
1015
- }
1016
- catch (error) {
1017
- return skillErrorResult(error);
1018
- }
1019
- });
1020
- server.registerTool("skill.inspect", {
1021
- description: "Inspect one registered Framekit Skill version and its current capability availability.",
1022
- inputSchema: { skill: z.string().min(1), version: z.string().min(1).optional() },
1023
- }, async ({ skill, version }) => {
1068
+ }, async () => sessionResult(async () => {
1069
+ if (!options.canonicalRecovery?.inspectNativeRecoveryEvidence)
1070
+ throw new Error("CAPABILITY_UNAVAILABLE: native recovery evidence inspection is not configured");
1071
+ return options.canonicalRecovery.inspectNativeRecoveryEvidence();
1072
+ }));
1073
+ server.registerTool("editor.native.recovery.inspect", {
1074
+ description: "Inspect recovery checkpoint evidence in the configured state directory without contacting Final Cut or clearing the checkpoint.",
1075
+ inputSchema: {},
1076
+ }, async () => sessionResult(async () => {
1077
+ if (!options.canonicalRecovery)
1078
+ throw new Error("CAPABILITY_UNAVAILABLE: canonical recovery checkpoint inspection is not configured");
1079
+ let evidence;
1024
1080
  try {
1025
- const { manifest, availability } = await runtime.inspectSkillAvailability(skill, version);
1026
- return jsonResult({ ...manifest, availability });
1081
+ evidence = await options.canonicalRecovery.inspectVersioned();
1027
1082
  }
1028
1083
  catch (error) {
1029
- return skillErrorResult(error);
1084
+ const nativeReservation = await options.canonicalRecovery.inspectNativeReservation();
1085
+ if (!nativeReservation)
1086
+ throw error;
1087
+ return { status: "recovery-required", scope: "configured-state-directory", nativeReservation };
1030
1088
  }
1031
- });
1032
- server.registerTool("skill.preview", {
1033
- description: "Validate and preview a registered Skill without mutating the editor.",
1089
+ return evidence
1090
+ ? { status: "recovery-required", scope: "configured-state-directory", ...evidence }
1091
+ : { status: "clear", scope: "configured-state-directory" };
1092
+ }));
1093
+ server.registerTool("editor.native.recovery.preview", {
1094
+ description: "Compare a separately authorized headed canonical read with one target-bound checkpoint. Confirmation alone does not establish authorization. Never clears the checkpoint or proves native operation quiescence.",
1034
1095
  inputSchema: {
1035
- skill: z.string().min(1),
1036
- version: z.string().min(1).optional(),
1037
- arguments: z.record(z.unknown()),
1096
+ confirmHeadedRead: z.boolean().optional(),
1097
+ expectedTarget: contextTargetSchema.optional(),
1098
+ expectedCheckpointId: z.string().regex(/^[a-f0-9]{64}$/).optional(),
1038
1099
  },
1039
- }, async ({ skill, version, arguments: skillArguments }) => {
1100
+ }, async ({ confirmHeadedRead, expectedTarget, expectedCheckpointId }) => {
1101
+ const operation = "editor.native.recovery.preview";
1102
+ if (!confirmHeadedRead || !expectedTarget || !expectedCheckpointId) {
1103
+ return mcpReadErrorResult("HEADED_READ_CONFIRMATION_REQUIRED", "recovery preview requires confirmation, target IDs, and the inspected checkpoint ID", operation);
1104
+ }
1105
+ if (!options.canonicalRecovery)
1106
+ return mcpReadErrorResult("CAPABILITY_UNAVAILABLE", "canonical recovery checkpoint inspection is not configured", operation);
1107
+ let evidence;
1040
1108
  try {
1041
- const baseRevision = revisionValueSchema.parse(skillArguments.baseRevision);
1042
- const { baseRevision: _baseRevision, ...input } = skillArguments;
1043
- return skillPreviewResult(await runtime.previewSkill({
1044
- skillId: skill,
1045
- ...(version ? { version } : {}),
1046
- baseRevision,
1047
- input,
1048
- }));
1109
+ evidence = await options.canonicalRecovery.inspectVersioned();
1049
1110
  }
1050
1111
  catch (error) {
1051
- return skillErrorResult(error);
1112
+ return mcpReadErrorResult("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", error instanceof Error ? error.message : String(error), operation);
1113
+ }
1114
+ if (!evidence || evidence.checkpointId !== expectedCheckpointId)
1115
+ return mcpReadErrorResult("CHECKPOINT_MISMATCH", "recovery checkpoint is missing or changed", operation);
1116
+ if (evidence.checkpoint.projectId !== expectedTarget.projectId || evidence.checkpoint.sequenceId !== expectedTarget.sequenceId) {
1117
+ return mcpReadErrorResult("TARGET_MISMATCH", "requested target differs from the checkpoint", operation);
1118
+ }
1119
+ const passive = await inspectMcpEditor(runtime, options);
1120
+ if (passive.identity.backend !== "final-cut-native-canonical") {
1121
+ return mcpReadErrorResult("CAPABILITY_UNAVAILABLE", "recovery preview requires the canonical native provider", operation);
1052
1122
  }
1053
- });
1054
- server.registerTool("skill.execute", {
1055
- description: "Execute only a runtime-issued Skill preview token and return verification/rollback evidence.",
1056
- inputSchema: {
1057
- previewToken: z.string().min(1),
1058
- },
1059
- }, async ({ previewToken }) => {
1060
1123
  try {
1061
- return jsonResult(await runtime.executeSkill(previewToken));
1124
+ return await inspectCanonicalReadForMcp(runtime, options, operation, true, expectedTarget, async () => {
1125
+ const beforeLive = await runtime.inspectLiveEditor();
1126
+ if (!liveTargetMatches(beforeLive, expectedTarget) || !beforeLive.revision?.id || !Number.isSafeInteger(beforeLive.revision.sequence)) {
1127
+ throw new Error("STALE_CONTEXT: live target or revision is unavailable before recovery read");
1128
+ }
1129
+ const snapshot = await runtime.inspectProject();
1130
+ const afterLive = await runtime.inspectLiveEditor();
1131
+ if (!liveTargetMatches(afterLive, expectedTarget) || afterLive.revision?.id !== beforeLive.revision.id
1132
+ || afterLive.revision?.sequence !== beforeLive.revision.sequence) {
1133
+ throw new Error("STALE_CONTEXT: live target or revision changed during recovery read");
1134
+ }
1135
+ if (snapshot.projectId !== expectedTarget.projectId || snapshot.timeline.id !== expectedTarget.sequenceId) {
1136
+ throw new Error("TARGET_MISMATCH: canonical snapshot differs from the checkpoint target");
1137
+ }
1138
+ const after = await options.canonicalRecovery.inspectVersioned();
1139
+ if (!after || after.checkpointId !== expectedCheckpointId)
1140
+ throw new Error("CHECKPOINT_MISMATCH: checkpoint changed during canonical read");
1141
+ const observedDigest = canonicalSnapshotDigest(snapshot);
1142
+ const comparison = evidence.checkpoint.expectedRestoreDigest === observedDigest
1143
+ ? "matches-expected-restoration"
1144
+ : evidence.checkpoint.beforeDigest === observedDigest ? "matches-before" : "different";
1145
+ return { checkpointId: expectedCheckpointId, target: expectedTarget, observedRevision: snapshot.revision, observedLiveRevision: afterLive.revision, observedDigest, comparison, pointInTime: true, quiescence: "unproven", checkpointCleared: false };
1146
+ }, (result) => result.target);
1062
1147
  }
1063
1148
  catch (error) {
1064
- return skillErrorResult(error);
1149
+ const message = error instanceof Error ? error.message : String(error);
1150
+ if (message.startsWith("STALE_CONTEXT:"))
1151
+ return mcpReadErrorResult("STALE_CONTEXT", message, operation);
1152
+ if (message.startsWith("TARGET_MISMATCH:"))
1153
+ return mcpReadErrorResult("TARGET_MISMATCH", message, operation);
1154
+ if (message.startsWith("CHECKPOINT_MISMATCH:"))
1155
+ return mcpReadErrorResult("CHECKPOINT_MISMATCH", message, operation);
1156
+ if (message.startsWith("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED:"))
1157
+ return mcpReadErrorResult("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message, operation);
1158
+ throw error;
1065
1159
  }
1066
1160
  });
1161
+ registerSkillTools(server, runtime);
1067
1162
  server.registerTool("project.inspect", {
1068
1163
  description: "Read a bound session baseline or perform an explicit canonical project resync before editing.route selects a capability-checked path.",
1069
1164
  inputSchema: timelineReadbackSchema,
1070
- }, async ({ sessionId, requestedCanonical, finalVerification }) => {
1165
+ }, async ({ sessionId, requestedCanonical, finalVerification, confirmHeadedRead, expectedTarget }) => {
1071
1166
  if (sessionId) {
1072
1167
  const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1073
1168
  if (decision.route === "session" || decision.route === "fast-observation") {
@@ -1078,20 +1173,9 @@ export function createMcpServer(runtime, options = {}) {
1078
1173
  snapshot: stored.document.base,
1079
1174
  });
1080
1175
  }
1081
- const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1082
- return jsonResult({ sessionId, readback: decision, ...resynced });
1083
- }
1084
- const inspected = await inspectMcpEditor(runtime, options);
1085
- const capability = inspected.capabilities.families.canonicalDocument.read;
1086
- if (!capability.available) {
1087
- return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
1088
- }
1089
- try {
1090
- return jsonResult(await runtime.inspectProject());
1091
- }
1092
- catch (error) {
1093
- return capabilityUnavailableErrorResult(error);
1176
+ return inspectCanonicalReadForMcp(runtime, options, "project.inspect", confirmHeadedRead, expectedTarget, async () => ({ sessionId, readback: decision, ...await canonicalResyncSession(sessionId, stored.document.provider?.id) }), (result) => ({ projectId: result.snapshot.projectId, sequenceId: result.snapshot.timeline.id }));
1094
1177
  }
1178
+ return inspectCanonicalReadForMcp(runtime, options, "project.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectProject(), (result) => ({ projectId: result.projectId, sequenceId: result.timeline.id }));
1095
1179
  });
1096
1180
  server.registerTool("artifact.inspect", {
1097
1181
  description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
@@ -1153,6 +1237,49 @@ export function createMcpServer(runtime, options = {}) {
1153
1237
  expectedRevision: revisionValueSchema.optional(),
1154
1238
  },
1155
1239
  }, async ({ projectId, sourcePath, expectedRevision }) => sessionResult(() => requireHeadlessProjects().registerMedia(projectId, sourcePath, expectedRevision)));
1240
+ server.registerTool("headless.media.search", {
1241
+ description: "Search one Framekit-owned project's registered media by ID, name, or source path without contacting Final Cut.",
1242
+ inputSchema: { projectId: z.string().min(1), query: z.string() },
1243
+ }, async ({ projectId, query }) => sessionResult(() => requireHeadlessProjects().searchMedia(projectId, query)));
1244
+ const externalEditSchema = z.object({
1245
+ schemaVersion: z.literal(1),
1246
+ clips: z.array(z.object({
1247
+ id: z.string().min(1), mediaId: z.string().min(1),
1248
+ sourceStartTime: rationalTimeSchema, durationTime: rationalTimeSchema,
1249
+ }).strict()).min(1),
1250
+ title: z.object({
1251
+ id: z.string().min(1), text: z.string().min(1),
1252
+ startTime: rationalTimeSchema, durationTime: rationalTimeSchema,
1253
+ }).strict(),
1254
+ music: z.object({
1255
+ id: z.string().min(1), mediaId: z.string().min(1), sourceStartTime: rationalTimeSchema,
1256
+ startTime: rationalTimeSchema, durationTime: rationalTimeSchema, gainDb: z.number().finite(),
1257
+ }).strict(),
1258
+ }).strict();
1259
+ server.registerTool("headless.edit-json.preview", {
1260
+ description: "Preview a versioned external edit against a Framekit project without mutation.",
1261
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema },
1262
+ }, async ({ projectId, sequenceId, expectedRevision, edit }) => sessionResult(async () => {
1263
+ const service = requireHeadlessProjects();
1264
+ const project = await service.inspect(projectId);
1265
+ const operations = externalEditOperations(edit, project.timeline, expectedRevision);
1266
+ const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1267
+ verifyExternalEditExportable(preview.after.timeline);
1268
+ return { ...preview, planDigest: externalEditPlanDigest(preview.command) };
1269
+ }));
1270
+ server.registerTool("headless.edit-json.execute", {
1271
+ description: "Execute a versioned external edit against a Framekit project revision.",
1272
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema, approved: z.literal(true), planDigest: z.string().regex(/^[a-f0-9]{64}$/) },
1273
+ }, async ({ projectId, sequenceId, expectedRevision, edit, planDigest }) => sessionResult(async () => {
1274
+ const service = requireHeadlessProjects();
1275
+ const project = await service.inspect(projectId);
1276
+ const operations = externalEditOperations(edit, project.timeline, expectedRevision);
1277
+ const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1278
+ verifyExternalEditExportable(preview.after.timeline);
1279
+ if (externalEditPlanDigest(preview.command) !== planDigest)
1280
+ throw new Error("EXTERNAL_EDIT_STALE_PREVIEW: approved edit does not match preview");
1281
+ return service.executeEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1282
+ }));
1156
1283
  server.registerTool("headless.edit.preview", {
1157
1284
  description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
1158
1285
  inputSchema: {
@@ -1179,6 +1306,10 @@ export function createMcpServer(runtime, options = {}) {
1179
1306
  expectedRevision,
1180
1307
  operations: operations,
1181
1308
  }, sequenceId)));
1309
+ server.registerTool("headless.edit.undo", {
1310
+ description: "Restore the prior Framekit-owned timeline at the expected revision and independently verify the persisted result.",
1311
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), undoId: z.string().min(1), expectedRevision: revisionValueSchema },
1312
+ }, async ({ projectId, sequenceId, undoId, expectedRevision }) => sessionResult(() => requireHeadlessProjects().undoEdit(projectId, sequenceId, undoId, expectedRevision)));
1182
1313
  const headlessRenderParametersSchema = z.object({
1183
1314
  outputPath: z.string().min(1),
1184
1315
  format: z.enum(["mp4", "mov"]),
@@ -1236,6 +1367,10 @@ export function createMcpServer(runtime, options = {}) {
1236
1367
  eventName: z.string().min(1).optional(),
1237
1368
  materialization: z.enum(["versioned", "reuse-existing"]).optional(),
1238
1369
  }).strict();
1370
+ server.registerTool("headless.fcpxml.export", {
1371
+ description: "Compile an exact Framekit-owned project revision to a new FCPXML artifact without contacting Final Cut.",
1372
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, outputPath: z.string().min(1), target: headlessFcpxmlTargetSchema },
1373
+ }, async ({ projectId, sequenceId, expectedRevision, outputPath, target }) => sessionResult(() => requireHeadlessProjects().exportFcpxml(projectId, sequenceId, expectedRevision, outputPath, target)));
1239
1374
  const headlessRoughCutRequestSchema = z.object({
1240
1375
  projectId: z.string().min(1),
1241
1376
  sequenceId: z.string().min(1),
@@ -1348,12 +1483,16 @@ export function createMcpServer(runtime, options = {}) {
1348
1483
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
1349
1484
  server.registerTool("editor.native.media.import", {
1350
1485
  description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
1351
- inputSchema: { path: z.string().min(1) },
1352
- }, async ({ path }, extra) => {
1486
+ inputSchema: { path: z.string().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1487
+ }, async ({ path, expectedImportTarget }, extra) => {
1353
1488
  if (!options.nativeEditor)
1354
1489
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1490
+ if (builtinImportUnavailable) {
1491
+ await options.canonicalRecovery?.assertClear();
1492
+ return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
1493
+ }
1355
1494
  try {
1356
- return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
1495
+ return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1357
1496
  }
1358
1497
  catch (error) {
1359
1498
  return nativeMediaImportErrorResult(error);
@@ -1361,11 +1500,11 @@ export function createMcpServer(runtime, options = {}) {
1361
1500
  });
1362
1501
  server.registerTool("editor.native.media.directory.preview", {
1363
1502
  description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
1364
- inputSchema: { path: z.string().trim().min(1) },
1365
- }, async ({ path }, extra) => {
1503
+ inputSchema: { path: z.string().trim().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1504
+ }, async ({ path, expectedImportTarget }, extra) => {
1366
1505
  if (!options.nativeEditor)
1367
1506
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1368
- return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
1507
+ return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1369
1508
  });
1370
1509
  server.registerTool("editor.native.media.directory.execute", {
1371
1510
  description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
@@ -1373,6 +1512,10 @@ export function createMcpServer(runtime, options = {}) {
1373
1512
  }, async ({ previewToken, confirm }, extra) => {
1374
1513
  if (!options.nativeEditor)
1375
1514
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1515
+ if (builtinImportUnavailable) {
1516
+ await options.canonicalRecovery?.assertClear();
1517
+ return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
1518
+ }
1376
1519
  return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
1377
1520
  });
1378
1521
  server.registerTool("editor.native.edit", {
@@ -1535,11 +1678,18 @@ export function createMcpServer(runtime, options = {}) {
1535
1678
  return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
1536
1679
  });
1537
1680
  server.registerTool("editor.native.media.search", {
1538
- description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
1681
+ description: "Search the active Final Cut Browser by literal text and return short-lived media handles; wildcard operators are unsupported.",
1539
1682
  inputSchema: { query: z.string().min(1) },
1540
1683
  }, async ({ query }, extra) => {
1541
1684
  if (!options.nativeEditor)
1542
1685
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
1686
+ const queryError = nativeMediaSearchQueryError(query);
1687
+ if (queryError) {
1688
+ return {
1689
+ isError: true,
1690
+ content: [{ type: "text", text: JSON.stringify(queryError) }],
1691
+ };
1692
+ }
1543
1693
  return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
1544
1694
  });
1545
1695
  server.registerTool("editor.native.media.select", {
@@ -1707,18 +1857,19 @@ export function createMcpServer(runtime, options = {}) {
1707
1857
  return jsonResult({ ...job, ...(sourceProof ? { sourceProof } : {}) });
1708
1858
  });
1709
1859
  server.registerTool("artifact.publish.execute", {
1710
- description: "Execute an experimental native handoff after explicit confirmation; dispatch alone is not project-creation proof, and success requires target readback.",
1860
+ description: "Dispatch a prepared native handoff with confirm=true; for a pending job separately authorize headed readback with confirmVerification=true. Dispatch does not prove project creation.",
1711
1861
  inputSchema: {
1712
1862
  jobId: z.string().trim().min(1),
1713
1863
  confirm: z.literal(true),
1864
+ confirmVerification: z.boolean().optional(),
1714
1865
  },
1715
- }, async ({ jobId, confirm }) => {
1866
+ }, async ({ jobId, confirm, confirmVerification }) => {
1716
1867
  if (!options.projectPublisher)
1717
1868
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1718
- if (options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
1869
+ if (!publishRouteIsGuarded && options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
1719
1870
  await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1720
1871
  }
1721
- return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
1872
+ return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm, confirmVerification));
1722
1873
  });
1723
1874
  server.registerTool("artifact.publish.status", {
1724
1875
  description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
@@ -1726,16 +1877,19 @@ export function createMcpServer(runtime, options = {}) {
1726
1877
  }, async ({ jobId }) => {
1727
1878
  if (!options.projectPublisher)
1728
1879
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1729
- return jsonResult(options.projectPublisher.getPublishJob(jobId));
1880
+ return jsonResult(await options.projectPublisher.loadPublishJob(jobId));
1730
1881
  });
1731
1882
  server.registerTool("artifact.publish", {
1732
- description: "Experimental, opt-in native import of validated FCPXML. Dispatch alone does not prove project creation; success requires matching created-target readback and explicit confirmation.",
1883
+ description: "Experimental direct import; explicitly confirm both creation and headed readback for this artifact. Dispatch alone does not prove project creation.",
1733
1884
  inputSchema: artifactPublishInputSchema,
1734
- }, async ({ artifactPath, targetLibraryPath, transactionId, confirm }) => {
1735
- if (!options.projectPublisher?.isAvailable())
1885
+ }, async ({ artifactPath, targetLibraryPath, transactionId, confirm, confirmVerification }) => {
1886
+ if (!options.projectPublisher)
1736
1887
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1737
- if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1738
- await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1888
+ if (!publishRouteIsGuarded) {
1889
+ if (!options.projectPublisher.isAvailable())
1890
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1891
+ if (requiresHeadedPublishingRoute(options.projectPublisher))
1892
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1739
1893
  }
1740
1894
  const transaction = runtime.getTransaction(transactionId);
1741
1895
  if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
@@ -1753,20 +1907,25 @@ export function createMcpServer(runtime, options = {}) {
1753
1907
  artifactDigest: transaction.artifactDigest,
1754
1908
  targetLibraryPath,
1755
1909
  confirm,
1910
+ confirmVerification,
1756
1911
  }));
1757
1912
  });
1758
1913
  server.registerTool("timeline.publish.new-project", {
1759
- description: "Experimental, opt-in native import of a verified artifact transaction; reports verified delivery only after matching created-target readback and explicit confirmation.",
1914
+ description: "Experimental direct import of a verified artifact; explicitly confirm creation and headed readback before verified delivery.",
1760
1915
  inputSchema: {
1761
1916
  transactionId: z.string().min(1),
1762
1917
  targetLibraryPath: z.string().trim().min(1),
1763
1918
  confirm: z.literal(true),
1919
+ confirmVerification: z.boolean().optional(),
1764
1920
  },
1765
- }, async ({ transactionId, targetLibraryPath, confirm }) => {
1766
- if (!options.projectPublisher?.isAvailable())
1921
+ }, async ({ transactionId, targetLibraryPath, confirm, confirmVerification }) => {
1922
+ if (!options.projectPublisher)
1767
1923
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1768
- if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1769
- await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1924
+ if (!publishRouteIsGuarded) {
1925
+ if (!options.projectPublisher.isAvailable())
1926
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1927
+ if (requiresHeadedPublishingRoute(options.projectPublisher))
1928
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1770
1929
  }
1771
1930
  const transaction = runtime.getTransaction(transactionId);
1772
1931
  if (transaction.target?.kind !== "artifact") {
@@ -1784,6 +1943,7 @@ export function createMcpServer(runtime, options = {}) {
1784
1943
  artifactDigest: transaction.artifactDigest,
1785
1944
  targetLibraryPath,
1786
1945
  confirm,
1946
+ confirmVerification,
1787
1947
  }));
1788
1948
  });
1789
1949
  server.registerTool("timeline.export", {
@@ -1848,9 +2008,28 @@ export function createMcpServer(runtime, options = {}) {
1848
2008
  });
1849
2009
  });
1850
2010
  server.registerTool("context.inspect", {
1851
- description: "Read the queryable agent editing context and its current revision.",
1852
- inputSchema: {},
1853
- }, async () => jsonResult(await runtime.inspectContext()));
2011
+ description: "Read editing context passively, or explicitly confirm a headed read for the expected project and sequence.",
2012
+ inputSchema: {
2013
+ confirmHeadedRead: z.boolean().optional(),
2014
+ expectedTarget: contextTargetSchema.optional(),
2015
+ },
2016
+ }, async ({ confirmHeadedRead, expectedTarget }) => sessionResult(async () => {
2017
+ if (!confirmHeadedRead)
2018
+ return runtime.inspectContext({ probeCanonicalSnapshot: false });
2019
+ if (!expectedTarget)
2020
+ throw new Error("EXPECTED_TARGET_REQUIRED: headed context read requires a project and sequence");
2021
+ const matches = (live) => live.project?.id === expectedTarget.projectId && live.sequence?.id === expectedTarget.sequenceId;
2022
+ if (!matches(await runtime.inspectLiveEditor()))
2023
+ throw new Error("TARGET_MISMATCH: active project or sequence differs from expected target");
2024
+ const context = await runtime.inspectContext({ probeCanonicalSnapshot: true });
2025
+ if (!context.project)
2026
+ throw new Error("CAPABILITY_UNAVAILABLE: headed canonical context could not be read");
2027
+ if (!matches(await runtime.inspectLiveEditor()) ||
2028
+ context.project.projectId !== expectedTarget.projectId || context.project.timeline.id !== expectedTarget.sequenceId) {
2029
+ throw new Error("TARGET_MISMATCH: context target changed during headed read");
2030
+ }
2031
+ return context;
2032
+ }));
1854
2033
  server.registerTool("context.changes", {
1855
2034
  description: "Read incremental timeline, live-state, and native-asset changes after a context revision.",
1856
2035
  inputSchema: {
@@ -1899,7 +2078,7 @@ export function createMcpServer(runtime, options = {}) {
1899
2078
  server.registerTool("timeline.inspect", {
1900
2079
  description: "Read a bound session baseline or perform an explicit canonical timeline resync after canonical capability checks.",
1901
2080
  inputSchema: timelineReadbackSchema,
1902
- }, async ({ sessionId, requestedCanonical, finalVerification }) => {
2081
+ }, async ({ sessionId, requestedCanonical, finalVerification, confirmHeadedRead, expectedTarget }) => {
1903
2082
  if (sessionId) {
1904
2083
  const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1905
2084
  if (decision.route === "session" || decision.route === "fast-observation") {
@@ -1910,41 +2089,19 @@ export function createMcpServer(runtime, options = {}) {
1910
2089
  timeline: stored.document.base,
1911
2090
  });
1912
2091
  }
1913
- const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1914
- return jsonResult({
1915
- sessionId,
1916
- readback: decision,
1917
- snapshot: resynced.snapshot.timeline,
1918
- session: resynced.session,
1919
- });
1920
- }
1921
- const inspected = await inspectMcpEditor(runtime, options);
1922
- const capability = inspected.capabilities.families.canonicalDocument.read;
1923
- if (!capability.available) {
1924
- return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
1925
- }
1926
- try {
1927
- return jsonResult(await runtime.inspectTimeline());
1928
- }
1929
- catch (error) {
1930
- return capabilityUnavailableErrorResult(error);
2092
+ return inspectCanonicalReadForMcp(runtime, options, "timeline.inspect", confirmHeadedRead, expectedTarget, async () => {
2093
+ const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
2094
+ return { sessionId, readback: decision, snapshot: resynced.snapshot.timeline, session: resynced.session };
2095
+ }, (result) => ({ sequenceId: result.snapshot.id }));
1931
2096
  }
2097
+ return inspectCanonicalReadForMcp(runtime, options, "timeline.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectTimeline(), (result) => ({ sequenceId: result.id }));
1932
2098
  });
1933
2099
  server.registerTool("timeline.semantic.inspect", {
1934
2100
  description: "Enrich timeline occurrences with source-range-bound semantic speech, visual, and metadata context without mutating the timeline.",
1935
2101
  inputSchema: timelineSemanticContextQuerySchema.shape,
1936
2102
  }, async (query) => {
1937
- const inspected = await inspectMcpEditor(runtime, options);
1938
- const capability = inspected.capabilities.families.canonicalDocument.read;
1939
- if (!capability.available) {
1940
- return capabilityErrorResult("timeline.semantic.inspect", "canonicalDocument.read", capability);
1941
- }
1942
- try {
1943
- return jsonResult(await runtime.inspectTimelineSemanticContext(query));
1944
- }
1945
- catch (error) {
1946
- return capabilityUnavailableErrorResult(error);
1947
- }
2103
+ const { confirmHeadedRead, expectedTarget, ...contextQuery } = query;
2104
+ return inspectCanonicalReadForMcp(runtime, options, "timeline.semantic.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectTimelineSemanticContext(contextQuery), (result) => ({ sequenceId: result.timelineId }));
1948
2105
  });
1949
2106
  server.registerTool("timeline.frame.capture", {
1950
2107
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
@@ -2026,6 +2183,18 @@ export function createMcpServer(runtime, options = {}) {
2026
2183
  sequence: z.number().int().nonnegative().optional(),
2027
2184
  },
2028
2185
  }, async ({ projectId, sequenceId, revision, sequence }) => {
2186
+ if (!(projectId && sequenceId && revision)) {
2187
+ const inspected = await inspectMcpEditor(runtime, options);
2188
+ const capability = inspected.capabilities.families.canonicalDocument.read;
2189
+ if (!capability.available)
2190
+ return capabilityErrorResult("timeline.changes", "canonicalDocument.read", capability);
2191
+ if (capability.evidenceTier === "headed-native") {
2192
+ return capabilityErrorResult("timeline.changes", "canonicalDocument.read", {
2193
+ available: false, backend: capability.backend, guarantee: "none",
2194
+ unavailableReason: "canonical timeline changes require an explicitly authorized headed read",
2195
+ });
2196
+ }
2197
+ }
2029
2198
  const project = projectId && sequenceId && revision
2030
2199
  ? undefined
2031
2200
  : await runtime.inspectProject();
@@ -2402,8 +2571,52 @@ async function effectiveConnectionStatus(runtime, options) {
2402
2571
  });
2403
2572
  }
2404
2573
  }
2405
- async function inspectMcpEditor(runtime, options) {
2406
- const inspected = await runtime.inspectEditor();
2574
+ async function inspectCanonicalReadForMcp(runtime, options, operation, confirmHeadedRead, expectedTarget, read, targetOf) {
2575
+ const passive = await inspectMcpEditor(runtime, options);
2576
+ const headed = passive.identity.backend === "final-cut-native-canonical";
2577
+ if (headed && (!confirmHeadedRead || !expectedTarget)) {
2578
+ return mcpReadErrorResult("HEADED_READ_CONFIRMATION_REQUIRED", `${operation} requires confirmHeadedRead and expectedTarget projectId and sequenceId before exporting a canonical snapshot`, operation);
2579
+ }
2580
+ if (headed && expectedTarget) {
2581
+ const before = await runtime.inspectLiveEditor();
2582
+ if (!liveTargetMatches(before, expectedTarget)) {
2583
+ return mcpReadErrorResult("TARGET_MISMATCH", `${operation} active project or sequence differs from expectedTarget`, operation);
2584
+ }
2585
+ }
2586
+ return runtime.withCanonicalReadScope(async () => {
2587
+ const inspected = await inspectMcpEditor(runtime, options, true);
2588
+ const capability = inspected.capabilities.families.canonicalDocument.read;
2589
+ if (!capability.available)
2590
+ return capabilityErrorResult(operation, "canonicalDocument.read", capability);
2591
+ try {
2592
+ const result = await read();
2593
+ if (headed && expectedTarget) {
2594
+ const live = await runtime.inspectLiveEditor();
2595
+ const returnedTarget = targetOf(result);
2596
+ if (!liveTargetMatches(live, expectedTarget)
2597
+ || (returnedTarget.projectId !== undefined && returnedTarget.projectId !== expectedTarget.projectId)
2598
+ || (returnedTarget.sequenceId !== undefined && returnedTarget.sequenceId !== expectedTarget.sequenceId)) {
2599
+ return mcpReadErrorResult("TARGET_MISMATCH", `${operation} result or active target changed during the headed read`, operation);
2600
+ }
2601
+ }
2602
+ return jsonResult(result);
2603
+ }
2604
+ catch (error) {
2605
+ return capabilityUnavailableErrorResult(error);
2606
+ }
2607
+ });
2608
+ }
2609
+ function liveTargetMatches(live, target) {
2610
+ return live.project?.id === target.projectId && live.sequence?.id === target.sequenceId;
2611
+ }
2612
+ function mcpReadErrorResult(code, message, operation) {
2613
+ return {
2614
+ isError: true,
2615
+ content: [{ type: "text", text: JSON.stringify({ code, message, operation }) }],
2616
+ };
2617
+ }
2618
+ async function inspectMcpEditor(runtime, options, probeCanonicalSnapshot = false) {
2619
+ const inspected = await runtime.inspectEditor({ probeCanonicalSnapshot });
2407
2620
  const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2408
2621
  const buildAlignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2409
2622
  if (options.requireBuildAlignment && buildAlignment.status !== "matched") {
@@ -2428,6 +2641,7 @@ async function inspectMcpEditor(runtime, options) {
2428
2641
  ...inspected.capabilities.editor,
2429
2642
  artifactPublish: publishingAvailable,
2430
2643
  artifactPublishMode: publishingMode,
2644
+ ...(publishingAvailable ? { artifactPublishDispatchGuarantee: "requested-unverified" } : {}),
2431
2645
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
2432
2646
  videoExport: exportAvailable,
2433
2647
  backgroundRender: backgroundExportAvailable,
@@ -2462,6 +2676,7 @@ async function inspectMcpEditor(runtime, options) {
2462
2676
  },
2463
2677
  publishing: publishingAvailable,
2464
2678
  publishingBackend: publishingMode === "background-capable" ? "fcpxml-document-open" : "fcpxml-publisher",
2679
+ publishingGuarantee: "native-verified",
2465
2680
  export: exportAvailable,
2466
2681
  exportBackend: "final-cut-native-export",
2467
2682
  backgroundExport: {
@@ -2497,7 +2712,7 @@ async function inspectMcpEditor(runtime, options) {
2497
2712
  }),
2498
2713
  fingerprint,
2499
2714
  buildAlignment,
2500
- nativeHandoffReadiness: createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
2715
+ nativeHandoffReadiness: await createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
2501
2716
  },
2502
2717
  ...(native ? { native } : {}),
2503
2718
  };
@@ -2506,7 +2721,7 @@ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
2506
2721
  const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2507
2722
  let extensionFingerprint;
2508
2723
  try {
2509
- extensionFingerprint = (await runtime.inspectEditor()).identity.buildFingerprint;
2724
+ extensionFingerprint = (await runtime.inspectEditor({ probeCanonicalSnapshot: false })).identity.buildFingerprint;
2510
2725
  }
2511
2726
  catch {
2512
2727
  const status = await connectionStatus(options).catch(() => undefined);
@@ -2515,7 +2730,7 @@ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
2515
2730
  const buildAlignment = assessBuildAlignment(fingerprint, extensionFingerprint, options.validationCommit);
2516
2731
  return createNativeHandoffReadiness(options.projectPublisher, buildAlignment, publishJobId);
2517
2732
  }
2518
- function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2733
+ async function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2519
2734
  const publisherReadiness = inspectProjectPublisherReadiness(publisher);
2520
2735
  const reasons = [...publisherReadiness.reasons];
2521
2736
  if (buildAlignment.status !== "matched") {
@@ -2537,15 +2752,36 @@ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2537
2752
  }
2538
2753
  else {
2539
2754
  try {
2540
- const job = publisher.getPublishJob(publishJobId);
2755
+ const job = typeof publisher.loadPublishJob === "function"
2756
+ ? await publisher.loadPublishJob(publishJobId)
2757
+ : publisher.getPublishJob(publishJobId);
2541
2758
  publish = { jobId: job.jobId, state: job.state };
2542
2759
  const resultTarget = job.result?.createdTarget;
2543
2760
  const targetMatches = job.createdTarget
2544
2761
  && resultTarget
2545
- && job.createdTarget.projectId === resultTarget.projectId
2546
- && job.createdTarget.sequenceId === resultTarget.sequenceId;
2762
+ && nativeTargetIdentityMatches(job.createdTarget, resultTarget);
2547
2763
  if (job.state === "verified" && job.result?.verified === true && targetMatches) {
2548
- verifiedTarget = resultTarget;
2764
+ if (typeof publisher.verifyCreatedTarget === "function") {
2765
+ try {
2766
+ const reboundTarget = await publisher.verifyCreatedTarget(job.jobId);
2767
+ if (!nativeTargetIdentityMatches(resultTarget, reboundTarget)) {
2768
+ throw new Error("persisted target identity changed during live rebind");
2769
+ }
2770
+ verifiedTarget = reboundTarget;
2771
+ }
2772
+ catch (error) {
2773
+ reasons.push({
2774
+ code: "FINAL_CUT_PUBLISH_TARGET_REBIND_FAILED",
2775
+ message: `Publish job ${job.jobId} no longer matches the live native target: ${error instanceof Error ? error.message : String(error)}`,
2776
+ });
2777
+ }
2778
+ }
2779
+ else {
2780
+ reasons.push({
2781
+ code: "FINAL_CUT_PUBLISH_TARGET_REBIND_UNAVAILABLE",
2782
+ message: `Publish job ${job.jobId} cannot be rebound because the publisher cannot revalidate the native library and active target`,
2783
+ });
2784
+ }
2549
2785
  }
2550
2786
  else {
2551
2787
  reasons.push({
@@ -2578,6 +2814,13 @@ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2578
2814
  ...(ready && verifiedTarget ? { createdTarget: verifiedTarget } : {}),
2579
2815
  };
2580
2816
  }
2817
+ function nativeTargetIdentityMatches(left, right) {
2818
+ return left.kind === right.kind
2819
+ && left.projectId === right.projectId
2820
+ && left.sequenceId === right.sequenceId
2821
+ && left.libraryId === right.libraryId
2822
+ && left.eventId === right.eventId;
2823
+ }
2581
2824
  function inspectProjectPublisherReadiness(publisher) {
2582
2825
  if (!publisher) {
2583
2826
  return {
@@ -2603,13 +2846,425 @@ function inspectProjectPublisherReadiness(publisher) {
2603
2846
  };
2604
2847
  }
2605
2848
  async function assertRequiredBuildAlignment(runtime, options) {
2606
- const inspected = await runtime.inspectEditor();
2849
+ const inspected = await runtime.inspectEditor({ probeCanonicalSnapshot: false });
2607
2850
  const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2608
2851
  const alignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2609
2852
  if (alignment.status !== "matched") {
2610
2853
  throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${alignment.message}`);
2611
2854
  }
2612
2855
  }
2856
+ function withPublishRecoveryGuard(provider, recovery, validateRoute) {
2857
+ const allowed = new Set(["isAvailable", "inspectReadiness", "executionMode", "getPublishJob", "loadPublishJob", "preparePublish"]);
2858
+ let current;
2859
+ return new Proxy(provider, {
2860
+ get(target, property) {
2861
+ if (property !== "executePublishJob" && property !== "publishNewProject") {
2862
+ const value = Reflect.get(target, property, target);
2863
+ if (typeof value !== "function")
2864
+ return value;
2865
+ if (allowed.has(property))
2866
+ return value.bind(target);
2867
+ return async (...args) => {
2868
+ await recovery.assertClear();
2869
+ return Reflect.apply(value, target, args);
2870
+ };
2871
+ }
2872
+ return async (...args) => {
2873
+ const jobId = property === "executePublishJob" && typeof args[0] === "string" ? args[0] : undefined;
2874
+ let provenDisabled = false;
2875
+ let entry = current;
2876
+ const acquiringReservation = !entry;
2877
+ if (entry) {
2878
+ if (entry.active || !jobId || entry.jobId !== jobId || args[1] !== true || args[2] !== true) {
2879
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish reservation only permits verification of its settled pending job");
2880
+ }
2881
+ entry.active = true;
2882
+ try {
2883
+ const observed = await recovery.inspectNativeReservation();
2884
+ if (observed?.reservationId !== entry.reservation.reservationId) {
2885
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish reservation changed before verification");
2886
+ }
2887
+ const getJob = Reflect.get(target, "getPublishJob", target);
2888
+ const job = getJob.call(target, jobId);
2889
+ if (job?.state !== "verification-pending" || (job.jobId !== undefined && job.jobId !== jobId)) {
2890
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job changed before verification");
2891
+ }
2892
+ }
2893
+ catch (error) {
2894
+ entry.active = false;
2895
+ throw error;
2896
+ }
2897
+ }
2898
+ else {
2899
+ // Never invoke caller-controlled job lookup before the reservation.
2900
+ const job = jobId ? inertBuiltInPublishJob(target, jobId) : undefined;
2901
+ if (job && job.jobId !== jobId)
2902
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity mismatch");
2903
+ const pending = job?.state === "verification-pending";
2904
+ const operation = jobId
2905
+ ? `native.publish.${createHash("sha256").update(jobId).digest("hex")}`
2906
+ : "native.publish.direct";
2907
+ const path = job?.targetLibraryPath;
2908
+ const digest = job?.artifactDigest;
2909
+ const context = jobId && !pending && /^publish-job-[a-z0-9-]{1,80}$/.test(jobId)
2910
+ && typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
2911
+ && typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)
2912
+ ? Object.freeze({ kind: "publish", jobId, dispatchId: randomUUID(), requestedTarget: Object.freeze({ libraryPath: path }),
2913
+ artifactDigest: digest, executorIdentity: null, nativeQuiescence: "unproven" })
2914
+ : undefined;
2915
+ // Capture primitives and data descriptors before awaiting the guard;
2916
+ // its implementation must not rewrite the evidence used for rechecks.
2917
+ const configurationKeys = ["enabled", "liveState", "readCanonicalSnapshot", "sourcePath", "publishJobsDirectory"];
2918
+ const requestedConfiguration = job ? configurationKeys.map((key) => Object.getOwnPropertyDescriptor(target, key)) : undefined;
2919
+ const requestedIntent = context && job ? { libraryPath: context.requestedTarget.libraryPath,
2920
+ artifactDigest: context.artifactDigest, state: job.state } : undefined;
2921
+ const reservation = await recovery.beginNative(operation, context);
2922
+ entry = { jobId, reservation, active: true, dispatched: pending, needsBinding: !context,
2923
+ ...(requestedIntent ? { requestedIntent } : {}), ...(requestedConfiguration ? { requestedConfiguration } : {}) };
2924
+ current = entry;
2925
+ }
2926
+ try {
2927
+ if (acquiringReservation && jobId && entry.requestedIntent) {
2928
+ const currentJob = inertBuiltInPublishJob(target, jobId);
2929
+ const expected = entry.requestedIntent;
2930
+ if (!currentJob || currentJob.jobId !== jobId || currentJob.targetLibraryPath !== expected.libraryPath
2931
+ || currentJob.artifactDigest !== expected.artifactDigest || currentJob.state !== expected.state) {
2932
+ entry.dispatched = true;
2933
+ await entry.reservation.markDispatchPossible();
2934
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish intent changed during reservation acquisition");
2935
+ }
2936
+ }
2937
+ // Property getters on arbitrary providers may themselves dispatch.
2938
+ const trustedShape = !utilTypes.isProxy(target) && property === "executePublishJob"
2939
+ && Object.getPrototypeOf(target) === FinalCutProjectPublisher.prototype
2940
+ && [["executePublishJob", builtInPublishExecute], ["getPublishJob", builtInPublishGetJob],
2941
+ ["persistPublishJob", builtInPublishPersist], ["trackNativeDispatch", builtInPublishTrack]].every(([key, method]) => typeof key === "string" && !Object.getOwnPropertyDescriptor(target, key)
2942
+ && Object.getOwnPropertyDescriptor(FinalCutProjectPublisher.prototype, key)?.value === method);
2943
+ if (acquiringReservation && !trustedShape) {
2944
+ entry.dispatched = true;
2945
+ await entry.reservation.markDispatchPossible();
2946
+ // A custom lookup may execute arbitrary provider code. Run it only
2947
+ // after durable uncertainty, then bind any eligible requested intent.
2948
+ if (jobId && entry.needsBinding) {
2949
+ const lookup = Reflect.get(target, "getPublishJob", target);
2950
+ if (typeof lookup === "function") {
2951
+ const requested = Reflect.apply(lookup, target, [jobId]);
2952
+ if (requested?.jobId !== undefined && requested.jobId !== jobId) {
2953
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity mismatch");
2954
+ }
2955
+ if (requested?.state === "verification-pending") {
2956
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: unowned pending publish cannot be invoked again");
2957
+ }
2958
+ const path = requested?.targetLibraryPath;
2959
+ const digest = requested?.artifactDigest;
2960
+ if (requested?.state !== "verification-pending" && /^publish-job-[a-z0-9-]{1,80}$/.test(jobId)
2961
+ && typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
2962
+ && typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)) {
2963
+ await entry.reservation.bindRecoveryContext({ kind: "publish", jobId, dispatchId: randomUUID(),
2964
+ requestedTarget: { libraryPath: path }, artifactDigest: digest,
2965
+ executorIdentity: null, nativeQuiescence: "unproven" });
2966
+ }
2967
+ }
2968
+ }
2969
+ }
2970
+ const value = trustedShape ? builtInPublishExecute : Reflect.get(target, property, target);
2971
+ const track = trustedShape ? builtInPublishTrack : Reflect.get(target, "trackNativeDispatch", target);
2972
+ if (typeof value !== "function")
2973
+ throw new Error("CAPABILITY_UNAVAILABLE: publisher operation is not available");
2974
+ if (acquiringReservation && jobId && property === "executePublishJob"
2975
+ && trustedShape) {
2976
+ const stores = ["publishJobs", "publishJobRuntime"].map((key) => Object.getOwnPropertyDescriptor(target, key)?.value);
2977
+ const ordinaryStores = stores.every((store) => !utilTypes.isProxy(store) && utilTypes.isMap(store)
2978
+ && Object.getPrototypeOf(store) === Map.prototype
2979
+ && !Object.getOwnPropertyDescriptor(store, "get") && !Object.getOwnPropertyDescriptor(store, "set") && !Object.getOwnPropertyDescriptor(store, "has")
2980
+ && Object.getOwnPropertyDescriptor(Map.prototype, "get")?.value === builtInMapGet
2981
+ && Object.getOwnPropertyDescriptor(Map.prototype, "set")?.value === builtInMapSet
2982
+ && Object.getOwnPropertyDescriptor(Map.prototype, "has")?.value === builtInMapHas);
2983
+ const job = ordinaryStores ? inertBuiltInPublishJob(target, jobId) : undefined;
2984
+ if (!ordinaryStores || (!job && builtInMapHas.call(stores[0], jobId))) {
2985
+ // A present but non-inert job may execute getters or identify a
2986
+ // different operation. Do not invoke it even after the marker.
2987
+ entry.dispatched = true;
2988
+ await entry.reservation.markDispatchPossible();
2989
+ throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity cannot be inspected safely");
2990
+ }
2991
+ if (job) {
2992
+ const enabled = Object.getOwnPropertyDescriptor(target, "enabled");
2993
+ const directory = Object.getOwnPropertyDescriptor(target, "publishJobsDirectory");
2994
+ const configurationKeys = ["enabled", "liveState", "readCanonicalSnapshot", "sourcePath", "publishJobsDirectory"];
2995
+ const configurationUnchanged = Boolean(entry.requestedConfiguration && configurationKeys.every((key, index) => {
2996
+ const before = entry.requestedConfiguration?.[index];
2997
+ const after = Object.getOwnPropertyDescriptor(target, key);
2998
+ return before && after && "value" in before && "value" in after && Object.is(before.value, after.value);
2999
+ }));
3000
+ const safePersistence = Boolean(configurationUnchanged && directory && "value" in directory
3001
+ && (directory.value === undefined
3002
+ || (typeof directory.value === "string" && !builtInMapHas.call(stores[1], jobId))));
3003
+ provenDisabled = (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
3004
+ && enabled?.value === false && safePersistence;
3005
+ const liveState = Object.getOwnPropertyDescriptor(target, "liveState");
3006
+ if (args[1] === true && enabled?.value === true && safePersistence
3007
+ && (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
3008
+ && liveState && "value" in liveState && liveState.value === undefined) {
3009
+ // This preflight uses only inert data and never invokes the
3010
+ // provider or its mutable dependencies.
3011
+ const blocked = { ...job, state: "awaiting-final-cut", nextAction: "retry", retryable: true,
3012
+ error: { code: "FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE", message: "Final Cut project state verification is unavailable; retry this job when the live provider is ready" } };
3013
+ builtInPublishPersist.call(target, blocked);
3014
+ return blocked;
3015
+ }
3016
+ const readback = Object.getOwnPropertyDescriptor(target, "readCanonicalSnapshot");
3017
+ if (args[1] === true && enabled?.value === true && safePersistence
3018
+ && (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
3019
+ && liveState && "value" in liveState && typeof liveState.value === "function"
3020
+ && readback && "value" in readback && readback.value === undefined) {
3021
+ const failed = { ...job, state: "failed", nextAction: "none", retryable: false,
3022
+ error: { code: "FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE", message: "FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE: headed canonical timeline readback is not configured; no import was attempted" } };
3023
+ builtInPublishPersist.call(target, failed);
3024
+ return failed;
3025
+ }
3026
+ // A mismatching managed artifact can be rejected without invoking
3027
+ // the publisher or its tracker. Keep this synchronous so the
3028
+ // trusted store and publisher checks cannot race an await.
3029
+ const source = Object.getOwnPropertyDescriptor(target, "sourcePath");
3030
+ if (args[1] === true && enabled?.value === true && !provenDisabled
3031
+ && (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
3032
+ && !job.sourceTransactionId.startsWith("headless-rough-cut:")
3033
+ && typeof source?.value === "string" && source.value === job.sourcePath
3034
+ && safePersistence
3035
+ && managedArtifactChanged(job.sourcePath, job.artifactDigest)) {
3036
+ const failed = { ...job, state: "failed", nextAction: "none", retryable: false,
3037
+ error: { code: "PUBLISH_SOURCE_CHANGED", message: "Managed FCPXML artifact changed after transaction verification" } };
3038
+ builtInPublishPersist.call(target, failed);
3039
+ return failed;
3040
+ }
3041
+ }
3042
+ }
3043
+ const invoke = async () => {
3044
+ // Once the provider is invoked, a missing callback is not proof of non-dispatch.
3045
+ if (!provenDisabled)
3046
+ entry.dispatched = true;
3047
+ return Reflect.apply(value, target, args);
3048
+ };
3049
+ // Custom tracking code can defer invocation and return or throw first.
3050
+ if (!provenDisabled)
3051
+ entry.dispatched = true;
3052
+ // Record uncertainty before entering any untrusted tracker or provider.
3053
+ // Resumed verification reuses the already marked reservation.
3054
+ if (acquiringReservation && trustedShape && !provenDisabled)
3055
+ await entry.reservation.markDispatchPossible();
3056
+ if (!provenDisabled)
3057
+ await validateRoute(target, property);
3058
+ const result = typeof track === "function"
3059
+ ? await Reflect.apply(track, target, [invoke, () => { entry.dispatched = true; }])
3060
+ : await invoke();
3061
+ if (entry.dispatched && result && typeof result === "object" && !Array.isArray(result)) {
3062
+ return { ...result, recoveryReservation: { status: "recovery-required", reservationId: entry.reservation.reservationId, reason: "native-quiescence-unproven" } };
3063
+ }
3064
+ return result;
3065
+ }
3066
+ finally {
3067
+ entry.active = false;
3068
+ if (!entry.dispatched) {
3069
+ await entry.reservation.release();
3070
+ if (current === entry)
3071
+ current = undefined;
3072
+ }
3073
+ }
3074
+ };
3075
+ },
3076
+ });
3077
+ }
3078
+ function inertBuiltInPublishJob(target, jobId) {
3079
+ if (utilTypes.isProxy(target) || Object.getPrototypeOf(target) !== FinalCutProjectPublisher.prototype
3080
+ || Object.getOwnPropertyDescriptor(target, "getPublishJob")
3081
+ || Object.getOwnPropertyDescriptor(FinalCutProjectPublisher.prototype, "getPublishJob")?.value !== builtInPublishGetJob)
3082
+ return undefined;
3083
+ const store = Object.getOwnPropertyDescriptor(target, "publishJobs")?.value;
3084
+ if (utilTypes.isProxy(store) || !utilTypes.isMap(store) || Object.getPrototypeOf(store) !== Map.prototype
3085
+ || Object.getOwnPropertyDescriptor(Map.prototype, "get")?.value !== builtInMapGet)
3086
+ return undefined;
3087
+ const job = builtInMapGet.call(store, jobId);
3088
+ const seen = new Set();
3089
+ const inert = (value) => {
3090
+ if (value === null || ["string", "boolean", "number", "undefined"].includes(typeof value))
3091
+ return true;
3092
+ if (typeof value !== "object" || utilTypes.isProxy(value) || seen.has(value) || seen.size >= 10_000)
3093
+ return false;
3094
+ seen.add(value);
3095
+ const prototype = Object.getPrototypeOf(value);
3096
+ if (prototype !== Object.prototype && prototype !== Array.prototype && prototype !== null)
3097
+ return false;
3098
+ return Reflect.ownKeys(value).every((key) => {
3099
+ if (typeof key !== "string")
3100
+ return false;
3101
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
3102
+ return Boolean(descriptor && "value" in descriptor && inert(descriptor.value));
3103
+ });
3104
+ };
3105
+ return inert(job) && job && typeof job === "object" ? structuredClone(job) : undefined;
3106
+ }
3107
+ function managedArtifactChanged(path, digest) {
3108
+ let fd;
3109
+ try {
3110
+ fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
3111
+ const info = fstatSync(fd);
3112
+ if (!info.isFile() || info.size > 64 * 1024 * 1024)
3113
+ return false;
3114
+ return createHash("sha256").update(readFileSync(fd, "utf8")).digest("hex") !== digest;
3115
+ }
3116
+ catch {
3117
+ return false;
3118
+ }
3119
+ finally {
3120
+ if (fd !== undefined)
3121
+ closeSync(fd);
3122
+ }
3123
+ }
3124
+ function isBuiltinImportObservationUnavailable(provider) {
3125
+ if (!provider || utilTypes.isProxy(provider) || Object.getPrototypeOf(provider) !== FinalCutNativeAutomationAdapter.prototype)
3126
+ return false;
3127
+ const observer = Object.getOwnPropertyDescriptor(provider, "importSourceObserver");
3128
+ if (!observer || !("value" in observer) || observer.value !== undefined)
3129
+ return false;
3130
+ return ["importMedia", "executeImportMediaDirectory", "capabilities"].every((key) => !Object.getOwnPropertyDescriptor(provider, key)
3131
+ && Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === builtInNativeMethods.get(key));
3132
+ }
3133
+ function withRecoveryCheckpointGuard(provider, recovery, allowedMethods = [], reservedMethods = [], reservationKind = "native") {
3134
+ const allowed = new Set(allowedMethods);
3135
+ const reserved = new Set(reservedMethods);
3136
+ const contextMethods = new Set(["focusTimeline", "selectMedia", "selectOccurrence", "selectCanonicalOccurrence"]);
3137
+ const searchMethods = new Set(["searchMedia", "searchMediaForCanonicalTarget", "searchTitles", "searchTransitions"]);
3138
+ return new Proxy(provider, {
3139
+ get(target, property) {
3140
+ if (!reserved.has(property)) {
3141
+ const value = Reflect.get(target, property, target);
3142
+ if (typeof value !== "function")
3143
+ return value;
3144
+ if (allowed.has(property))
3145
+ return value.bind(target);
3146
+ return async (...args) => {
3147
+ await recovery.assertClear();
3148
+ return Reflect.apply(value, target, args);
3149
+ };
3150
+ }
3151
+ // Inspect descriptors without invoking provider accessors while another
3152
+ // native reservation may be held. Unknown proxy shapes stay guarded.
3153
+ if (!utilTypes.isProxy(target)) {
3154
+ let object = target;
3155
+ while (object && !utilTypes.isProxy(object)) {
3156
+ const descriptor = Object.getOwnPropertyDescriptor(object, property);
3157
+ if (descriptor) {
3158
+ if ("value" in descriptor && typeof descriptor.value !== "function")
3159
+ return descriptor.value;
3160
+ break;
3161
+ }
3162
+ object = Object.getPrototypeOf(object);
3163
+ }
3164
+ if (!object)
3165
+ return undefined;
3166
+ }
3167
+ return async (...args) => {
3168
+ if (reserved.has(property)) {
3169
+ const reservation = await recovery.beginNative(`native.${reservationKind === "disposable" ? "disposable." : ""}${String(property).toLowerCase()}`);
3170
+ // Reject a disabled operation without invoking any adapter code. For all
3171
+ // other cases, callbacks and mutable internals may schedule dispatch.
3172
+ const disabledPreflight = !utilTypes.isProxy(target)
3173
+ && Object.getPrototypeOf(target) === FinalCutNativeAutomationAdapter.prototype
3174
+ && Object.getOwnPropertyDescriptor(target, "enabled")?.value === false
3175
+ && Reflect.ownKeys(target).every((key) => {
3176
+ const descriptor = Object.getOwnPropertyDescriptor(target, key);
3177
+ return Boolean(descriptor && "value" in descriptor);
3178
+ })
3179
+ && [...builtInNativeMethods].every(([key, method]) => key === "constructor" || typeof method !== "function"
3180
+ || (!Object.getOwnPropertyDescriptor(target, key)
3181
+ && Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === method));
3182
+ const untrustedProvider = !disabledPreflight;
3183
+ let dispatched = untrustedProvider;
3184
+ try {
3185
+ if (untrustedProvider)
3186
+ await reservation.markDispatchPossible();
3187
+ if (disabledPreflight) {
3188
+ if (property === "focusTimeline") {
3189
+ await reservation.release();
3190
+ return disabledNativeFocusContext();
3191
+ }
3192
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are disabled");
3193
+ }
3194
+ const value = Reflect.get(target, property, target);
3195
+ const track = Reflect.get(target, "trackNativeDispatch", target);
3196
+ if (typeof value !== "function")
3197
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation is not available");
3198
+ const invoke = async () => Reflect.apply(value, target, args);
3199
+ const result = typeof track === "function"
3200
+ ? await Reflect.apply(track, target, [invoke, () => { dispatched = true; }])
3201
+ : await invoke();
3202
+ const evidence = result;
3203
+ const restored = typeof evidence?.beforeDigest === "string" && /^[a-f0-9]{64}$/.test(evidence.beforeDigest)
3204
+ && evidence.restoredDigest === evidence.beforeDigest;
3205
+ const media = (value) => {
3206
+ if (!value || typeof value !== "object")
3207
+ return false;
3208
+ const item = value;
3209
+ return typeof item.mediaHandle === "string" && item.mediaHandle.length > 0
3210
+ && item.verification?.verified === true && item.verification.stage === "post-import-browser-discovery";
3211
+ };
3212
+ const directory = result;
3213
+ const verifiedDirectory = () => {
3214
+ if (directory?.status !== "completed" || directory.partial !== false || directory.failedCount !== 0
3215
+ || !Array.isArray(directory.files) || directory.files.length === 0
3216
+ || directory.importedCount !== directory.files.length || !Array.isArray(directory.results)
3217
+ || directory.results.length !== directory.files.length)
3218
+ return false;
3219
+ const expected = new Set();
3220
+ for (const file of directory.files) {
3221
+ if (!file || typeof file.sourcePath !== "string" || !file.sourcePath || expected.has(file.sourcePath))
3222
+ return false;
3223
+ expected.add(file.sourcePath);
3224
+ }
3225
+ const handles = new Set();
3226
+ for (const entry of directory.results) {
3227
+ if (!entry || entry.status !== "imported" || typeof entry.sourcePath !== "string"
3228
+ || !expected.delete(entry.sourcePath) || !media(entry.media))
3229
+ return false;
3230
+ const item = entry.media;
3231
+ if (item.sourcePath !== entry.sourcePath || handles.has(item.mediaHandle))
3232
+ return false;
3233
+ handles.add(item.mediaHandle);
3234
+ }
3235
+ return expected.size === 0;
3236
+ };
3237
+ const preview = typeof property === "string" && property.startsWith("preview");
3238
+ const prepared = result;
3239
+ const verified = preview ? typeof prepared?.previewToken === "string" && prepared.previewToken.length > 0
3240
+ : contextMethods.has(property) ? prepared?.available === true
3241
+ : searchMethods.has(property) ? Array.isArray(result)
3242
+ : property === "locateOccurrence" || property === "locateOccurrenceForCanonicalTarget" ? ["none", "unique", "ambiguous"].includes(String(prepared?.status)) && Array.isArray(prepared?.occurrences)
3243
+ : property === "targetMedia" ? prepared?.status === "unique" && prepared.selected === true
3244
+ : property === "importMedia" ? media(result)
3245
+ : property === "executeImportMediaDirectory" ? verifiedDirectory()
3246
+ : reservationKind === "disposable"
3247
+ ? property === "undo"
3248
+ ? evidence?.undone === true && evidence.verification?.passed === true && restored
3249
+ : (evidence?.status === "VERIFIED" && evidence.verification?.passed === true)
3250
+ || (evidence?.status === "ROLLED_BACK" && restored)
3251
+ : evidence?.verification?.verified === true && (property !== "undo" || evidence.undone === true);
3252
+ if (!untrustedProvider && (verified || (!dispatched && contextMethods.has(property) && prepared?.available === false))) {
3253
+ await reservation.release();
3254
+ }
3255
+ return result;
3256
+ }
3257
+ catch (error) {
3258
+ if (!dispatched)
3259
+ await reservation.release();
3260
+ throw error;
3261
+ }
3262
+ }
3263
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation is not available");
3264
+ };
3265
+ },
3266
+ });
3267
+ }
2613
3268
  function withBuildAlignmentGuard(provider, assertAlignment, synchronousMethods = []) {
2614
3269
  const synchronous = new Set(synchronousMethods);
2615
3270
  return new Proxy(provider, {