@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
@@ -0,0 +1,204 @@
1
+ import { type TimelineIr } from "../../../packages/runtime/src/index.js";
2
+ import { type FileCanonicalRecoveryGuard, type TimelineIrMaterializationCoverage, type TimelineIrMaterializationProvenance, type TimelineIrToFcpxmlResult, type TimelineIrToFcpxmlTarget } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ import { EditingSessionRepository } from "./headless-sessions.js";
4
+ export interface SessionMaterializationPublishRequest {
5
+ jobId: string;
6
+ artifactPath: string;
7
+ artifactDigest: string;
8
+ target: TimelineIrToFcpxmlTarget;
9
+ destination: TimelineIrToFcpxmlResult["destination"];
10
+ collisionPolicy: "create-only";
11
+ desired: TimelineIr;
12
+ desiredDigest: string;
13
+ baseDigest: string;
14
+ baseRevision: TimelineIr["revision"];
15
+ coverage: TimelineIrMaterializationCoverage;
16
+ provenance: TimelineIrMaterializationProvenance;
17
+ }
18
+ export type MaterializationVerificationTier = "artifact" | "delivery" | "storage-observed" | "canonical-verified" | "interaction-required";
19
+ export type MaterializationDeliveryState = "background" | "activated" | "prompted" | "failed" | "interaction-required";
20
+ export interface MaterializationDeliveryEvidence {
21
+ state: MaterializationDeliveryState;
22
+ route: "background" | "headed" | "unknown";
23
+ }
24
+ export interface MaterializationStructuralDiff {
25
+ target: {
26
+ projectId: string;
27
+ sequenceId: string;
28
+ };
29
+ desiredDigest: string;
30
+ actualDigest: string;
31
+ changes: Array<{
32
+ path: string;
33
+ before?: unknown;
34
+ after?: unknown;
35
+ }>;
36
+ }
37
+ export interface MaterializationVerification {
38
+ tier: MaterializationVerificationTier;
39
+ status: "verified" | "blocked" | "failed";
40
+ artifactDigest: string;
41
+ desiredDigest: string;
42
+ reason?: string;
43
+ canonicalReadbackDigest?: string;
44
+ canonicalTarget?: {
45
+ libraryUid: string;
46
+ eventUid: string;
47
+ projectUid: string;
48
+ sequenceUid: string;
49
+ };
50
+ structuralDiff?: MaterializationStructuralDiff;
51
+ delivery?: MaterializationDeliveryEvidence;
52
+ }
53
+ export interface SessionMaterializationPublisher {
54
+ trackNativeDispatch?<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
55
+ readCanonicalTarget?(request: {
56
+ target: {
57
+ libraryUid: string;
58
+ eventUid: string;
59
+ projectUid: string;
60
+ sequenceUid: string;
61
+ };
62
+ }): Promise<{
63
+ canonicalReadback: TimelineIr;
64
+ canonicalTarget: {
65
+ libraryUid: string;
66
+ eventUid: string;
67
+ projectUid: string;
68
+ sequenceUid: string;
69
+ };
70
+ delivery?: MaterializationDeliveryEvidence;
71
+ }>;
72
+ publish(request: SessionMaterializationPublishRequest): Promise<{
73
+ state: "completed";
74
+ canonicalReadback: TimelineIr;
75
+ canonicalTarget: {
76
+ libraryUid: string;
77
+ eventUid: string;
78
+ projectUid: string;
79
+ sequenceUid: string;
80
+ };
81
+ headedNativeVerified: boolean;
82
+ delivery?: MaterializationDeliveryEvidence;
83
+ } | {
84
+ state: "blocked";
85
+ code: string;
86
+ message: string;
87
+ retryable: boolean;
88
+ delivery?: MaterializationDeliveryEvidence;
89
+ }>;
90
+ }
91
+ export interface SessionMaterializationJob {
92
+ schemaVersion: 1 | 2;
93
+ jobId: string;
94
+ sessionId: string;
95
+ state: "blocked" | "publishing" | "completed" | "failed";
96
+ nextAction: "retry" | "status" | "none";
97
+ artifactPath: string;
98
+ artifactDigest: string;
99
+ target: TimelineIrToFcpxmlTarget;
100
+ destination: TimelineIrToFcpxmlResult["destination"];
101
+ desired: TimelineIr;
102
+ desiredDigest: string;
103
+ baseDigest: string;
104
+ baseRevision: TimelineIr["revision"];
105
+ coverage?: TimelineIrMaterializationCoverage;
106
+ provenance?: TimelineIrMaterializationProvenance;
107
+ verification?: MaterializationVerification;
108
+ continuation?: {
109
+ state: "canonical-resync-required" | "resynced";
110
+ reason: string;
111
+ sessionId?: string;
112
+ readbackDigest?: string;
113
+ changeSinceHandoff?: "changed" | "unchanged" | "unknown";
114
+ delivery?: MaterializationDeliveryEvidence;
115
+ };
116
+ sessionDigest: string;
117
+ claim?: {
118
+ id: string;
119
+ claimedAt: string;
120
+ };
121
+ recoveryReservation?: {
122
+ reservationId: string;
123
+ reason: "native-quiescence-unproven";
124
+ };
125
+ providerError?: {
126
+ code: string;
127
+ message: string;
128
+ retryable: boolean;
129
+ };
130
+ providerRequestPhase?: "dispatch-intent" | "returned";
131
+ evidence: {
132
+ artifact: {
133
+ verified: true;
134
+ format: "fcpxml";
135
+ digest: string;
136
+ };
137
+ providerRequested: boolean;
138
+ canonicalReadback: boolean;
139
+ headedNative: boolean;
140
+ };
141
+ error?: {
142
+ code: string;
143
+ message: string;
144
+ retryable: boolean;
145
+ };
146
+ }
147
+ export declare class SessionMaterializationJobs {
148
+ private readonly directory;
149
+ private readonly sessions;
150
+ private readonly publisher?;
151
+ private readonly recoveryGuard?;
152
+ constructor(directory: string, sessions: EditingSessionRepository, publisher?: SessionMaterializationPublisher | undefined, recoveryGuard?: Pick<FileCanonicalRecoveryGuard, "beginNative"> | undefined);
153
+ preview(sessionId: string, target: TimelineIrToFcpxmlTarget): Promise<{
154
+ sessionId: string;
155
+ mutating: boolean;
156
+ sessionState: import("../../../packages/runtime/src/index.js").EditingSessionState;
157
+ target: TimelineIrToFcpxmlTarget;
158
+ destination: {
159
+ mode: "versioned" | "reuse-existing";
160
+ projectUid: string;
161
+ sequenceUid: string;
162
+ projectName: string;
163
+ sequenceName: string;
164
+ };
165
+ collisionPolicy: string;
166
+ artifactDigest: string;
167
+ coverage: TimelineIrMaterializationCoverage;
168
+ provenance: TimelineIrMaterializationProvenance;
169
+ evidence: {
170
+ artifact: {
171
+ verified: boolean;
172
+ format: "fcpxml";
173
+ digest: string;
174
+ };
175
+ };
176
+ }>;
177
+ execute(sessionId: string, target: TimelineIrToFcpxmlTarget, confirm: boolean): Promise<SessionMaterializationJob>;
178
+ status(jobId: string): Promise<SessionMaterializationJob>;
179
+ retry(jobId: string): Promise<SessionMaterializationJob>;
180
+ resync(jobId: string, sessionId: string): Promise<{
181
+ jobId: string;
182
+ state: "resynced";
183
+ sessionId: string;
184
+ changeSinceHandoff: "changed" | "unchanged" | "unknown";
185
+ canonicalTarget: {
186
+ libraryUid: string;
187
+ eventUid: string;
188
+ projectUid: string;
189
+ sequenceUid: string;
190
+ };
191
+ readbackDigest: string;
192
+ document: import("../../../packages/runtime/src/index.js").EditingSessionDocument;
193
+ delivery?: MaterializationDeliveryEvidence | undefined;
194
+ }>;
195
+ private attempt;
196
+ private validateStagedJob;
197
+ private claim;
198
+ private release;
199
+ private fail;
200
+ private save;
201
+ private jobPath;
202
+ private claimPath;
203
+ private assertProvider;
204
+ }
@@ -1,16 +1,19 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
3
3
  import { dirname, join } from "node:path";
