@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,9 @@
1
+ import type { CompositeEditPreview, MusicAddRequest } from "../domain/editing.js";
2
+ import { EditService } from "./edit-service.js";
3
+ import { ProjectService } from "../application/project-service.js";
4
+ export declare class MusicService {
5
+ private readonly project;
6
+ private readonly edits;
7
+ constructor(project: ProjectService, edits: EditService);
8
+ previewMusic(request: MusicAddRequest): Promise<CompositeEditPreview>;
9
+ }
@@ -0,0 +1,32 @@
1
+ export * from "./domain/index.js";
2
+ export * from "./runtime.js";
3
+ export * from "./timeline/snapshot-diff.js";
4
+ export * from "./verification/verification.js";
5
+ export * from "./editing/intent.js";
6
+ export * from "./editing/duration-policy.js";
7
+ export * from "./capabilities.js";
8
+ export * from "./timeline/snapshot-digest.js";
9
+ export * from "./timeline/editing-session.js";
10
+ export * from "./render/render-contract.js";
11
+ export * from "./render/render-and-verify.js";
12
+ export * from "./timeline/drift-reconciliation.js";
13
+ export * from "./timeline/fast-observation.js";
14
+ export * from "./application/project-store.js";
15
+ export * from "./application/transaction-store.js";
16
+ export * from "./application/local-media.js";
17
+ export * from "./application/project-transactions.js";
18
+ export * from "./application/semantic-media-index-store.js";
19
+ export * from "./context/project-catalog.js";
20
+ export * from "./speech/filler-removal.js";
21
+ export * from "./audio/analysis.js";
22
+ export * from "./audio/dialogue-normalization.js";
23
+ export * from "./audio/noise-reduction.js";
24
+ export * from "./color-correction.js";
25
+ export * from "./domain/skills.js";
26
+ export * from "./skills/requirements.js";
27
+ export * from "./skills/index.js";
28
+ export type { RuntimeOptions } from "./application/runtime-options.js";
29
+ export * from "./speech/filler-detector.js";
30
+ export * from "./speech/safe-cut-resolver.js";
31
+ export * from "./speech/analysis.js";
32
+ export * from "./speech/mapping.js";
@@ -12,11 +12,13 @@ export * from "./render/render-and-verify.js";
12
12
  export * from "./timeline/drift-reconciliation.js";
13
13
  export * from "./timeline/fast-observation.js";
14
14
  export * from "./application/project-store.js";
15
+ export * from "./application/transaction-store.js";
15
16
  export * from "./application/local-media.js";
16
17
  export * from "./application/project-transactions.js";
17
18
  export * from "./application/semantic-media-index-store.js";
18
19
  export * from "./context/project-catalog.js";
19
20
  export * from "./speech/filler-removal.js";
21
+ export * from "./audio/analysis.js";
20
22
  export * from "./audio/dialogue-normalization.js";
21
23
  export * from "./audio/noise-reduction.js";
22
24
  export * from "./color-correction.js";
