@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
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  <p align="center">
6
6
  <img src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white" alt="Node.js 20 or newer" />
7
- <img src="https://img.shields.io/badge/pnpm-12.3.4-F69220?logo=pnpm&logoColor=white" alt="pnpm 12.3.4" />
7
+ <img src="https://img.shields.io/badge/pnpm-12.18.0-F69220?logo=pnpm&logoColor=white" alt="pnpm 12.18.0" />
8
8
  <img src="https://img.shields.io/badge/Final%20Cut%20Pro-macOS-000000?logo=apple&logoColor=white" alt="Final Cut Pro on macOS" />
9
9
  <a href="https://discord.gg/Dmp8FSF4vg"><img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Join the Framekit Discord" /></a>
10
10
  </p>
@@ -17,12 +17,16 @@ Agentic video editing runtime and MCP server for Final Cut Pro.
17
17
 
18
18
  For repository development, you need:
19
19
 
20
- - Node.js 20 or newer;
21
- - pnpm 12.3.4;
22
- - Xcode 16.4 and the macOS 15.5 SDK for native Final Cut work.
20
+ Contributor toolchain: Node.js 22.23.5 and pnpm 12.18.0.
21
+ Consumer runtime: Node.js >=20.
22
+ CI tests this contributor pair; the pre-commit hook accepts Node.js 22.23 or newer.
23
+ Install pnpm 12.18.0 using Corepack or your preferred package manager.
23
24
 
24
- The Xcode requirement is only needed for the native Workflow Extension. For the
25
- pinned Node and shell toolchain, enter the optional Nix shell first:
25
+ Xcode 16.4 and the macOS 15.5 SDK are required for native Final Cut work.
26
+
27
+ The Xcode requirement is only needed for the native Workflow Extension. The
28
+ optional Nix shell provides Node.js 22, pinned pnpm, FFmpeg/ffprobe, and SQLite
29
+ for fixture and headless work:
26
30
 
27
31
  ```sh
28
32
  nix develop ./nix
@@ -48,8 +52,8 @@ stdio. Start it from the repository root and connect it to an MCP client:
48
52
  pnpm run mcp
49
53
  ```
50
54
 
51
- See the [MCP tools](./docs/mcp/tools.md) and [MCP documentation](./docs/mcp/README.md)
52
- for the tool inventory and live-backend setup.
55
+ See [Getting started](./docs/getting-started.md) for local and live-backend
56
+ setup, and [Architecture](./docs/architecture.md) for capability boundaries.
53
57
 
54
58
  ## Connect Codex to Final Cut
55
59
 
@@ -74,8 +78,8 @@ approved rough-cut plan, and render a verified MP4 plus editable FCPXML without
74
78
  a connected Final Cut session. Optional native publishing is experimental and
75
79
  is not guaranteed in v0.1.18: a document-open dispatch does not prove that
76
80
  Final Cut completed an import or created a native project. See the
77
- [Codex video production runbook](./docs/tests/codex-video-production-e2e.md)
78
- and [first-run setup and capability boundaries](./docs/final-cut/installation.md).
81
+ [Codex video production runbook](./plugins/framekit/references/tests/codex-video-production-e2e.md)
82
+ and [first-run setup and capability boundaries](./docs/getting-started.md).
79
83
 
80
84
  For local native development, use the checkout's CLI wrapper from the repository
81
85
  root:
@@ -90,8 +94,9 @@ pnpm run framekit -- connect finalcut --development
90
94
 
91
95
  - [Documentation index](./docs/README.md)
92
96
  - [Getting started](./docs/getting-started.md)
93
- - [Architecture](./docs/ARCHITECTURE.md)
94
- - [Clean Codex and Claude Code MCP validation](./docs/tests/clean-mcp-clients.md)
97
+ - [Architecture](./docs/architecture.md)
98
+ - [Testing](./docs/testing.md)
99
+ - [Release](./docs/release.md)
95
100
 
96
101
  ## Development
97
102
 
