@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,77 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ import { EditingSession, type EditingSessionState, type TimelineIr } from "./editing-session.js";
3
+ import type { TimelineReconciliationResult } from "./drift-reconciliation.js";
4
+ export declare const FAST_TIMELINE_OBSERVATION_SCHEMA_VERSION: 1;
5
+ export type FastTimelineCoverageState = "complete" | "partial" | "unknown";
6
+ export type FastTimelineTrust = "normalized" | "structural" | "evidence-only";
7
+ export type FastTimelineFreshness = "editor-read" | "storage-observed" | "unknown";
8
+ export interface FastTimelineObservationTarget {
9
+ projectId: string;
10
+ sequenceId: string;
11
+ }
12
+ export interface FastTimelineObservationProvenance {
13
+ framekitRevision: ContextRevision;
14
+ artifactDigest: string;
15
+ target: FastTimelineObservationTarget;
16
+ }
17
+ /** Provider-neutral evidence envelope. A timeline is optional because most fast providers are partial. */
18
+ export interface FastTimelineObservation {
19
+ schemaVersion: typeof FAST_TIMELINE_OBSERVATION_SCHEMA_VERSION;
20
+ provider: string;
21
+ sourceType: string;
22
+ canonical: false;
23
+ target: FastTimelineObservationTarget;
24
+ provenance: FastTimelineObservationProvenance;
25
+ observedAt: string;
26
+ trust: FastTimelineTrust;
27
+ freshness: FastTimelineFreshness;
28
+ revision: ContextRevision;
29
+ observationDigest: string;
30
+ timelineDigest?: string;
31
+ coverage: {
32
+ occurrences: FastTimelineCoverageState;
33
+ resources: FastTimelineCoverageState;
34
+ timing: FastTimelineCoverageState;
35
+ roles: FastTimelineCoverageState;
36
+ storylineRelationships: FastTimelineCoverageState;
37
+ markersCaptions: FastTimelineCoverageState;
38
+ };
39
+ unknowns: string[];
40
+ timeline?: TimelineIr;
41
+ }
42
+ export interface FastTimelineNormalizationInput extends Omit<FastTimelineObservation, "timeline" | "timelineDigest"> {
43
+ timeline?: TimelineIr;
44
+ timelineDigest?: string;
45
+ }
46
+ export type FastTimelineReconciliationStatus = "unchanged" | "advanced-by-framekit" | "proven-structural-delta" | "possibly-stale" | "conflicted" | "canonical-resync-required" | "target-mismatch" | "provider-incompatible";
47
+ export interface FastTimelineSessionEvidence {
48
+ state: EditingSessionState;
49
+ base: TimelineIr;
50
+ desired: TimelineIr;
51
+ serialized: string;
52
+ }
53
+ export type FastTimelineReconciliation = {
54
+ status: FastTimelineReconciliationStatus;
55
+ canonical: false;
56
+ provider: string;
57
+ sourceType: string;
58
+ revision: ContextRevision;
59
+ coverage: FastTimelineObservation["coverage"];
60
+ unknowns: string[];
61
+ reason: string;
62
+ session: FastTimelineSessionEvidence;
63
+ reconciliation?: TimelineReconciliationResult;
64
+ };
65
+ /**
66
+ * Normalize an adapter-produced envelope at the runtime boundary.
67
+ * The runtime validates the optional Timeline IR but never invents unknown fields.
68
+ */
69
+ export declare function normalizeFastTimelineObservation(input: FastTimelineNormalizationInput): FastTimelineObservation;
70
+ /**
71
+ * Reconcile provider evidence through the real EditingSession state machine.
72
+ * Partial evidence never replaces the known canonical baseline.
73
+ */
74
+ export declare function reconcileFastTimelineObservation(input: {
75
+ session: EditingSession;
76
+ observation: FastTimelineObservation;
77
+ }): FastTimelineReconciliation;
@@ -0,0 +1,11 @@
1
+ import type { RationalTime, TimeRange } from "../domain/primitives.js";
2
+ export interface RationalParts {
3
+ value: bigint;
4
+ timescale: bigint;
5
+ }
6
+ export declare function parseRational(time: RationalTime, errorCode: string): RationalParts;
7
+ export declare function addRationalTimes(left: RationalTime, right: RationalTime, errorCode?: string): RationalTime;
8
+ export declare function subtractRationalTimes(left: RationalTime, right: RationalTime, errorCode?: string): RationalTime;
9
+ export declare function isWithinClip(position: RationalParts, startTime: RationalTime, durationTime: RationalTime): boolean;
10
+ export declare function rationalDifferenceSeconds(left: RationalParts, right: RationalParts): number;
11
+ export declare function translateRationalRange(clipStartTime: RationalTime, clipStart: number, sourceRange: TimeRange): TimeRange;
@@ -0,0 +1,32 @@
1
+ import type { Clip, ProjectSnapshot } from "../domain/project.js";
2
+ import type { ContextRevision } from "../domain/primitives.js";
3
+ export type PrimaryStorylineDestination = {
4
+ kind: "start";
5
+ } | {
6
+ kind: "end";
7
+ } | {
8
+ kind: "before";
9
+ occurrenceId: string;
10
+ } | {
11
+ kind: "after";
12
+ occurrenceId: string;
13
+ };
14
+ export interface PrimaryStorylineReorderPreview {
15
+ projectId: string;
16
+ sequenceId: string;
17
+ revision: ContextRevision;
18
+ snapshotDigest: string;
19
+ occurrenceId: string;
20
+ moving: Clip;
21
+ source: string;
22
+ destination: PrimaryStorylineDestination;
23
+ noOp: boolean;
24
+ before: Clip[];
25
+ after: Clip[];
26
+ }
27
+ /** Reject a preview if its complete baseline or planned content has changed. */
28
+ export declare function assertReorderPreviewCurrent(preview: PrimaryStorylineReorderPreview, snapshot: ProjectSnapshot): void;
29
+ /** Plan a contiguous primary-storyline reorder without dispatching an editor operation. */
30
+ export declare function previewPrimaryStorylineReorder(snapshot: ProjectSnapshot, occurrenceId: string, destination: PrimaryStorylineDestination): PrimaryStorylineReorderPreview;
31
+ /** Compare the entire supported snapshot with the approved reorder projection. */
32
+ export declare function verifyPrimaryStorylineReorder(preview: PrimaryStorylineReorderPreview, before: ProjectSnapshot, after: ProjectSnapshot): void;
@@ -0,0 +1,202 @@
1
+ import { createHash } from "node:crypto";
2
+ import { isDeepStrictEqual } from "node:util";
3
+ import { addRationalTimes, parseRational } from "./rational-time.js";
4
+ function compare(left, right) {
5
+ const a = parseRational(left, "REORDER_INVALID");
6
+ const b = parseRational(right, "REORDER_INVALID");
7
+ const difference = a.value * b.timescale - b.value * a.timescale;
8
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
9
+ }
10
+ function snapshotDigest(snapshot) {
11
+ const json = JSON.stringify(snapshot, (_key, value) => {
12
+ if (!value || typeof value !== "object" || Array.isArray(value))
13
+ return value;
14
+ return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
15
+ });
16
+ return createHash("sha256").update(json).digest("hex");
17
+ }
18
+ /** Reject a preview if its complete baseline or planned content has changed. */
19
+ export function assertReorderPreviewCurrent(preview, snapshot) {
20
+ try {
21
+ if (preview.snapshotDigest !== snapshotDigest(snapshot)
22
+ || !isDeepStrictEqual(preview, previewPrimaryStorylineReorder(snapshot, preview.occurrenceId, preview.destination))) {
23
+ throw new Error("preview mismatch");
24
+ }
25
+ }
26
+ catch (error) {
27
+ throw new Error("REORDER_PREVIEW_STALE: target, revision, content, or preview changed", { cause: error });
28
+ }
29
+ }
30
+ function assertFiniteNumbers(value) {
31
+ if (typeof value === "number" && !Number.isFinite(value))
32
+ throw new Error("REORDER_INVALID: non-finite snapshot value");
33
+ if (Array.isArray(value)) {
34
+ for (const item of value)
35
+ assertFiniteNumbers(item);
36
+ }
37
+ else if (value && typeof value === "object") {
38
+ for (const child of Object.values(value))
39
+ assertFiniteNumbers(child);
40
+ }
41
+ }
42
+ function assertNumericTime(value, exact) {
43
+ const time = parseRational(exact, "REORDER_INVALID");
44
+ const seconds = Number(time.value) / Number(time.timescale);
45
+ if (!Number.isFinite(seconds) || !Number.isFinite(value)
46
+ || Math.abs(value - seconds) > Number.EPSILON * Math.max(1, Math.abs(value), Math.abs(seconds)) * 8) {
47
+ throw new Error("REORDER_INVALID: numeric and rational timing disagree");
48
+ }
49
+ }
50
+ /** Plan a contiguous primary-storyline reorder without dispatching an editor operation. */
51
+ export function previewPrimaryStorylineReorder(snapshot, occurrenceId, destination) {
52
+ if (!destination || typeof destination !== "object"
53
+ || !["start", "end", "before", "after"].includes(destination.kind)
54
+ || ((destination.kind === "before" || destination.kind === "after") && (typeof destination.occurrenceId !== "string" || !destination.occurrenceId))) {
55
+ throw new Error("REORDER_INVALID: destination is invalid");
56
+ }
57
+ assertFiniteNumbers(snapshot);
58
+ if (!snapshot.projectId || !snapshot.timeline.id || !snapshot.revision.id || !Number.isSafeInteger(snapshot.revision.sequence) || snapshot.revision.sequence < 0) {
59
+ throw new Error("REORDER_INVALID: target and revision are required");
60
+ }
61
+ if (snapshot.timeline.markers.length || snapshot.timeline.captions.length
62
+ || snapshot.timeline.storyElements.some((item) => item.kind !== "asset-clip")) {
63
+ throw new Error("REORDER_UNSUPPORTED: timeline structure requires independent verification");
64
+ }
65
+ const clips = [...snapshot.timeline.clips].sort((a, b) => compare(a.startTime, b.startTime));
66
+ const ids = new Set();
67
+ const mediaIds = new Set();
68
+ for (const media of snapshot.media) {
69
+ if (!media.mediaId || !media.source || mediaIds.has(media.mediaId))
70
+ throw new Error("REORDER_INVALID: media source binding is incomplete or ambiguous");
71
+ mediaIds.add(media.mediaId);
72
+ }
73
+ for (let index = 0; index < clips.length; index++) {
74
+ const clip = clips[index];
75
+ if (!clip.id || ids.has(clip.id) || !clip.mediaId || !mediaIds.has(clip.mediaId))
76
+ throw new Error("REORDER_INVALID: occurrence identity or source binding is incomplete");
77
+ ids.add(clip.id);
78
+ if (clip.track !== 0 || clip.attachedTo || !clip.sourceStartTime)
79
+ throw new Error("REORDER_UNSUPPORTED: primary occurrence or source range is unavailable");
80
+ if (parseRational(clip.sourceStartTime, "REORDER_INVALID").value < 0n) {
81
+ throw new Error("REORDER_INVALID: source start must not be negative");
82
+ }
83
+ assertNumericTime(clip.start, clip.startTime);
84
+ assertNumericTime(clip.duration, clip.durationTime);
85
+ if (clip.sourceStart !== undefined)
86
+ assertNumericTime(clip.sourceStart, clip.sourceStartTime);
87
+ if (compare(clip.durationTime, { value: "0", timescale: "1" }) <= 0)
88
+ throw new Error("REORDER_INVALID: duration must be positive");
89
+ const sourceRange = snapshot.media.find((media) => media.mediaId === clip.mediaId)?.sourceRange;
90
+ if (sourceRange !== undefined) {
91
+ if (!sourceRange || typeof sourceRange !== "object" || !sourceRange.start || !sourceRange.duration) {
92
+ throw new Error("REORDER_INVALID: supplied source range is malformed");
93
+ }
94
+ if (parseRational(sourceRange.duration, "REORDER_INVALID").value <= 0n
95
+ || compare(clip.sourceStartTime, sourceRange.start) < 0
96
+ || compare(addRationalTimes(clip.sourceStartTime, clip.durationTime, "REORDER_INVALID"), addRationalTimes(sourceRange.start, sourceRange.duration, "REORDER_INVALID")) > 0) {
97
+ throw new Error("REORDER_INVALID: occurrence exceeds supplied source range");
98
+ }
99
+ }
100
+ if (index > 0 && compare(addRationalTimes(clips[index - 1].startTime, clips[index - 1].durationTime), clip.startTime) !== 0) {
101
+ throw new Error("REORDER_UNSUPPORTED: primary storyline is not contiguous");
102
+ }
103
+ }
104
+ if (snapshot.timeline.storyElements.length !== clips.length) {
105
+ throw new Error("REORDER_UNSUPPORTED: story elements are incomplete or unaccounted");
106
+ }
107
+ const storyIds = new Set();
108
+ for (const element of snapshot.timeline.storyElements) {
109
+ const clip = clips.find((item) => item.id === element.id);
110
+ if (!clip || storyIds.has(element.id) || element.mediaId !== clip.mediaId
111
+ || !element.startTime || !element.durationTime
112
+ || compare(element.startTime, clip.startTime) !== 0 || compare(element.durationTime, clip.durationTime) !== 0
113
+ || (element.lane !== undefined && element.lane !== 0) || element.attachedTo) {
114
+ throw new Error("REORDER_UNSUPPORTED: story element does not match a primary occurrence");
115
+ }
116
+ assertNumericTime(element.start, element.startTime);
117
+ assertNumericTime(element.duration, element.durationTime);
118
+ storyIds.add(element.id);
119
+ }
120
+ const oldIndex = clips.findIndex((clip) => clip.id === occurrenceId);
121
+ if (oldIndex < 0)
122
+ throw new Error("REORDER_TARGET_NOT_FOUND: moving occurrence is missing");
123
+ if ((destination.kind === "before" || destination.kind === "after") && !ids.has(destination.occurrenceId)) {
124
+ throw new Error("REORDER_TARGET_NOT_FOUND: destination occurrence is missing");
125
+ }
126
+ const selected = clips[oldIndex];
127
+ const source = snapshot.media.find((media) => media.mediaId === selected.mediaId).source;
128
+ const result = { projectId: snapshot.projectId, sequenceId: snapshot.timeline.id, revision: structuredClone(snapshot.revision), snapshotDigest: snapshotDigest(snapshot), occurrenceId, moving: structuredClone(selected), source, destination: structuredClone(destination), noOp: true, before: [], after: [] };
129
+ if ((destination.kind === "before" || destination.kind === "after") && destination.occurrenceId === occurrenceId)
130
+ return result;
131
+ const reordered = [...clips];
132
+ const [moving] = reordered.splice(oldIndex, 1);
133
+ const slot = destination.kind === "start" ? 0 : destination.kind === "end" ? reordered.length
134
+ : reordered.findIndex((clip) => clip.id === destination.occurrenceId) + (destination.kind === "after" ? 1 : 0);
135
+ reordered.splice(slot, 0, moving);
136
+ const newIndex = reordered.findIndex((clip) => clip.id === occurrenceId);
137
+ if (newIndex === oldIndex)
138
+ return result;
139
+ const first = Math.min(oldIndex, newIndex);
140
+ const last = Math.max(oldIndex, newIndex);
141
+ result.noOp = false;
142
+ result.before = structuredClone(clips.slice(first, last + 1));
143
+ let cursor = structuredClone(clips[first].startTime);
144
+ result.after = reordered.slice(first, last + 1).map((clip) => {
145
+ const moved = { ...structuredClone(clip), startTime: cursor, start: Number(cursor.value) / Number(cursor.timescale) };
146
+ cursor = addRationalTimes(cursor, clip.durationTime, "REORDER_INVALID");
147
+ return moved;
148
+ });
149
+ return result;
150
+ }
151
+ function comparable(value) {
152
+ if (Array.isArray(value))
153
+ return value.map(comparable);
154
+ if (!value || typeof value !== "object")
155
+ return value;
156
+ const object = value;
157
+ if (Object.keys(object).length === 2 && typeof object.value === "string" && typeof object.timescale === "string") {
158
+ const { value: numerator, timescale: denominator } = parseRational({ value: object.value, timescale: object.timescale }, "REORDER_READBACK_FAILED");
159
+ let a = numerator < 0n ? -numerator : numerator;
160
+ let b = denominator;
161
+ while (b !== 0n)
162
+ [a, b] = [b, a % b];
163
+ const divisor = a || 1n;
164
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
165
+ }
166
+ return Object.fromEntries(Object.entries(object).map(([key, child]) => [key, comparable(child)]));
167
+ }
168
+ /** Compare the entire supported snapshot with the approved reorder projection. */
169
+ export function verifyPrimaryStorylineReorder(preview, before, after) {
170
+ try {
171
+ assertReorderPreviewCurrent(preview, before);
172
+ if (!preview.noOp && (!after.revision.id || !Number.isSafeInteger(after.revision.sequence)
173
+ || after.revision.id === before.revision.id || after.revision.sequence <= before.revision.sequence)) {
174
+ throw new Error("revision did not advance");
175
+ }
176
+ const expected = structuredClone(before);
177
+ if (!preview.noOp) {
178
+ const moved = new Map(preview.after.map((item) => [item.id, item]));
179
+ expected.timeline.clips = expected.timeline.clips.map((item) => structuredClone(moved.get(item.id) ?? item));
180
+ expected.timeline.storyElements = expected.timeline.storyElements.map((element) => {
181
+ const updated = moved.get(element.id);
182
+ return updated ? { ...element, start: updated.start, startTime: structuredClone(updated.startTime) } : element;
183
+ });
184
+ expected.revision = structuredClone(after.revision);
185
+ }
186
+ const actual = structuredClone(after);
187
+ const byStart = (a, b) => {
188
+ if (!a.startTime || !b.startTime)
189
+ throw new Error("exact timing unavailable");
190
+ return compare(a.startTime, b.startTime) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
191
+ };
192
+ expected.timeline.clips.sort(byStart);
193
+ expected.timeline.storyElements.sort(byStart);
194
+ actual.timeline.clips.sort(byStart);
195
+ actual.timeline.storyElements.sort(byStart);
196
+ if (!isDeepStrictEqual(comparable(expected), comparable(actual)))
197
+ throw new Error("snapshot differs from approved reorder");
198
+ }
199
+ catch (error) {
200
+ throw new Error("REORDER_READBACK_FAILED: complete snapshot did not match the approved reorder", { cause: error });
201
+ }
202
+ }
@@ -0,0 +1,3 @@
1
+ import type { ProjectSnapshot } from "../domain/project.js";
2
+ import type { TimelineDiff } from "../domain/diff.js";
3
+ export declare function diffSnapshots(before: ProjectSnapshot, after: ProjectSnapshot): TimelineDiff;
@@ -26,6 +26,7 @@ function diffById(before, after) {
26
26
  function mediaRegistryFields(media) {
27
27
  return {
28
28
  source: media.source,
29
+ sourceRange: media.sourceRange,
29
30
  mediaKind: media.mediaKind,
30
31
  duration: media.duration,
31
32
  sourceDigest: media.sourceDigest,
@@ -0,0 +1,3 @@
1
+ import type { ProjectSnapshot } from "../domain/project.js";
2
+ /** Digest canonical editor content while deliberately excluding observation revisions and analysis. */
3
+ export declare function canonicalSnapshotDigest(snapshot: ProjectSnapshot): string;
@@ -5,7 +5,7 @@ export function canonicalSnapshotDigest(snapshot) {
5
5
  projectId: snapshot.projectId,
6
6
  projectName: snapshot.projectName,
7
7
  timeline: snapshot.timeline,
8
- media: snapshot.media.map(({ mediaId, source }) => ({ mediaId, source })),
8
+ media: snapshot.media.map(({ mediaId, source, sourceRange }) => ({ mediaId, source, ...(sourceRange ? { sourceRange } : {}) })),
9
9
  };
10
10
  return createHash("sha256").update(stableJson(canonical)).digest("hex");
11
11
  }
@@ -0,0 +1,6 @@
1
+ import type { EditTransaction } from "../domain/editing.js";
2
+ import type { VerificationEngine, VerificationPolicy, VerificationReport } from "../domain/verification.js";
3
+ export declare function assertValidVerificationPolicy(policy: VerificationPolicy): void;
4
+ export declare class DefaultVerificationEngine implements VerificationEngine {
5
+ verify(transaction: EditTransaction, policy: VerificationPolicy): Promise<VerificationReport>;
6
+ }
@@ -0,0 +1,37 @@
1
+ import type { AnalysisInput, AudioAnalysis, AudioAnalyzer, MetadataAnalysis, MetadataAnalyzer, VisualAnalysis, VisualAnalyzer, SpeechAnalysis, SpeechAnalyzer, TimeRange } from "../../runtime/src/index.js";
2
+ export declare class FixtureSpeechAnalyzer implements SpeechAnalyzer {
3
+ readonly descriptor: {
4
+ id: string;
5
+ provider: string;
6
+ version: string;
7
+ };
8
+ readonly capabilities: {
9
+ transcription: boolean;
10
+ vad: boolean;
11
+ };
12
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<SpeechAnalysis>;
13
+ }
14
+ export declare class FixtureAudioAnalyzer implements AudioAnalyzer {
15
+ readonly descriptor: {
16
+ id: string;
17
+ provider: string;
18
+ version: string;
19
+ };
20
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<AudioAnalysis>;
21
+ }
22
+ export declare class FixtureVisualAnalyzer implements VisualAnalyzer {
23
+ readonly descriptor: {
24
+ id: string;
25
+ provider: string;
26
+ version: string;
27
+ };
28
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<VisualAnalysis>;
29
+ }
30
+ export declare class FixtureMetadataAnalyzer implements MetadataAnalyzer {
31
+ readonly descriptor: {
32
+ id: string;
33
+ provider: string;
34
+ version: string;
35
+ };
36
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<MetadataAnalysis>;
37
+ }
@@ -0,0 +1,55 @@
1
+ import type { Caption, Clip, ContextChangeSet, ContextRevision, EditOperation, EditorIdentity, EditorPort, ManagedArtifact, EditorAsset, AssetSearchQuery, MediaContext, Marker, ProjectSnapshot, ProjectCatalog, ProjectSelection, ProjectSelectionResult, RationalTime, RuntimeCapabilities, CapturedFrameSource, WorkflowOperation } from "../../runtime/src/index.js";
2
+ export interface InMemoryProjectFixture {
3
+ projectId: string;
4
+ projectName: string;
5
+ timelineId: string;
6
+ timelineName: string;
7
+ frameDuration?: RationalTime;
8
+ clips: Array<Omit<Clip, "startTime" | "durationTime"> & Partial<Pick<Clip, "startTime" | "durationTime">>>;
9
+ media?: MediaContext[];
10
+ markers?: Marker[];
11
+ captions?: Caption[];
12
+ assets?: EditorAsset[];
13
+ frames?: Array<{
14
+ position: RationalTime;
15
+ timecode: string;
16
+ image: CapturedFrameSource["image"];
17
+ }>;
18
+ }
19
+ export interface InMemoryFixture extends InMemoryProjectFixture {
20
+ projects?: ProjectCatalog["projects"];
21
+ /** Canonical snapshots available for explicit project selection. */
22
+ projectSnapshots?: InMemoryProjectFixture[];
23
+ }
24
+ export declare class InMemoryEditorAdapter implements EditorPort {
25
+ getManagedArtifact?: () => Promise<ManagedArtifact>;
26
+ private snapshot;
27
+ private readonly assets;
28
+ private readonly history;
29
+ private readonly snapshotsByTarget;
30
+ private readonly projects;
31
+ private activeProjectId;
32
+ private activeSequenceId;
33
+ private selectionRevision;
34
+ private readonly framesByTarget;
35
+ constructor(fixture: InMemoryFixture);
36
+ read(): Promise<ProjectSnapshot>;
37
+ readProject(): Promise<ProjectSnapshot>;
38
+ getIdentity(): Promise<EditorIdentity>;
39
+ getCapabilities(): Promise<RuntimeCapabilities>;
40
+ captureFrame(position: RationalTime, expectedRevision: ContextRevision): Promise<CapturedFrameSource>;
41
+ private activeFrames;
42
+ listAssets(query?: AssetSearchQuery): Promise<EditorAsset[]>;
43
+ listProjects(): Promise<ProjectCatalog>;
44
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
45
+ readChanges(since: ContextRevision): Promise<ContextChangeSet>;
46
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
47
+ previewTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<ProjectSnapshot>;
48
+ applyTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<void>;
49
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
50
+ private applyOperation;
51
+ private updateClip;
52
+ private applyRippleDelete;
53
+ private assertRevision;
54
+ private nextSnapshot;
55
+ }
@@ -733,10 +733,10 @@ export class InMemoryEditorAdapter {
733
733
  applyRippleDelete(snapshot, timelineId, start, end) {
734
734
  if (timelineId !== snapshot.timeline.id)
735
735
  throw new Error(`TIMELINE_NOT_FOUND: ${timelineId}`);
736
- if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start) {
737
- throw new Error("INVALID_OPERATION: ripple delete range must be positive");
736
+ if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
737
+ throw new Error(`INVALID_OPERATION: ripple delete range [${start}, ${end}) must be increasing`);
738
738
  }
739
- if (end > snapshot.timeline.duration) {
739
+ if (start < 0 || end > snapshot.timeline.duration) {
740
740
  throw new Error(`INVALID_OPERATION: ripple delete range [${start}, ${end}) must fit timeline bounds [0, ${snapshot.timeline.duration})`);
741
741
  }
742
742
  const removedDuration = end - start;
@@ -0,0 +1,4 @@
1
+ export * from "./in-memory-editor.js";
2
+ export * from "./fixture-analyzers.js";
3
+ export * from "./skill-fixtures.js";
4
+ export * from "./sender-lifecycle-fixture.js";
@@ -1,3 +1,4 @@
1
1
  export * from "./in-memory-editor.js";
2
2
  export * from "./fixture-analyzers.js";
3
3
  export * from "./skill-fixtures.js";
4
+ export * from "./sender-lifecycle-fixture.js";
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Experimental subprocess fixture. This is not a production coordinator,
3
+ * authenticated journal, native receiver, or reservation recovery mechanism.
4
+ * Callers must supply a disposable, isolated directory and synthetic identity.
5
+ */
6
+ import { type ChildProcessWithoutNullStreams } from "node:child_process";
7
+ export interface SenderFixtureBinding {
8
+ reservationId: string;
9
+ /** Synthetic immutable intent bytes; never treated as authenticated production state. */
10
+ reservationBytes: string;
11
+ reservationVersion: 3 | 4;
12
+ route: "publish" | "materialization";
13
+ owner: string;
14
+ /** Caller-provided fixture identity; not authenticated by the intent or receiver. */
15
+ executionId: string;
16
+ }
17
+ export interface SenderFixtureObservation {
18
+ status: "active-or-interrupted" | "abort-requested" | "sender-settled" | "unknown";
19
+ evidenceTrust: "unverified-fixture-marker";
20
+ nativeQuiescence: "unproven";
21
+ recoveryEligibility: "unavailable";
22
+ }
23
+ /** Read untrusted fixture markers; sender settlement never proves receiver state. */
24
+ export declare function inspectSenderFixture(directory: string, b: SenderFixtureBinding, hooks?: {
25
+ beforeRecheck?: () => Promise<void>;
26
+ }): Promise<SenderFixtureObservation>;
27
+ /**
28
+ * Start a disposable fixture child only after an exclusive, durable marker.
29
+ * It deliberately has no production callers and never changes a reservation.
30
+ * PID is not persisted or used as evidence; markers are not authenticated.
31
+ * Callers must consume child.stdout and child.stderr, or bound the process with
32
+ * timeoutMs or abort(); unread output can fill the pipes and block the child.
33
+ * After direct-child exit, inherited local pipes are bounded and may be closed;
34
+ * this neither proves descendant termination nor native receiver quiescence.
35
+ * Descendant writes to a closed pipe may observe EPIPE or SIGPIPE.
36
+ */
37
+ export declare function startSenderFixture(directory: string, input: SenderFixtureBinding, options: {
38
+ command: string;
39
+ args: string[];
40
+ timeoutMs?: number;
41
+ killAfterMs?: number;
42
+ }): Promise<{
43
+ child: ChildProcessWithoutNullStreams;
44
+ abort(): Promise<void>;
45
+ closed: Promise<void>;
46
+ localStatus(): "active" | "abort-requested" | "sender-settled" | "unknown";
47
+ }>;