@@ -0,0 +1,3 @@
1
+ import type { MediaIndexEntry, RoughCutPlan, RoughCutPlanRequest } from "../domain/media.js";
2
+ import type { ContextRevision } from "../domain/primitives.js";
3
+ export declare function planRoughCut(entries: MediaIndexEntry[], revision: ContextRevision, request: RoughCutPlanRequest): RoughCutPlan;
@@ -0,0 +1,71 @@
1
+ import { type FramekitRenderCapabilityReport, type FramekitRenderPlan, type FramekitRenderProvider, type FramekitRenderProviderResult, type FramekitRenderRequest } from "./render-contract.js";
2
+ import type { RationalTime } from "../domain/primitives.js";
3
+ export type FramekitRenderVerificationStatus = "passed" | "failed" | "unavailable";
4
+ export interface FramekitRenderArtifactStream {
5
+ kind: "video" | "audio";
6
+ codec?: string;
7
+ width?: number;
8
+ height?: number;
9
+ frameRate?: RationalTime;
10
+ sampleRate?: number;
11
+ channels?: number;
12
+ }
13
+ export interface FramekitRenderArtifactMetadata {
14
+ path: string;
15
+ format: string;
16
+ sizeBytes: number;
17
+ fileDigest: string;
18
+ durationSeconds: number;
19
+ width: number;
20
+ height: number;
21
+ frameRate: RationalTime;
22
+ streams: FramekitRenderArtifactStream[];
23
+ }
24
+ export interface FramekitRenderVerificationCheck {
25
+ name: string;
26
+ passed: boolean;
27
+ detail: string;
28
+ expected?: unknown;
29
+ observed?: unknown;
30
+ }
31
+ export interface FramekitRenderVerificationResult {
32
+ status: FramekitRenderVerificationStatus;
33
+ checks: FramekitRenderVerificationCheck[];
34
+ artifact?: FramekitRenderArtifactMetadata;
35
+ error?: {
36
+ code: string;
37
+ message: string;
38
+ };
39
+ }
40
+ export interface FramekitRenderSemanticAssertionContext {
41
+ plan: FramekitRenderPlan;
42
+ result: FramekitRenderProviderResult;
43
+ artifact: FramekitRenderArtifactMetadata;
44
+ }
45
+ export interface FramekitRenderSemanticAssertion {
46
+ name: string;
47
+ verify(context: FramekitRenderSemanticAssertionContext): FramekitRenderVerificationCheck | boolean | Promise<FramekitRenderVerificationCheck | boolean>;
48
+ }
49
+ export interface FramekitRenderAndVerifyOptions {
50
+ capabilities?: FramekitRenderCapabilityReport;
51
+ semanticAssertions?: FramekitRenderSemanticAssertion[];
52
+ isUnavailable?: (error: unknown) => boolean;
53
+ }
54
+ export interface FramekitRenderAndVerifyResult {
55
+ status: FramekitRenderVerificationStatus;
56
+ plan?: FramekitRenderPlan;
57
+ render?: FramekitRenderProviderResult;
58
+ verification?: FramekitRenderVerificationResult;
59
+ error?: {
60
+ code: string;
61
+ message: string;
62
+ };
63
+ }
64
+ export interface FramekitRenderArtifactVerifier {
65
+ verify(plan: FramekitRenderPlan, result: FramekitRenderProviderResult): Promise<FramekitRenderVerificationResult>;
66
+ }
67
+ /**
68
+ * Owns the closed loop: immutable plan, provider render, then an independent
69
+ * artifact verification gate. Provider success alone never yields `passed`.
70
+ */
71
+ export declare function renderAndVerifyFramekitProject(request: FramekitRenderRequest, provider: FramekitRenderProvider, verifier: FramekitRenderArtifactVerifier, options?: FramekitRenderAndVerifyOptions): Promise<FramekitRenderAndVerifyResult>;
@@ -0,0 +1,96 @@
1
+ import type { ContextRevision, RationalTime } from "../domain/primitives.js";
2
+ import { type TimelineIr } from "../timeline/editing-session.js";
3
+ export declare const FRAMEKIT_RENDER_CONTRACT_VERSION: 1;
4
+ export type FramekitRenderFormat = "mp4" | "mov";
5
+ export type FramekitRenderFeature = "local-media" | "structural-edits" | "audio-gain" | "audio-mixing" | "transform" | "titles" | "cross-dissolve";
6
+ export type FramekitRenderCapabilityStatus = "supported" | "degraded" | "unsupported";
7
+ export interface FramekitRenderParameters {
8
+ outputPath: string;
9
+ format: FramekitRenderFormat;
10
+ width: number;
11
+ height: number;
12
+ frameRate: RationalTime;
13
+ overwrite?: boolean;
14
+ }
15
+ export interface FramekitRenderRequest {
16
+ contractVersion: typeof FRAMEKIT_RENDER_CONTRACT_VERSION;
17
+ target: {
18
+ projectId: string;
19
+ sequenceId: string;
20
+ };
21
+ projectRevision: ContextRevision;
22
+ timeline: TimelineIr;
23
+ parameters: FramekitRenderParameters;
24
+ requiredFeatures: FramekitRenderFeature[];
25
+ }
26
+ export interface FramekitRenderRequestInput {
27
+ timeline: TimelineIr;
28
+ target: {
29
+ projectId: string;
30
+ sequenceId: string;
31
+ };
32
+ revision?: ContextRevision;
33
+ parameters: FramekitRenderParameters;
34
+ requiredFeatures?: FramekitRenderFeature[];
35
+ }
36
+ export interface FramekitRenderCapabilityReport {
37
+ renderer: {
38
+ id: string;
39
+ version: string;
40
+ };
41
+ features: Partial<Record<FramekitRenderFeature, FramekitRenderCapabilityStatus>>;
42
+ }
43
+ export interface FramekitRenderPlan {
44
+ contractVersion: typeof FRAMEKIT_RENDER_CONTRACT_VERSION;
45
+ target: {
46
+ projectId: string;
47
+ sequenceId: string;
48
+ };
49
+ projectRevision: ContextRevision;
50
+ timeline: TimelineIr;
51
+ parameters: FramekitRenderParameters;
52
+ requiredFeatures: FramekitRenderFeature[];
53
+ renderer: {
54
+ id: string;
55
+ version: string;
56
+ };
57
+ capabilities: FramekitRenderCapabilityReport;
58
+ planDigest: string;
59
+ }
60
+ export interface FramekitRenderProviderResult {
61
+ contractVersion: typeof FRAMEKIT_RENDER_CONTRACT_VERSION;
62
+ status: "rendered";
63
+ target: {
64
+ projectId: string;
65
+ sequenceId: string;
66
+ };
67
+ projectRevision: ContextRevision;
68
+ renderer: {
69
+ id: string;
70
+ version: string;
71
+ };
72
+ planDigest: string;
73
+ output: {
74
+ path: string;
75
+ format: FramekitRenderFormat;
76
+ };
77
+ /** Rendering and independent artifact verification are separate gates. */
78
+ verificationRequired: true;
79
+ }
80
+ export interface FramekitRenderProvider {
81
+ readonly id: string;
82
+ readonly version: string;
83
+ capabilities(request: FramekitRenderRequest): FramekitRenderCapabilityReport;
84
+ render(plan: FramekitRenderPlan): Promise<FramekitRenderProviderResult>;
85
+ }
86
+ export declare class FramekitRenderContractError extends Error {
87
+ readonly code: "RENDER_INVALID_REQUEST" | "RENDER_STALE_REVISION" | "RENDER_CAPABILITY_UNAVAILABLE" | "RENDER_INVALID_RESULT";
88
+ constructor(code: "RENDER_INVALID_REQUEST" | "RENDER_STALE_REVISION" | "RENDER_CAPABILITY_UNAVAILABLE" | "RENDER_INVALID_RESULT", message: string);
89
+ }
90
+ export declare function createFramekitRenderRequest(input: FramekitRenderRequestInput): FramekitRenderRequest;
91
+ export declare function inferFramekitRenderFeatures(timeline: TimelineIr): FramekitRenderFeature[];
92
+ export declare function createFramekitRenderPlan(request: FramekitRenderRequest, capabilities: FramekitRenderCapabilityReport): FramekitRenderPlan;
93
+ export declare function createFramekitRenderResult(plan: FramekitRenderPlan, output: {
94
+ path: string;
95
+ format: FramekitRenderFormat;
96
+ }): FramekitRenderProviderResult;
@@ -0,0 +1,85 @@
1
+ import type { AgentContext, AssetSearchQuery, AudioAnalysis, NoiseAnalysis, CompositeEditPreview, CompositeEditRequest, ContextDiff, ContextCursor, ContextRevision, CapabilityInspectionOptions, EditOperation, EditTransaction, EditorAsset, EditorChange, EditorLiveState, EditorPort, ManagedArtifact, MediaContext, MediaIndexEntry, MediaIndexQuery, RoughCutPlan as SemanticRoughCutPlan, RoughCutPlanRequest as SemanticRoughCutPlanRequest, MediaUnderstanding, MusicAddRequest, ProjectCatalog, ProjectSelection, ProjectSelectionResult, ProjectSnapshot, RoughCutConstructionPlan, RoughCutConstructionPlanRequest, RoughCutConstructionPreview, RationalTime, SpeechAnalysis, TimelineDiff, TimelineChangesRequest, TimelineChangesResult, TimelineFrameCapture, TimelineSemanticContext, TimelineSemanticContextQuery, TimeRange, VerificationPolicy, VisualAnalysis, EditorTimelineEditTargetInput, DurationPolicyPlan, DurationPolicyRequest } from "./domain/index.js";
2
+ import type { SkillDefinition, SkillExecution, SkillManifest, SkillPreview } from "./domain/skills.js";
3
+ import type { SkillInspection, SkillPreviewRequest } from "./skills/runtime.js";
4
+ import type { FillerRemovalPreview, FillerRemovalRequest } from "./speech/filler-removal.js";
5
+ import type { RuntimeOptions } from "./application/runtime-options.js";
6
+ import type { DialogueNormalizationPreview, DialogueNormalizationRequest } from "./audio/dialogue-normalization.js";
7
+ /** Stable runtime façade exposed to the MCP server and editor adapters. */
8
+ export declare class AgentVideoRuntime {
9
+ private readonly editor;
10
+ private readonly projects;
11
+ private readonly contexts;
12
+ private readonly media;
13
+ private readonly edits;
14
+ private readonly music;
15
+ private readonly fillerRemoval;
16
+ private readonly durationPolicy;
17
+ private readonly dialogueNormalization;
18
+ private readonly skills;
19
+ constructor(adapter: EditorPort, options?: RuntimeOptions);
20
+ withCanonicalReadScope<T>(operation: () => Promise<T>): Promise<T>;
21
+ inspectProject(): Promise<ProjectSnapshot>;
22
+ inspectTimeline(): Promise<ProjectSnapshot["timeline"]>;
23
+ inspectArtifact(): Promise<ManagedArtifact>;
24
+ planRoughCutConstruction(request: RoughCutConstructionPlanRequest): Promise<RoughCutConstructionPlan>;
25
+ previewRoughCutConstruction(request: RoughCutConstructionPlanRequest): Promise<RoughCutConstructionPreview>;
26
+ captureFrame(position: RationalTime, options?: {
27
+ analyze?: boolean;
28
+ }): Promise<TimelineFrameCapture>;
29
+ listProjects(): Promise<ProjectCatalog>;
30
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
31
+ inspectEditor(options?: CapabilityInspectionOptions): Promise<{
32
+ identity: import("./domain/capabilities.js").EditorIdentity;
33
+ capabilities: {
34
+ editor: import("./domain/capabilities.js").EditorCapabilities;
35
+ analyzers: import("./domain/capabilities.js").AnalyzerCapabilities;
36
+ schemaVersion: typeof import("./domain/capabilities.js").CAPABILITY_SCHEMA_VERSION;
37
+ families: import("./domain/capabilities.js").CapabilityFamilies;
38
+ };
39
+ }>;
40
+ inspectContext(options?: CapabilityInspectionOptions): Promise<AgentContext>;
41
+ inspectLiveEditor(): Promise<EditorLiveState>;
42
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
43
+ edit(operation: EditOperation, policy?: VerificationPolicy): Promise<EditTransaction>;
44
+ editArtifact(artifactPath: string, operation: EditOperation, policy?: VerificationPolicy): Promise<EditTransaction>;
45
+ editTimeline(target: EditorTimelineEditTargetInput, operation: EditOperation, policy?: VerificationPolicy): Promise<EditTransaction>;
46
+ previewEdit(request: CompositeEditRequest): Promise<CompositeEditPreview>;
47
+ previewArtifactEdit(artifactPath: string, request: CompositeEditRequest): Promise<CompositeEditPreview>;
48
+ previewTimelineEdit(target: EditorTimelineEditTargetInput, request: CompositeEditRequest): Promise<CompositeEditPreview>;
49
+ executeEdit(previewToken: string, policy?: VerificationPolicy): Promise<EditTransaction>;
50
+ previewMusic(request: MusicAddRequest): Promise<CompositeEditPreview>;
51
+ previewFillerRemoval(request: FillerRemovalRequest): Promise<FillerRemovalPreview>;
52
+ executeFillerRemoval(previewToken: string): Promise<EditTransaction>;
53
+ previewDialogueNormalization(request: DialogueNormalizationRequest): Promise<DialogueNormalizationPreview>;
54
+ executeDialogueNormalization(previewToken: string): Promise<EditTransaction>;
55
+ registerSkill(definition: SkillDefinition): void;
56
+ /** Register the repository-owned Skills used by the generic MCP surface. */
57
+ registerBuiltinSkills(): void;
58
+ listSkills(): SkillManifest[];
59
+ inspectSkill(skillId: string, version?: string): SkillManifest;
60
+ listSkillAvailability(): Promise<SkillInspection[]>;
61
+ inspectSkillAvailability(skillId: string, version?: string): Promise<SkillInspection>;
62
+ previewSkill(request: SkillPreviewRequest): Promise<SkillPreview>;
63
+ executeSkill(previewToken: string): Promise<SkillExecution>;
64
+ changesSince(revision: ContextRevision): Promise<TimelineDiff>;
65
+ timelineChangesSince(request: TimelineChangesRequest): Promise<TimelineChangesResult>;
66
+ contextChangesSince(cursorOrRevision: ContextCursor | ContextRevision, waitMs?: number): Promise<ContextDiff>;
67
+ analyzeSpeech(mediaId: string, range?: TimeRange): Promise<SpeechAnalysis>;
68
+ analyzeAudio(mediaId: string, range?: TimeRange): Promise<AudioAnalysis>;
69
+ analyzeNoise(mediaId: string, range?: TimeRange): Promise<NoiseAnalysis>;
70
+ analyzeVisual(mediaId: string, range?: TimeRange): Promise<VisualAnalysis>;
71
+ understandMedia(mediaId: string): Promise<MediaUnderstanding>;
72
+ understandMediaInProject(mediaId: string, project: ProjectSnapshot): Promise<MediaUnderstanding>;
73
+ planDuration(request: DurationPolicyRequest): DurationPolicyPlan;
74
+ inspectMedia(mediaId: string): Promise<MediaContext>;
75
+ searchMedia(query: string): Promise<MediaContext[]>;
76
+ indexMedia(query?: MediaIndexQuery): Promise<MediaIndexEntry[]>;
77
+ planRoughCut(request: SemanticRoughCutPlanRequest): Promise<SemanticRoughCutPlan>;
78
+ planRoughCutInProject(request: SemanticRoughCutPlanRequest, project: ProjectSnapshot): Promise<SemanticRoughCutPlan>;
79
+ inspectTimelineSemanticContext(query?: TimelineSemanticContextQuery): Promise<TimelineSemanticContext>;
80
+ listAssets(query?: AssetSearchQuery): Promise<EditorAsset[]>;
81
+ getDiff(transactionId: string): TimelineDiff;
82
+ getTransaction(transactionId: string): EditTransaction;
83
+ verifyTransaction(transactionId: string): Promise<NonNullable<EditTransaction["verification"]>>;
84
+ undo(transactionId: string): Promise<ProjectSnapshot>;
85
+ }
@@ -7,13 +7,14 @@ import { FillerRemovalService } from "./editing/filler-removal-service.js";
7
7
  import { MediaAnalysisService } from "./application/media-analysis-service.js";