@@ -0,0 +1,58 @@
1
+ import type { AnalysisInput, AudioAnalysis, AudioAnalyzer, AnalyzerDescriptor, MetadataAnalysis, MetadataAnalyzer, SpeechAnalysis, SpeechAnalyzer, TimeRange, VisualAnalysis, VisualAnalyzer } from "../../../../packages/runtime/src/index.js";
2
+ export interface CommandAnalyzerOptions {
3
+ command: string;
4
+ timeoutMs?: number;
5
+ providerVersion?: string;
6
+ requireVad?: boolean;
7
+ }
8
+ export declare function createCommandAnalyzers(options: {
9
+ speechCommand?: string;
10
+ speechProviderVersion?: string;
11
+ speechRequireVad?: boolean;
12
+ audioCommand?: string;
13
+ visualCommand?: string;
14
+ metadataCommand?: string;
15
+ timeoutMs?: number;
16
+ }): {
17
+ speechAnalyzer?: SpeechAnalyzer;
18
+ audioAnalyzer?: AudioAnalyzer;
19
+ visualAnalyzer?: VisualAnalyzer;
20
+ metadataAnalyzer?: MetadataAnalyzer;
21
+ };
22
+ export declare class CommandSpeechAnalyzer implements SpeechAnalyzer {
23
+ private readonly options;
24
+ readonly descriptor: AnalyzerDescriptor;
25
+ readonly capabilities: {
26
+ transcription: true;
27
+ vad: boolean;
28
+ };
29
+ constructor(options: CommandAnalyzerOptions);
30
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<SpeechAnalysis>;
31
+ }
32
+ export declare class CommandAudioAnalyzer implements AudioAnalyzer {
33
+ private readonly options;
34
+ readonly descriptor: {
35
+ id: string;
36
+ provider: string;
37
+ };
38
+ constructor(options: CommandAnalyzerOptions);
39
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<AudioAnalysis>;
40
+ }
41
+ export declare class CommandVisualAnalyzer implements VisualAnalyzer {
42
+ private readonly options;
43
+ readonly descriptor: {
44
+ id: string;
45
+ provider: string;
46
+ };
47
+ constructor(options: CommandAnalyzerOptions);
48
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<VisualAnalysis>;
49
+ }
50
+ export declare class CommandMetadataAnalyzer implements MetadataAnalyzer {
51
+ private readonly options;
52
+ readonly descriptor: {
53
+ id: string;
54
+ provider: string;
55
+ };
56
+ constructor(options: CommandAnalyzerOptions);
57
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<MetadataAnalysis>;
58
+ }
@@ -1,6 +1,7 @@
1
1
  import { spawn } from "node:child_process";