4
+ import { types as utilTypes } from "node:util";
4
5
  import { timelineIrDigest, validateTimelineIr } from "../../../packages/runtime/src/index.js";
5
- import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ import { compileTimelineIrToFcpxml, FinalCutBackgroundMaterializationPublisher, validateFinalCutBackgroundMaterializationRequest, } from "../../../adapters/final-cut/typescript/src/index.js";
6
7
  export class SessionMaterializationJobs {
7
8
  directory;
8
9
  sessions;
9
10
  publisher;
10
- constructor(directory, sessions, publisher) {
11
+ recoveryGuard;
12
+ constructor(directory, sessions, publisher, recoveryGuard) {
11
13
  this.directory = directory;
12
14
  this.sessions = sessions;
13
15
  this.publisher = publisher;
16
+ this.recoveryGuard = recoveryGuard;
14
17
  }
15
18
  async preview(sessionId, target) {
16
19
  const session = await this.sessions.loadForMaterialization(sessionId);
@@ -168,12 +171,20 @@ export class SessionMaterializationJobs {
168
171
  const claim = await this.claim(job);
169
172
  if (!claim.owned)
170
173
  return claim.job;
171
- const claimed = claim.job;
174
+ let claimed = claim.job;
175
+ let reservation;
176
+ let providerRequested = false;
177
+ // Do not evaluate provider properties before acquiring the reservation.
178
+ let dispatched = false;
172
179
  try {
173
180
  const finalFailure = await this.validateStagedJob(claimed);
174
181
  if (finalFailure)
175
182
  return this.fail(claimed, finalFailure);
176
- const result = await this.publisher.publish({
183
+ if (claimed.destination.mode !== "versioned")
184
+ return this.fail(claimed, {
185
+ code: "MATERIALIZATION_DESTINATION_INVALID", message: "Versioned destination required", retryable: false, providerRequested: false,
186
+ });
187
+ const request = {
177
188
  jobId: claimed.jobId,
178
189
  artifactPath: claimed.artifactPath,
179
190
  artifactDigest: claimed.artifactDigest,
@@ -186,12 +197,85 @@ export class SessionMaterializationJobs {
186
197
  baseRevision: structuredClone(claimed.baseRevision),
187
198
  coverage: structuredClone(claimed.coverage),
188
199
  provenance: structuredClone(claimed.provenance),
189
- });
200
+ };
201
+ try {
202
+ // The built-in adapter's pure request checks must run before the
203
+ // dispatch boundary, while the staged request is still inert data.
204
+ validateFinalCutBackgroundMaterializationRequest(request);
205
+ }
206
+ catch (error) {
207
+ return this.fail(claimed, materializationFailure(error, false));
208
+ }
209
+ // This check invokes no provider operation and is limited to the exact
210
+ // built-in implementation. Custom providers remain untrusted.
211
+ if (hasInertUnavailableMaterializationOptions(this.publisher)) {
212
+ const blocked = {
213
+ ...claimed, state: "blocked", nextAction: "retry", claim: undefined,
214
+ verification: { tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest,
215
+ desiredDigest: claimed.desiredDigest, reason: "No non-UI materialization capability is configured; the provider was not called" },
216
+ error: { code: "FINAL_CUT_BACKGROUND_MATERIALIZATION_UNAVAILABLE", message: "No explicit non-UI Final Cut materialization capability is configured", retryable: true },
217
+ };
218
+ await this.save(blocked);
219
+ return blocked;
220
+ }
221
+ if (this.recoveryGuard) {
222
+ try {
223
+ const id = createHash("sha256").update(claimed.jobId).digest("hex");
224
+ reservation = await this.recoveryGuard.beginNative(`native.materialize.${id}`, {
225
+ kind: "materialization", jobId: claimed.jobId, dispatchId: randomUUID(),
226
+ requestedTarget: { libraryUid: claimed.target.libraryUid, eventUid: claimed.target.eventUid,
227
+ projectUid: claimed.target.projectUid, sequenceUid: claimed.target.sequenceUid },
228
+ artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
229
+ destination: { ...structuredClone(claimed.destination), mode: "versioned" },
230
+ executorIdentity: null, nativeQuiescence: "unproven",
231
+ });
232
+ }
233
+ catch {
234
+ const blocked = {
235
+ ...claimed, state: "blocked", nextAction: "retry", claim: undefined,
236
+ verification: {
237
+ tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
238
+ reason: "An unresolved native reservation prevents materialization; the provider was not called",
239
+ },
240
+ error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "An unresolved native reservation prevents materialization; the provider was not called", retryable: true },
241
+ };
242
+ await this.save(blocked);
243
+ return blocked;
244
+ }
245
+ claimed = { ...claimed, recoveryReservation: { reservationId: reservation.reservationId, reason: "native-quiescence-unproven" } };
246
+ await this.save(claimed);
247
+ }
248
+ const invoke = async () => {
249
+ const intent = {
250
+ ...claimed, providerRequestPhase: "dispatch-intent",
251
+ evidence: { ...claimed.evidence, providerRequested: true },
252
+ };
253
+ await this.save(intent);
254
+ claimed = intent;
255
+ providerRequested = true;
256
+ return this.publisher.publish(request);
257
+ };
258
+ // A tracker is executable provider code. It may defer invoking the
259
+ // supplied operation even if it returns or throws first.
260
+ dispatched = true;
261
+ // Persist uncertainty before executing even the tracker: untrusted
262
+ // tracker code may invoke or defer the provider without acknowledgement.
263
+ if (reservation)
264
+ await reservation.markDispatchPossible();
265
+ const result = this.publisher.trackNativeDispatch
266
+ ? await this.publisher.trackNativeDispatch(invoke, () => { dispatched = true; })
267
+ : await invoke();
268
+ claimed = { ...claimed, providerRequestPhase: "returned" };
269
+ if (reservation && !providerRequested && !dispatched) {
270
+ await reservation.release();
271
+ reservation = undefined;
272
+ claimed = { ...claimed, recoveryReservation: undefined };
273
+ }
190
274
  if (result.state === "blocked") {
191
275
  const blocked = {
192
276
  ...claimed,
193
277
  state: "blocked",
194
- nextAction: "retry",
278
+ nextAction: claimed.recoveryReservation ? "none" : "retry",
195
279
  claim: undefined,
196
280
  evidence: { ...claimed.evidence, providerRequested: true },
197
281
  verification: {
@@ -202,7 +286,10 @@ export class SessionMaterializationJobs {
202
286
  reason: result.message,
203
287
  ...(result.delivery ? { delivery: result.delivery } : { delivery: deliveryEvidenceForBlockedCode(result.code) }),
204
288
  },
205
- error: { code: result.code, message: result.message, retryable: result.retryable },
289
+ ...(claimed.recoveryReservation ? { providerError: { code: result.code, message: result.message, retryable: result.retryable } } : {}),
290
+ error: claimed.recoveryReservation
291
+ ? { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Materialization may have been dispatched; native quiescence is unproven and it must not be retried", retryable: false }
292
+ : { code: result.code, message: result.message, retryable: result.retryable },
206
293
  };
207
294
  await this.save(blocked);
208
295
  return blocked;
@@ -260,11 +347,22 @@ export class SessionMaterializationJobs {
260
347
  reason: "Canonical readback verified this handoff once. Re-read the materialized target before later edits to detect subsequent manual Final Cut changes.",
261
348
  },
262
349
  };
263
- await this.save(completed);
264
- return completed;
350
+ const outcome = claimed.recoveryReservation
351
+ ? {
352
+ ...completed, state: "blocked", nextAction: "none",
353
+ error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Canonical readback was verified but native quiescence is unproven; do not retry publication", retryable: false },
354
+ continuation: { state: "canonical-resync-required", reason: "Recovery is required before a fresh canonical session can be created from this verified readback." },
355
+ }
356
+ : completed;
357
+ await this.save(outcome);
358
+ return outcome;
265
359
  }
266
360
  catch (error) {
267
- return this.fail(claimed, materializationFailure(error, true));
361
+ if (reservation && !providerRequested && !dispatched) {
362
+ await reservation.release();
363
+ claimed = { ...claimed, recoveryReservation: undefined };
364
+ }
365
+ return this.fail(claimed, materializationFailure(error, providerRequested || claimed.evidence.providerRequested));
268
366
  }
269
367
  finally {
270
368
  await this.release(claimed.jobId, claimed.claim.id);
@@ -538,6 +636,41 @@ function collectStructuralChanges(before, after, path, changes) {
538
636
  }
539
637
  changes.push({ path, ...(before !== undefined ? { before } : {}), ...(after !== undefined ? { after } : {}) });
540
638
  }
639
+ // Only inspect own data properties on ordinary, non-proxy objects. Calling
640
+ // isAvailable() here could execute a caller-supplied getter before a native
641
+ // reservation exists, so every unfamiliar shape must take the guarded path.
642
+ const builtinStringTrim = String.prototype.trim;
643
+ const builtinMaterializationMethods = new Map([
644
+ ["publish", FinalCutBackgroundMaterializationPublisher.prototype.publish],
645
+ ["trackNativeDispatch", FinalCutBackgroundMaterializationPublisher.prototype.trackNativeDispatch],
646
+ ["isAvailable", FinalCutBackgroundMaterializationPublisher.prototype.isAvailable],
647
+ ]);
648
+ function hasInertUnavailableMaterializationOptions(publisher) {
649
+ if (utilTypes.isProxy(publisher) || Object.getPrototypeOf(publisher) !== FinalCutBackgroundMaterializationPublisher.prototype)
650
+ return false;
651
+ for (const [name, method] of builtinMaterializationMethods) {
652
+ if (Object.getOwnPropertyDescriptor(publisher, name)
653
+ || Object.getOwnPropertyDescriptor(FinalCutBackgroundMaterializationPublisher.prototype, name)?.value !== method)
654
+ return false;
655
+ }
656
+ const optionsProperty = Object.getOwnPropertyDescriptor(publisher, "options");
657
+ if (!optionsProperty || !("value" in optionsProperty))
658
+ return false;
659
+ const options = optionsProperty.value;
660
+ if (!options || typeof options !== "object" || utilTypes.isProxy(options))
661
+ return false;
662
+ const prototype = Object.getPrototypeOf(options);
663
+ if (prototype !== null && prototype !== Object.prototype)
664
+ return false;
665
+ if (prototype && (Object.getOwnPropertyDescriptor(prototype, "executor") || Object.getOwnPropertyDescriptor(prototype, "command")))
666
+ return false;
667
+ const executor = Object.getOwnPropertyDescriptor(options, "executor");
668
+ const command = Object.getOwnPropertyDescriptor(options, "command");
669
+ if ((executor && (!("value" in executor) || executor.value !== undefined)) || (command && !("value" in command)))
670
+ return false;
671
+ const value = command?.value;
672
+ return value === undefined || value === null || (typeof value === "string" && builtinStringTrim.call(value) === "");
673
+ }
541
674
  function isRecord(value) {
542
675
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
543
676
  }
@@ -0,0 +1,18 @@
1
+ import type { EditingSessionState } from "../../../packages/runtime/src/index.js";
2
+ export type TimelineReadbackRoute = "session" | "fast-observation" | "canonical-resync";
3
+ export interface TimelineReadbackRequest {
4
+ hasCanonicalBase: boolean;
5
+ requestedCanonical: boolean;
6
+ finalVerification: boolean;
7
+ sessionState: EditingSessionState;
8
+ fastObservation?: {
9
+ available: boolean;
10
+ coverageComplete: boolean;
11
+ status: "unchanged" | "advanced-by-framekit" | "proven-structural-delta" | "possibly-stale" | "conflicted" | "canonical-resync-required" | "target-mismatch" | "provider-incompatible" | "unavailable";
12
+ };
13
+ }
14
+ export interface TimelineReadbackDecision {
15
+ route: TimelineReadbackRoute;
16
+ reason: string;
17
+ }
18
+ export declare function chooseTimelineReadback(request: TimelineReadbackRequest): TimelineReadbackDecision;
@@ -0,0 +1,90 @@
1
+ import type { CapabilityGuarantee, EditorIdentity, RuntimeCapabilities } from "../../../packages/runtime/src/index.js";
2
+ export type EditingRouteOperation = "project.list" | "project.select" | "project.inspect" | "timeline.inspect" | "editor.live.inspect" | "timeline.edit" | "timeline.mask.add" | "editor.native.edit" | "editor.native.picture-in-picture" | "artifact.edit" | "timeline.publish.new-project" | "timeline.export";
3
+ export type EditingRouteFallback = "none" | "external-renderer";
4
+ export type CapabilityUnavailableCategory = "background-api" | "canonical-snapshot" | "native-ui";
5
+ export declare const HEADLESS_TIMELINE_EDIT_TYPES: readonly ["insert-occurrence", "rename-occurrence", "trim-occurrence", "move-occurrence", "split-occurrence", "set-gain", "set-transform", "remove-occurrence", "add-marker", "add-title", "remove-title", "add-transition", "remove-transition"];
6
+ export declare const EDITING_ROUTE_EDIT_TYPES: readonly ["insert-occurrence", "rename-occurrence", "trim-occurrence", "move-occurrence", "split-occurrence", "set-gain", "set-transform", "remove-occurrence", "add-marker", "add-title", "remove-title", "add-transition", "remove-transition", "rename-clip", "trim-clip", "reduce-noise", "set-color-correction", "ripple-delete"];
7
+ export type EditingRouteEditType = (typeof EDITING_ROUTE_EDIT_TYPES)[number];
8
+ export interface EditingRouteRequest {
9
+ operation: EditingRouteOperation;
10
+ fallback?: EditingRouteFallback;
11
+ /** Select the headless SSoT or explicitly opt into a headed editor path. */
12
+ path?: "headless" | "headed";
13
+ /** Identify the concrete timeline edit for capability-granular headless routing. */
14
+ editType?: EditingRouteEditType;
15
+ }
16
+ export interface EditorRoutingContext {
17
+ connection: {
18
+ state: string;
19
+ lastError?: {
20
+ code: string;
21
+ message: string;
22
+ };
23
+ };
24
+ editor?: {
25
+ identity: EditorIdentity;
26
+ capabilities: RuntimeCapabilities;
27
+ };
28
+ native?: Record<string, boolean>;
29
+ nativeReadiness?: NativeRoutingReadiness;
30
+ headless?: {
31
+ available: boolean;
32
+ backend: string;
33
+ guarantee: CapabilityGuarantee;
34
+ supportedOperations: string[];
35
+ };
36
+ }
37
+ export interface NativeRoutingReadiness {
38
+ state: "ready" | "unavailable" | "timeout" | "cancelled" | "stale";
39
+ nextAction: "none" | "retry" | "queue" | "unavailable";
40
+ retryable: boolean;
41
+ firstMissing?: string;
42
+ frontmost: boolean;
43
+ timelineFocus: boolean;
44
+ selectedTarget: boolean;
45
+ targetKind?: "selected-clip" | "browser-media" | "playhead" | "unknown" | "none";
46
+ targetBound?: boolean;
47
+ overlay: "clear" | "blocked" | "unknown";
48
+ permission: "granted" | "required" | "unknown";
49
+ guidance: string;
50
+ undo: "available" | "unavailable" | "unknown";
51
+ }
52
+ export interface EditingRouteProvider {
53
+ backend: string;
54
+ guarantee: CapabilityGuarantee;
55
+ }
56
+ export interface EditingRouteReason {
57
+ code: "EDITOR_SELECTED" | "EDITOR_UNAVAILABLE" | "CAPABILITY_UNAVAILABLE" | "EXTERNAL_FALLBACK_SELECTED" | "HEADLESS_SELECTED" | "HEADLESS_UNAVAILABLE";
58
+ message: string;
59
+ connectionState: string;
60
+ cause?: {
61
+ code: string;
62
+ message: string;
63
+ };
64
+ unavailable?: {
65
+ category: CapabilityUnavailableCategory;
66
+ capability: string;
67
+ backend: string;
68
+ guarantee: CapabilityGuarantee;
69
+ message: string;
70
+ };
71
+ }
72
+ export interface EditingRoute {
73
+ operation: EditingRouteOperation;
74
+ status: "editor-selected" | "headless-selected" | "external-fallback-selected" | "unavailable";
75
+ selectedPath: "editor" | "headless" | "artifact" | "background" | "native" | "external-renderer" | "none";
76
+ requiredCapabilities: string[];
77
+ missingCapabilities: string[];
78
+ provider?: EditingRouteProvider;
79
+ readiness?: Pick<NativeRoutingReadiness, "state" | "nextAction" | "retryable" | "firstMissing" | "targetKind" | "targetBound" | "guidance">;
80
+ editor?: EditorIdentity;
81
+ workflow: string[];
82
+ reason: EditingRouteReason;
83
+ }
84
+ export declare const EDITOR_FIRST_WORKFLOW: string[];
85
+ export declare const HEADLESS_FIRST_WORKFLOW: string[];
86
+ export declare const BACKGROUND_LIBRARY_WORKFLOW: string[];
87
+ export declare const BACKGROUND_ARTIFACT_WORKFLOW: string[];
88
+ export declare const EDITOR_FIRST_MCP_INSTRUCTIONS: string;
89
+ export declare const HEADLESS_FIRST_MCP_INSTRUCTIONS: string;
90
+ export declare function resolveEditingRoute(request: EditingRouteRequest, context: EditorRoutingContext): EditingRoute;
@@ -250,6 +250,8 @@ function routingReadiness(context) {
250
250
  nextAction: readiness.nextAction,
251
251
  retryable: readiness.retryable,
252
252
  ...(readiness.firstMissing ? { firstMissing: readiness.firstMissing } : {}),
253
+ ...(readiness.targetKind ? { targetKind: readiness.targetKind } : {}),
254
+ ...(readiness.targetBound !== undefined ? { targetBound: readiness.targetBound } : {}),
253
255
  guidance: readiness.guidance,
254
256
  };
255
257
  }
@@ -0,0 +1,75 @@
1
+ import type { SessionSqliteObservationProvider } from "./headless-sessions.js";
2
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
+ import { AgentVideoRuntime, type CapabilityProcessMode, type CapabilityPreflight, type EditorIdentity } from "../../../packages/runtime/src/index.js";
4
+ import { type BackgroundRenderExportProvider, type DisposableNativeEditWorkflow, type FinalCutProjectPublishJobState, FinalCutProjectPublisher, type FileCanonicalRecoveryGuard, type FinalCutVideoExporter, type NativeFinalCutEditor, type NativeOperationSession } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { type BuildAlignmentReport } from "./build-alignment.js";
6
+ import { type FramekitBuildFingerprint } from "./version.js";
7
+ import { type EditingSessionChangeSource } from "./headless-sessions.js";
8
+ import { type SessionMaterializationPublisher } from "./materialization-jobs.js";
9
+ import { type HeadlessProjectWorkflow } from "../../../packages/headless-application/src/index.js";
10
+ export type { SessionMaterializationPublisher } from "./materialization-jobs.js";
11
+ export interface McpConnectionStatus {
12
+ state: string;
13
+ lastError?: {
14
+ code: string;
15
+ message: string;
16
+ };
17
+ editorDetected?: boolean;
18
+ extensionInstalled?: boolean;
19
+ socketPath?: string | null;
20
+ identity?: EditorIdentity;
21
+ capabilities?: unknown;
22
+ preflight?: McpCapabilityPreflight;
23
+ }
24
+ export interface McpCapabilityPreflight extends CapabilityPreflight {
25
+ fingerprint: FramekitBuildFingerprint;
26
+ buildAlignment: BuildAlignmentReport;
27
+ nativeHandoffReadiness: NativeHandoffReadiness;
28
+ }
29
+ export interface NativeHandoffReadiness {
30
+ status: "ready" | "blocked" | "verified";
31
+ reasons: Array<{
32
+ code: string;
33
+ message: string;
34
+ }>;
35
+ targetBinding: {
36
+ available: boolean;
37
+ guarantee: "native-readback" | "none";
38
+ };
39
+ buildAlignment: BuildAlignmentReport;
40
+ publish?: {
41
+ jobId: string;
42
+ state: FinalCutProjectPublishJobState;
43
+ };
44
+ createdTarget?: {
45
+ kind: "editor.project";
46
+ projectId: string;
47
+ sequenceId: string;
48
+ libraryId?: string;
49
+ eventId?: string;
50
+ libraryPath?: string;
51
+ projectName: string;
52
+ sequenceName?: string;
53
+ };
54
+ }
55
+ export interface McpServerOptions {
56
+ processMode?: CapabilityProcessMode;
57
+ connectionStatus?: () => McpConnectionStatus | undefined | Promise<McpConnectionStatus | undefined>;
58
+ nativeEditor?: NativeFinalCutEditor;
59
+ disposableNative?: Pick<DisposableNativeEditWorkflow, "preview" | "execute" | "undo">;
60
+ nativeOperationSession?: Pick<NativeOperationSession, "submit" | "status" | "retry" | "cancel">;
61
+ projectPublisher?: FinalCutProjectPublisher;
62
+ canonicalRecovery?: Pick<FileCanonicalRecoveryGuard, "inspectVersioned" | "inspectNativeReservation" | "assertClear" | "beginNative"> & Partial<Pick<FileCanonicalRecoveryGuard, "inspectNativeRecoveryEvidence">>;
63
+ videoExporter?: FinalCutVideoExporter;
64
+ backgroundRenderer?: BackgroundRenderExportProvider;
65
+ buildFingerprint?: FramekitBuildFingerprint;
66
+ requireBuildAlignment?: boolean;
67
+ validationCommit?: string;
68
+ sessionDirectory?: string;
69
+ sessionChangeSource?: EditingSessionChangeSource;
70
+ sqliteObservationProvider?: SessionSqliteObservationProvider;
71
+ materializationDirectory?: string;
72
+ sessionMaterializationPublisher?: SessionMaterializationPublisher;
73
+ headlessProjects?: HeadlessProjectWorkflow;
74
+ }
75
+ export declare function createMcpServer(runtime: AgentVideoRuntime, options?: McpServerOptions): McpServer;