8
8
  import { MusicService } from "./editing/music-service.js";
9
9
  import { ProjectService } from "./application/project-service.js";
10
- import { TransactionStore } from "./application/transaction-store.js";
10
+ import { InMemoryTransactionStore } from "./application/transaction-store.js";
11
11
  import { DurationPolicyService } from "./application/duration-policy-service.js";
12
12
  import { DialogueNormalizationService } from "./editing/dialogue-normalization-service.js";
13
13
  import { SkillRuntime } from "./skills/runtime.js";
14
14
  import { builtinSkills } from "./skills/builtin.js";
15
15
  /** Stable runtime façade exposed to the MCP server and editor adapters. */
16
16
  export class AgentVideoRuntime {
17
+ editor;
17
18
  projects;
18
19
  contexts;
19
20
  media;
@@ -24,9 +25,10 @@ export class AgentVideoRuntime {
24
25
  dialogueNormalization;
25
26
  skills;
26
27
  constructor(adapter, options = {}) {
28
+ this.editor = adapter;
27
29
  const context = new ContextEngine(adapter);
28
30
  const verificationEngine = options.verificationEngine ?? new DefaultVerificationEngine();
29
- const transactions = new TransactionStore();
31
+ const transactions = new InMemoryTransactionStore();
30
32
  this.projects = new ProjectService(adapter, context, options);
31
33
  this.contexts = new ContextService(adapter, context);
32
34
  this.media = new MediaAnalysisService(this.projects, context, options);
@@ -37,11 +39,14 @@ export class AgentVideoRuntime {
37
39
  this.durationPolicy = new DurationPolicyService();
38
40
  this.skills = new SkillRuntime(this.projects, this.media, this.edits, options);
39
41
  }
42
+ withCanonicalReadScope(operation) {
43
+ return this.editor.withCanonicalReadScope?.(operation) ?? operation();
44
+ }
40
45
  async inspectProject() {
41
- return this.projects.inspectProject();
46
+ return this.withCanonicalReadScope(() => this.projects.inspectProject());
42
47
  }
43
48
  async inspectTimeline() {
44
- return this.projects.inspectTimeline();
49
+ return this.withCanonicalReadScope(() => this.projects.inspectTimeline());
45
50
  }
46
51
  async inspectArtifact() {
47
52
  return this.projects.inspectArtifact();
@@ -66,9 +71,13 @@ export class AgentVideoRuntime {
66
71
  async inspectEditor(options = {}) {
67
72
  return this.projects.inspectEditor(options);
68
73
  }
69
- async inspectContext() {
70
- const editor = await this.inspectEditor();
71
- return this.contexts.inspectContext(editor.capabilities);
74
+ async inspectContext(options = {}) {
75
+ const inspect = async () => {
76
+ const editor = await this.inspectEditor({ ...options, probeCanonicalSnapshot: options.probeCanonicalSnapshot === true });
77
+ const headedRead = editor.capabilities.families?.canonicalDocument.read.evidenceTier === "headed-native";
78
+ return this.contexts.inspectContext(editor.capabilities, { includeCanonicalSnapshot: !headedRead || options.probeCanonicalSnapshot === true });
79
+ };
80
+ return options.probeCanonicalSnapshot === true ? this.withCanonicalReadScope(inspect) : inspect();
72
81
  }
73
82
  async inspectLiveEditor() {
74
83
  return this.contexts.inspectLiveEditor();
@@ -0,0 +1,2 @@
1
+ import type { SkillDefinition } from "../domain/skills.js";
2
+ export declare function builtinSkills(): SkillDefinition[];
@@ -0,0 +1,3 @@
1
+ export * from "./registry.js";
2
+ export * from "./requirements.js";
3
+ export * from "./runtime.js";
@@ -0,0 +1,10 @@
1
+ import type { SkillDefinition, SkillManifest } from "../domain/skills.js";
2
+ export declare class SkillRegistry {
3
+ private readonly definitions;
4
+ register(definition: SkillDefinition): void;
5
+ has(skillId: string, version: string): boolean;
6
+ list(): SkillManifest[];
7
+ inspect(skillId: string, version?: string): SkillManifest;
8
+ lookup(skillId: string, version?: string): SkillDefinition;
9
+ }
10
+ export declare function validateManifest(manifest: SkillManifest): void;
@@ -0,0 +1,38 @@
1
+ import type { SkillManifest } from "../domain/skills.js";
2
+ import type { EditorIdentity, RuntimeCapabilities } from "../domain/capabilities.js";
3
+ import type { ContextRevision } from "../domain/primitives.js";
4
+ export declare const SKILL_EDITOR_CAPABILITIES: readonly ["projectRead", "timelineSnapshotRead", "timelineWrite", "timelineArtifactWrite", "readAfterWrite", "rollback", "assetDiscovery", "liveStateRead", "playheadWrite", "frameCapture", "artifactPublish", "projectCatalogRead", "projectSelection", "compositeTransactions", "videoExport", "mediaImport", "mediaPlacement", "pictureInPicture", "titlePlacement", "clipMove", "clipReplace", "clipRemoval", "transitionPlacement", "audioAttachment", "audioMixing", "noiseReduction", "colorCorrection"];
5
+ export declare const SKILL_ANALYZER_CAPABILITIES: readonly ["speechTranscribe", "speechVad", "audioLoudness", "audioNoise", "visualTrack", "metadataDescribe"];
6
+ export type SkillRequirementReasonCode = "MISSING_EDITOR_CAPABILITY" | "MISSING_ANALYZER_CAPABILITY" | "UNSUPPORTED_SEMANTIC_OPERATION" | "UNKNOWN_REQUIREMENT" | "EMPTY_REQUIREMENT_GROUP" | "NO_ALTERNATIVE_SATISFIED";
7
+ export interface SkillRequirementDiagnostic {
8
+ path: string;
9
+ code: SkillRequirementReasonCode;
10
+ requirement: unknown;
11
+ name: string;
12
+ message: string;
13
+ }
14
+ export interface SkillResolutionContext {
15
+ capabilities: RuntimeCapabilities;
16
+ editor?: EditorIdentity;
17
+ revision?: ContextRevision;
18
+ }
19
+ export interface SkillAvailability {
20
+ skillId: string;
21
+ skillVersion: string;
22
+ available: boolean;
23
+ satisfiedRequirementPath: string[];
24
+ missingRequirements: SkillRequirementDiagnostic[];
25
+ reasonCodes: SkillRequirementReasonCode[];
26
+ context: {
27
+ editor?: EditorIdentity;
28
+ backend: string;
29
+ revision?: ContextRevision;
30
+ };
31
+ }
32
+ export declare class SkillRequirementsUnavailableError extends Error {
33
+ readonly availability: SkillAvailability;
34
+ readonly code: "SKILL_REQUIREMENTS_UNMET";
35
+ constructor(availability: SkillAvailability);
36
+ }
37
+ export declare function resolveSkillRequirements(manifest: Pick<SkillManifest, "id" | "version" | "requirements">, context: SkillResolutionContext): SkillAvailability;
38
+ export declare function assertSkillRequirements(manifest: Pick<SkillManifest, "id" | "version" | "requirements">, context: SkillResolutionContext): SkillAvailability;
@@ -0,0 +1,38 @@
1
+ import type { ProjectService } from "../application/project-service.js";
2
+ import type { MediaAnalysisService } from "../application/media-analysis-service.js";
3
+ import type { RuntimeOptions } from "../application/runtime-options.js";
4
+ import type { ContextRevision } from "../domain/primitives.js";
5
+ import type { SkillDefinition, SkillExecution, SkillManifest, SkillPreview } from "../domain/skills.js";
6
+ import type { EditService } from "../editing/edit-service.js";
7
+ import { type SkillAvailability } from "./requirements.js";
8
+ import { SkillRegistry } from "./registry.js";
9
+ export interface SkillPreviewRequest {
10
+ skillId: string;
11
+ version?: string;
12
+ baseRevision: ContextRevision;
13
+ input: unknown;
14
+ }
15
+ export interface SkillInspection {
16
+ manifest: SkillManifest;
17
+ availability: SkillAvailability;
18
+ }
19
+ export declare class SkillRuntime {
20
+ private readonly project;
21
+ private readonly analysis;
22
+ private readonly edits;
23
+ private readonly options;
24
+ readonly registry: SkillRegistry;
25
+ private readonly previews;
26
+ constructor(project: ProjectService, analysis: MediaAnalysisService, edits: EditService, options?: RuntimeOptions);
27
+ register(definition: SkillDefinition): void;
28
+ list(): SkillManifest[];
29
+ inspect(skillId: string, version?: string): SkillManifest;
30
+ listAvailability(): Promise<SkillInspection[]>;
31
+ inspectAvailability(skillId: string, version?: string): Promise<SkillInspection>;
32
+ preview(request: SkillPreviewRequest): Promise<SkillPreview>;
33
+ execute(previewToken: string): Promise<SkillExecution>;
34
+ private assertInputSchema;
35
+ private prunePreviews;
36
+ private now;
37
+ private currentResolutionContext;
38
+ }
@@ -0,0 +1,18 @@
1
+ import type { AnalysisInput, AnalyzerDescriptor, RevisionBoundSpeechAnalysis, SpeechSegment, VadCoverageSpan } from "../domain/media.js";
2
+ import type { RationalTime, TimeRange } from "../domain/primitives.js";
3
+ export declare const DEFAULT_SPEECH_SOURCE_TIMEBASE: RationalTime;
4
+ export interface SpeechBindingContext {
5
+ input: AnalysisInput;
6
+ provider?: AnalyzerDescriptor;
7
+ range?: TimeRange;
8
+ }
9
+ /**
10
+ * Validate provider evidence and bind it to the current source and revision.
11
+ * Missing provenance is filled from the trusted runtime request; conflicting
12
+ * provenance is rejected before the evidence can authorize an edit.
13
+ */
14
+ export declare function bindSpeechAnalysis(value: unknown, context: SpeechBindingContext): RevisionBoundSpeechAnalysis;
15
+ /** Check that range-scoped VAD cannot contradict top-level availability. */
16
+ export declare function validateVadCoverageConsistency(vadCoverage: VadCoverageSpan[] | undefined, vadSegments: SpeechSegment[] | undefined, vadUnavailableReason: string | undefined, observedRange: TimeRange): void;
17
+ /** Validate serialized range-scoped VAD before consuming it. */
18
+ export declare function validateVadCoverage(value: unknown, observed: TimeRange, duration: number | undefined): VadCoverageSpan[] | undefined;
@@ -37,6 +37,9 @@ export function bindSpeechAnalysis(value, context) {
37
37
  validateObservedRange(observedRange, requestedRange, context.input.media.duration);
38
38
  const words = validateWords(record.words, observedRange, context.input.media.duration);
39
39
  const vadSegments = validateOptionalSegments(record.vadSegments, "VAD", observedRange, context.input.media.duration);
40
+ const vadUnavailableReason = optionalString(record.vadUnavailableReason, "VAD unavailable reason");
41
+ const vadCoverage = validateVadCoverage(record.vadCoverage, observedRange, context.input.media.duration);
42
+ validateVadCoverageConsistency(vadCoverage, vadSegments, vadUnavailableReason, observedRange);
40
43
  const silenceSegments = validateOptionalSegments(record.silenceSegments, "silence", observedRange, context.input.media.duration);
41
44
  const protectedSegments = validateOptionalSegments(record.protectedSegments, "protected", observedRange, context.input.media.duration);
42
45
  const capability = validateCapability(record.capability, vadSegments);
@@ -55,10 +58,74 @@ export function bindSpeechAnalysis(value, context) {
55
58
  capability,
56
59
  words,
57
60
  ...(vadSegments ? { vadSegments } : {}),
61
+ ...(vadCoverage !== undefined ? { vadCoverage } : {}),
62
+ ...(vadUnavailableReason !== undefined ? { vadUnavailableReason } : {}),
58
63
  ...(silenceSegments ? { silenceSegments } : {}),
59
64
  ...(protectedSegments ? { protectedSegments } : {}),
60
65
  };
61
66
  }
67
+ /** Check that range-scoped VAD cannot contradict top-level availability. */
68
+ export function validateVadCoverageConsistency(vadCoverage, vadSegments, vadUnavailableReason, observedRange) {
69
+ if (vadUnavailableReason !== undefined && vadSegments !== undefined) {
70
+ throw new Error("ANALYSIS_INVALID: VAD evidence conflicts with its unavailable status");
71
+ }
72
+ if (vadCoverage !== undefined && vadUnavailableReason !== undefined) {
73
+ let cursor = observedRange.start;
74
+ const complete = vadCoverage.length > 0 && vadCoverage.every((span) => {
75
+ if (span.status !== "available" || span.start !== cursor)
76
+ return false;
77
+ cursor = span.end;
78
+ return true;
79
+ }) && cursor === observedRange.end;
80
+ if (complete)
81
+ throw new Error("ANALYSIS_INVALID: complete VAD coverage conflicts with its unavailable status");
82
+ }
83
+ if (vadCoverage !== undefined && vadSegments !== undefined) {
84
+ let cursor = observedRange.start;
85
+ const covered = [];
86
+ for (const span of vadCoverage) {
87
+ if (span.status !== "available" || span.start !== cursor) {
88
+ throw new Error("ANALYSIS_INVALID: top-level VAD requires complete available coverage");
89
+ }
90
+ cursor = span.end;
91
+ covered.push(...span.segments);
92
+ }
93
+ if (cursor !== observedRange.end || covered.length !== vadSegments.length || covered.some((segment, index) => {
94
+ const other = vadSegments[index];
95
+ return !other || segment.start !== other.start || segment.end !== other.end
96
+ || segment.kind !== other.kind || segment.confidence !== other.confidence;
97
+ })) {
98
+ throw new Error("ANALYSIS_INVALID: top-level VAD differs from complete coverage");
99
+ }
100
+ }
101
+ }
102
+ /** Validate serialized range-scoped VAD before consuming it. */
103
+ export function validateVadCoverage(value, observed, duration) {
104
+ if (value === undefined)
105
+ return undefined;
106
+ if (!Array.isArray(value))
107
+ throw new Error("ANALYSIS_INVALID: VAD coverage must be an array");
108
+ const coverage = value.map((entry, index) => {
109
+ const span = asRecord(entry, `VAD coverage ${index + 1} must be an object`);
110
+ const range = validateRange(span, "VAD coverage range");
111
+ validateEvidenceBounds([range], observed, duration, "VAD coverage range");
112
+ if (span.status === "available") {
113
+ const segments = validateOptionalSegments(span.segments, "VAD coverage", range, duration);
114
+ if (!segments || span.reason !== undefined)
115
+ throw new Error("ANALYSIS_INVALID: available VAD coverage needs segments and no reason");
116
+ return { start: range.start, end: range.end, status: "available", segments };
117
+ }
118
+ if (span.status === "unavailable") {
119
+ const reason = optionalString(span.reason, "VAD coverage unavailable reason");
120
+ if (!reason || span.segments !== undefined)
121
+ throw new Error("ANALYSIS_INVALID: unavailable VAD coverage needs a reason and no segments");
122
+ return { start: range.start, end: range.end, status: "unavailable", reason };
123
+ }
124
+ throw new Error("ANALYSIS_INVALID: VAD coverage status is unsupported");
125
+ });
126
+ validateOrderedRanges(coverage, "VAD coverage");
127
+ return coverage;
128
+ }
62
129
  function sourceIdentityOf(media) {
63
130
  return {
64
131
  mediaId: media.mediaId,
@@ -0,0 +1,49 @@
1
+ import type { SpeechAnalysis, SpeechWord } from "../domain/media.js";
2
+ import type { TimeRange } from "../domain/primitives.js";
3
+ export declare const DEFAULT_FILLER_VOCABULARY: readonly ["er", "erm", "hmm", "uh", "um"];
4
+ export declare const DEFAULT_FILLER_CONFIDENCE_THRESHOLD = 0.92;
5
+ export type FillerReasonCode = "ANALYZER_MARKED_FILLER" | "VOCABULARY_MATCH" | "BELOW_CONFIDENCE_THRESHOLD";
6
+ export interface FillerOccurrence {
7
+ occurrenceId: string;
8
+ mediaId?: string;
9
+ sourceRange: TimeRange;
10
+ sequenceRange: TimeRange;
11
+ }
12
+ export interface FillerDetectionInput {
13
+ previewId: string;
14
+ analysis: SpeechAnalysis;
15
+ targetRange: TimeRange;
16
+ occurrence: FillerOccurrence;
17
+ revisionId?: string;
18
+ }
19
+ export interface FillerDetectorOptions {
20
+ vocabulary?: readonly string[];
21
+ confidenceThreshold?: number;
22
+ }
23
+ export interface FillerCandidateEvidence {
24
+ word: SpeechWord;
25
+ analyzerMarkedFiller: boolean;
26
+ vocabularyMatch: boolean;
27
+ withinTarget: boolean;
28
+ }
29
+ export interface FillerCandidate {
30
+ id: string;
31
+ word: SpeechWord;
32
+ wordEvidence: SpeechWord;
33
+ confidence: number;
34
+ confidenceThreshold: number;
35
+ eligible: boolean;
36
+ occurrenceId: string;
37
+ mediaId?: string;
38
+ sourceRange: TimeRange;
39
+ sequenceRange: TimeRange;
40
+ reasonCodes: FillerReasonCode[];
41
+ evidence: FillerCandidateEvidence;
42
+ }
43
+ /** Turn analyzer speech evidence into deterministic, preview-scoped candidates. */
44
+ export declare class FillerDetector {
45
+ private readonly vocabulary;
46
+ private readonly confidenceThreshold;
47
+ constructor(options?: FillerDetectorOptions);
48
+ detect(input: FillerDetectionInput): FillerCandidate[];
49
+ }