2
- import { access } from "node:fs/promises";
3
- import { bindSpeechAnalysis, sameMediaSourceIdentity } from "../../../../packages/runtime/src/index.js";
2
+ import { createHash } from "node:crypto";
3
+ import { createReadStream } from "node:fs";
4
+ import { bindSpeechAnalysis, sameMediaSourceIdentity, validateAudioAnalysisPayload } from "../../../../packages/runtime/src/index.js";
4
5
  export function createCommandAnalyzers(options) {
5
6
  return {
6
7
  ...(options.speechCommand ? {
@@ -81,18 +82,17 @@ export class CommandMetadataAnalyzer {
81
82
  }
82
83
  async function runCommand(options, request, kind) {
83
84
  const source = request.media.source;
84
- try {
85
- await access(source);
86
- }
87
- catch {
88
- throw new Error(`ANALYZER_MEDIA_UNAVAILABLE: ${kind} source is not readable: ${source}`);
89
- }
90
85
  const timeoutMs = options.timeoutMs ?? 120_000;
86
+ const initialDigest = await digestAnalyzerSource(source, kind, timeoutMs);
87
+ const expectedDigest = request.media.sourceDigest?.replace(/^sha256:/, "");
88
+ if (expectedDigest !== undefined && expectedDigest !== initialDigest) {
89
+ throw new Error(`ANALYZER_SOURCE_CHANGED: ${kind} source bytes do not match the requested source digest`);
90
+ }
91
91
  const child = spawn(options.command, [], { stdio: ["pipe", "pipe", "pipe"] });
92
92
  const stdout = [];
93
93
  const stderr = [];
94
94
  let settled = false;
95
- return new Promise((resolve, reject) => {
95
+ const result = await new Promise((resolve, reject) => {
96
96
  const timer = setTimeout(() => {
97
97
  if (settled)
98
98
  return;
@@ -121,7 +121,7 @@ async function runCommand(options, request, kind) {
121
121
  }
122
122
  try {
123
123
  const value = JSON.parse(Buffer.concat(stdout).toString("utf8"));
124
- validateResult(value, kind);
124
+ validateResult(value, kind, request);
125
125
  resolve(value);
126
126
  }
127
127
  catch (error) {
@@ -130,6 +130,42 @@ async function runCommand(options, request, kind) {
130
130
  });
131
131
  child.stdin.end(JSON.stringify(commandRequest(request, kind)));
132
132
  });
133
+ if (await digestAnalyzerSource(source, kind, timeoutMs) !== initialDigest) {
134
+ throw new Error(`ANALYZER_SOURCE_CHANGED: ${kind} source bytes changed while analysis was running`);
135
+ }
136
+ return result;
137
+ }
138
+ async function digestAnalyzerSource(source, kind, timeoutMs) {
139
+ const stream = createReadStream(source);
140
+ let timedOut = false;
141
+ let timer;
142
+ try {
143
+ return await Promise.race([
144
+ (async () => {
145
+ const digest = createHash("sha256");
146
+ for await (const chunk of stream)
147
+ digest.update(chunk);
148
+ return digest.digest("hex");
149
+ })(),
150
+ new Promise((_resolve, reject) => {
151
+ timer = setTimeout(() => {
152
+ timedOut = true;
153
+ stream.destroy();
154
+ reject(new Error(`ANALYZER_TIMEOUT: ${kind} source verification exceeded ${timeoutMs}ms`));
155
+ }, timeoutMs);
156
+ }),
157
+ ]);
158
+ }
159
+ catch {
160
+ if (timedOut)
161
+ throw new Error(`ANALYZER_TIMEOUT: ${kind} source verification exceeded ${timeoutMs}ms`);
162
+ throw new Error(`ANALYZER_MEDIA_UNAVAILABLE: ${kind} source cannot be read for content verification: ${source}`);
163
+ }
164
+ finally {
165
+ if (timer)
166
+ clearTimeout(timer);
167
+ stream.destroy();
168
+ }
133
169
  }
134
170
  function commandRequest(request, kind) {
135
171
  if (kind !== "speech")
@@ -190,7 +226,7 @@ function sameRange(value, expected) {
190
226
  const range = value;
191
227
  return range.start === expected.start && range.end === expected.end;
192
228
  }
193
- function validateResult(value, kind) {
229
+ function validateResult(value, kind, request) {
194
230
  if (!value || typeof value !== "object")
195
231
  throw new Error("result must be an object");
196
232
  const record = value;
@@ -200,8 +236,11 @@ function validateResult(value, kind) {
200
236
  return;
201
237
  }
202
238
  if (kind === "audio") {
203
- if (!["integratedLufs", "truePeakDb", "silenceMs"].every((key) => typeof record[key] === "number"))
204
- throw new Error("audio result requires loudness fields");
239
+ validateAudioAnalysisPayload(value);
240
+ if (record.signalScope === "occurrence"
241
+ && (!request.occurrenceId || record.occurrenceId !== request.occurrenceId)) {
242
+ throw new Error("audio occurrence identity does not match the requested occurrence");
243
+ }
205
244
  return;
206
245
  }
207
246
  if (kind === "metadata") {
@@ -0,0 +1,24 @@
1
+ import type { AssetSearchQuery, EditorAsset } from "../../../../packages/runtime/src/index.js";
2
+ import type { NativeFinalCutTitleMatch, NativeFinalCutTransitionMatch } from "./native.js";
3
+ export interface FinalCutAssetRegistryOptions {
4
+ roots?: string[];
5
+ nativeTitleProvider?: Pick<NativeTitleProvider, "searchTitles">;
6
+ nativeTransitionProvider?: Pick<NativeTransitionProvider, "searchTransitions">;
7
+ }
8
+ export interface NativeTitleProvider {
9
+ searchTitles(query: string): Promise<NativeFinalCutTitleMatch[]>;
10
+ }
11
+ export interface NativeTransitionProvider {
12
+ searchTransitions(query: string): Promise<NativeFinalCutTransitionMatch[]>;
13
+ }
14
+ export declare function defaultFinalCutAssetRoots(): string[];
15
+ export declare class FinalCutAssetRegistry {
16
+ private readonly roots;
17
+ private readonly nativeTitleProvider?;
18
+ private readonly nativeTransitionProvider?;
19
+ private cached?;
20
+ constructor(options?: FinalCutAssetRegistryOptions);
21
+ listAssets(query?: AssetSearchQuery): Promise<EditorAsset[]>;
22
+ refresh(): void;
23
+ private scan;
24
+ }
@@ -0,0 +1,98 @@
1
+ import type { ContextRevision } from "../../../../packages/runtime/src/index.js";
2
+ export type BackgroundRenderSourceKind = "final-cut-timeline" | "fcpxml-artifact";
3
+ export interface BackgroundRenderTarget {
4
+ projectId: string;
5
+ sequenceId: string;
6
+ revision?: ContextRevision;
7
+ digest?: string;
8
+ }
9
+ export interface BackgroundRenderSource {
10
+ kind: BackgroundRenderSourceKind;
11
+ target: BackgroundRenderTarget;
12
+ artifactPath?: string;
13
+ }
14
+ export interface BackgroundRenderRequest {
15
+ source: BackgroundRenderSource;
16
+ outputPath: string;
17
+ preset: string;
18
+ overwrite?: boolean;
19
+ timeoutMs?: number;
20
+ }
21
+ export interface BackgroundRenderProbeResult {
22
+ durationSeconds: number;
23
+ width: number;
24
+ height: number;
25
+ frameRate: number;
26
+ hasAudio: boolean;
27
+ videoCodec?: string;
28
+ audioCodec?: string;
29
+ }
30
+ export interface BackgroundRenderMetadata extends BackgroundRenderProbeResult {
31
+ outputPath: string;
32
+ sizeBytes: number;
33
+ format: string;
34
+ outputDigest: string;
35
+ }
36
+ export type BackgroundRenderEvidenceTier = "background-native" | "artifact-rendered" | "external-rendered";
37
+ export interface BackgroundRenderProvenance {
38
+ renderer: "external-renderer";
39
+ evidenceTier: Exclude<BackgroundRenderEvidenceTier, "background-native">;
40
+ source: BackgroundRenderSource;
41
+ }
42
+ export interface BackgroundRenderResult {
43
+ jobId: string;
44
+ outputPath: string;
45
+ preset: string;
46
+ completed: true;
47
+ verified: true;
48
+ metadata: BackgroundRenderMetadata;
49
+ provenance: BackgroundRenderProvenance;
50
+ }
51
+ export type BackgroundRenderJobState = "queued" | "rendering" | "verifying" | "completed" | "cancelled" | "failed";
52
+ export interface BackgroundRenderJobStatus {
53
+ jobId: string;
54
+ state: BackgroundRenderJobState;
55
+ progress: number;
56
+ message: string;
57
+ error?: {
58
+ code: string;
59
+ message: string;
60
+ };
61
+ }
62
+ export interface BackgroundRenderExecutionContext {
63
+ request: BackgroundRenderRequest;
64
+ stagingPath: string;
65
+ signal: AbortSignal;
66
+ reportProgress(progress: number, message?: string): void;
67
+ }
68
+ export type BackgroundRenderExecutor = (context: BackgroundRenderExecutionContext) => Promise<void>;
69
+ export type BackgroundRenderProbe = (stagingPath: string) => Promise<BackgroundRenderProbeResult>;
70
+ export type BackgroundRenderProgressListener = (status: BackgroundRenderJobStatus) => void;
71
+ export interface BackgroundRenderJob {
72
+ readonly id: string;
73
+ status(): BackgroundRenderJobStatus;
74
+ onProgress(listener: BackgroundRenderProgressListener): () => void;
75
+ result(): Promise<BackgroundRenderResult>;
76
+ cancel(): Promise<void>;
77
+ }
78
+ export interface BackgroundRenderExportProviderOptions {
79
+ enabled?: boolean;
80
+ renderer?: BackgroundRenderExecutor;
81
+ probe?: BackgroundRenderProbe;
82
+ defaultTimeoutMs?: number;
83
+ }
84
+ /**
85
+ * Runs an injected background renderer against a staged output.
86
+ *
87
+ * This provider is intentionally external/artifact-derived. It does not invoke
88
+ * Final Cut UI and never labels its result as native Final Cut rendering.
89
+ */
90
+ export declare class BackgroundRenderExportProvider {
91
+ private readonly enabled;
92
+ private readonly renderer?;
93
+ private readonly probe?;
94
+ private readonly defaultTimeoutMs;
95
+ constructor(options?: BackgroundRenderExportProviderOptions);
96
+ isAvailable(): boolean;
97
+ start(request: BackgroundRenderRequest): BackgroundRenderJob;
98
+ }
@@ -0,0 +1,47 @@
1
+ import type { TimelineIr } from "../../../../packages/runtime/src/index.js";
2
+ import type { FinalCutTargetIdentity, TimelineIrMaterializationCoverage, TimelineIrMaterializationProvenance, TimelineIrToFcpxmlResult, TimelineIrToFcpxmlTarget } from "./timeline-ir-fcpxml.js";
3
+ export interface FinalCutBackgroundMaterializationRequest {
4
+ jobId: string;
5
+ artifactPath: string;
6
+ artifactDigest: string;
7
+ target: TimelineIrToFcpxmlTarget;
8
+ destination: TimelineIrToFcpxmlResult["destination"];
9
+ collisionPolicy: "create-only";
10
+ desired: TimelineIr;
11
+ desiredDigest: string;
12
+ baseDigest: string;
13
+ baseRevision: TimelineIr["revision"];
14
+ coverage: TimelineIrMaterializationCoverage;
15
+ provenance: TimelineIrMaterializationProvenance;
16
+ }
17
+ export type FinalCutBackgroundMaterializationResult = {
18
+ state: "completed";
19
+ canonicalReadback: TimelineIr;
20
+ canonicalTarget: FinalCutTargetIdentity;
21
+ headedNativeVerified: boolean;
22
+ } | {
23
+ state: "blocked";
24
+ code: string;
25
+ message: string;
26
+ retryable: boolean;
27
+ };
28
+ export interface FinalCutBackgroundMaterializationPublisherOptions {
29
+ executor?: (request: FinalCutBackgroundMaterializationRequest) => Promise<FinalCutBackgroundMaterializationResult>;
30
+ command?: string;
31
+ commandTimeoutMs?: number;
32
+ }
33
+ /**
34
+ * Publishes an immutable FCPXML artifact through an explicit non-UI Final Cut
35
+ * capability. The command owns Final Cut import and target-bound canonical
36
+ * readback; this adapter never activates Final Cut or falls back to UI calls.
37
+ */
38
+ export declare class FinalCutBackgroundMaterializationPublisher {
39
+ private readonly options;
40
+ private readonly dispatchContext;
41
+ private readonly commandTimeoutMs;
42
+ constructor(options?: FinalCutBackgroundMaterializationPublisherOptions);
43
+ isAvailable(): boolean;
44
+ trackNativeDispatch<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
45
+ publish(request: FinalCutBackgroundMaterializationRequest): Promise<FinalCutBackgroundMaterializationResult>;
46
+ }
47
+ export declare function validateFinalCutBackgroundMaterializationRequest(request: FinalCutBackgroundMaterializationRequest): void;
@@ -1,5 +1,6 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { spawn } from "node:child_process";
3
+ import { AsyncLocalStorage } from "node:async_hooks";
3
4
  import { readFile } from "node:fs/promises";
4
5
  import { timelineIrDigest, validateTimelineIr } from "../../../../packages/runtime/src/index.js";
5
6
  const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
@@ -10,6 +11,7 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
10
11
  */
11
12
  export class FinalCutBackgroundMaterializationPublisher {
12
13
  options;
14
+ dispatchContext = new AsyncLocalStorage();
13
15
  commandTimeoutMs;
14
16
  constructor(options = {}) {
15
17
  this.options = options;
@@ -21,8 +23,11 @@ export class FinalCutBackgroundMaterializationPublisher {
21
23
  isAvailable() {
22
24
  return this.options.executor !== undefined || Boolean(this.options.command?.trim());
23
25
  }
26
+ async trackNativeDispatch(operation, onDispatch) {
27
+ return this.dispatchContext.run(onDispatch, operation);
28
+ }
24
29
  async publish(request) {
25
- validateRequest(request);
30
+ validateFinalCutBackgroundMaterializationRequest(request);
26
31
  const executor = this.options.executor ?? (this.options.command?.trim()
27
32
  ? commandExecutor(this.options.command.trim(), this.commandTimeoutMs)
28
33
  : undefined);
@@ -41,11 +46,12 @@ export class FinalCutBackgroundMaterializationPublisher {
41
46
  if (timelineIrDigest(request.desired) !== request.desiredDigest) {
42
47
  throw new Error("MATERIALIZATION_DESIRED_SNAPSHOT_INVALID: the staged desired Timeline IR digest is invalid");
43
48
  }
49
+ this.dispatchContext.getStore()?.();
44
50
  const result = await executor({ ...request, desired: structuredClone(request.desired) });
45
51
  return validateResult(result);
46
52
  }
47
53
  }
48
- function validateRequest(request) {
54
+ export function validateFinalCutBackgroundMaterializationRequest(request) {
49
55
  if (!request.jobId.trim())
50
56
  throw new Error("MATERIALIZATION_REQUEST_INVALID: jobId is required");
51
57
  if (!request.artifactPath.trim() || !request.artifactDigest.trim()) {
@@ -0,0 +1,32 @@
1
+ import type { CanonicalRecoveryCheckpoint, CanonicalRecoveryGuard } from "./canonical.js";
2
+ import { type NativeMaterializationRecoveryContext, type NativePublishRecoveryContext } from "./native-recovery-inspection.js";
3
+ /** A durable, exclusive checkpoint; unresolved checkpoints are never cleared automatically. */
4
+ export declare class FileCanonicalRecoveryGuard implements CanonicalRecoveryGuard {
5
+ private readonly path;
6
+ private owner?;
7
+ constructor(path: string);
8
+ assertClear(): Promise<void>;
9
+ /** Read native reservation and sender evidence without acquiring or modifying locks. */
10
+ inspectNativeRecoveryEvidence(): Promise<import("./native-recovery-inspection.js").NativeRecoveryInspection>;
11
+ /** Return evidence only; inspection never clears or claims recovery. */
12
+ inspect(): Promise<CanonicalRecoveryCheckpoint | undefined>;
13
+ /** Inspect a direct native reservation without fabricating a canonical target. */
14
+ inspectNativeReservation(): Promise<{
15
+ reservationId: string;
16
+ operation: string;
17
+ } | undefined>;
18
+ /** Atomically reserve the same path used by canonical checkpoints. */
19
+ beginNative(operation: string, context?: NativeMaterializationRecoveryContext | NativePublishRecoveryContext): Promise<{
20
+ readonly reservationId: string;
21
+ markDispatchPossible(): Promise<void>;
22
+ bindRecoveryContext(context: NativeMaterializationRecoveryContext | NativePublishRecoveryContext): Promise<void>;
23
+ release(): Promise<void>;
24
+ }>;
25
+ inspectVersioned(): Promise<{
26
+ checkpointId: string;
27
+ checkpoint: CanonicalRecoveryCheckpoint;
28
+ } | undefined>;
29
+ begin(checkpoint: CanonicalRecoveryCheckpoint): Promise<void>;
30
+ complete(): Promise<void>;
31
+ private completeOwned;
32
+ }