@morshoto/framekit 0.2.2 → 0.2.4

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 (160) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -0,0 +1,101 @@
1
+ import type { ContextRevision, EditOperation, EditorChange, EditorLiveState, EditorIdentity, RuntimeCapabilities, LiveEditorStatePort, ProjectCatalog, ProjectSnapshot, ProjectSelection, ProjectSelectionResult } from "../../../../packages/runtime/src/index.js";
2
+ export declare const FINAL_CUT_LIVE_PROTOCOL_VERSION = 1;
3
+ /** Shared deterministic endpoint used by both the Node client and Swift host. */
4
+ export declare const DEFAULT_FINAL_CUT_LIVE_SOCKET: string;
5
+ export type FinalCutLiveMethod = "capabilities" | "state" | "changes" | "projects" | "select-project" | "snapshot" | "apply" | "restore" | "deliver-fcpxml";
6
+ export interface FinalCutFcpxmlDeliveryRequest {
7
+ artifactPath: string;
8
+ targetLibraryLocation?: string;
9
+ activates: boolean;
10
+ }
11
+ export interface FinalCutFcpxmlDelivery {
12
+ status: "dispatched" | "user-interaction-required" | "failed";
13
+ route: "background-document-open";
14
+ attempted: boolean;
15
+ imported: boolean;
16
+ requestedActivates: boolean;
17
+ activation: "preserved" | "activated" | "unknown";
18
+ ui: "none" | "prompted" | "displayed" | "unknown";
19
+ target: {
20
+ requestedLibraryLocation?: string;
21
+ guarantee: "requested-unverified" | "unavailable";
22
+ };
23
+ error?: {
24
+ code: string;
25
+ message: string;
26
+ };
27
+ }
28
+ export interface FinalCutLiveRequest {
29
+ version: number;
30
+ id: string;
31
+ method: FinalCutLiveMethod;
32
+ afterSequence?: number;
33
+ waitMs?: number;
34
+ projectId?: string;
35
+ sequenceId?: string;
36
+ artifactPath?: string;
37
+ targetLibraryLocation?: string;
38
+ activates?: boolean;
39
+ operation?: EditOperation;
40
+ expectedRevision?: ContextRevision;
41
+ snapshot?: ProjectSnapshot;
42
+ }
43
+ export type FinalCutLiveResponse = {
44
+ version: number;
45
+ id: string;
46
+ ok: true;
47
+ result: {
48
+ identity: EditorIdentity;
49
+ capabilities: RuntimeCapabilities;
50
+ state?: EditorLiveState;
51
+ changes?: EditorChange[];
52
+ catalog?: ProjectCatalog;
53
+ snapshot?: ProjectSnapshot;
54
+ revision?: ContextRevision;
55
+ delivery?: FinalCutFcpxmlDelivery;
56
+ };
57
+ } | {
58
+ version: number;
59
+ id: string;
60
+ ok: false;
61
+ error: {
62
+ code: string;
63
+ message: string;
64
+ };
65
+ };
66
+ export interface FinalCutLiveTransport {
67
+ request(request: FinalCutLiveRequest): Promise<FinalCutLiveResponse>;
68
+ }
69
+ export interface FinalCutLiveInspection {
70
+ identity: EditorIdentity;
71
+ capabilities: RuntimeCapabilities;
72
+ }
73
+ /** Newline-delimited JSON transport for the local Workflow Extension socket. */
74
+ export declare class UnixSocketFinalCutLiveTransport implements FinalCutLiveTransport {
75
+ private readonly socketPath;
76
+ private readonly timeoutMs;
77
+ constructor(socketPath: string, timeoutMs?: number);
78
+ request(request: FinalCutLiveRequest): Promise<FinalCutLiveResponse>;
79
+ private requestOnce;
80
+ }
81
+ export declare class FinalCutLiveAdapter implements LiveEditorStatePort {
82
+ private readonly transport;
83
+ private readonly socketPath;
84
+ private selectedTarget?;
85
+ constructor(transport: FinalCutLiveTransport, socketPath?: string);
86
+ inspect(): Promise<FinalCutLiveInspection>;
87
+ getIdentity(): Promise<EditorIdentity>;
88
+ getCapabilities(): Promise<RuntimeCapabilities>;
89
+ read(): Promise<ProjectSnapshot>;
90
+ readProject(): Promise<ProjectSnapshot>;
91
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
92
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
93
+ readLiveState(): Promise<EditorLiveState>;
94
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
95
+ deliverFcpxml(request: FinalCutFcpxmlDeliveryRequest): Promise<FinalCutFcpxmlDelivery>;
96
+ listProjects(): Promise<ProjectCatalog>;
97
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
98
+ private assertSelectedTargetActive;
99
+ private request;
100
+ }
101
+ export declare function createFinalCutLiveAdapter(socketPath?: string): FinalCutLiveAdapter;
@@ -287,6 +287,14 @@ function validateCanonicalSnapshot(snapshot) {
287
287
  requireNonEmpty(media.source, `media ${media.mediaId} source`);
288
288
  if (media.duration !== undefined)
289
289
  requireFiniteNonNegative(media.duration, `media ${media.mediaId} duration`);
290
+ if (media.sourceRange !== undefined) {
291
+ requireRecord(media.sourceRange, `media ${media.mediaId} source range`);
292
+ requireRational(media.sourceRange.start, `media ${media.mediaId} source range start`);
293
+ requireRational(media.sourceRange.duration, `media ${media.mediaId} source range duration`);
294
+ if (BigInt(media.sourceRange.duration.value) <= 0n) {
295
+ protocolError(`media ${media.mediaId} source range duration must be positive`);
296
+ }
297
+ }
290
298
  }
291
299
  const mediaIds = uniqueIds(snapshot.media, ({ mediaId }) => mediaId, "media");
292
300
  uniqueIds(snapshot.timeline.markers, ({ id }) => id, "marker");
@@ -0,0 +1,12 @@
1
+ import type { MediaContext, MediaSearchQuery } from "../../../../packages/runtime/src/index.js";
2
+ export interface FinalCutMediaRegistryOptions {
3
+ roots?: string[];
4
+ }
5
+ /** Read-only local media discovery that never contacts or activates Final Cut. */
6
+ export declare class FinalCutMediaRegistry {
7
+ private readonly roots;
8
+ private cached?;
9
+ constructor(options?: FinalCutMediaRegistryOptions);
10
+ listMedia(query?: MediaSearchQuery): Promise<MediaContext[]>;
11
+ refresh(): void;
12
+ }
@@ -0,0 +1,6 @@
1
+ export interface NativeOperationLease {
2
+ acquire(): void;
3
+ release(): void;
4
+ }
5
+ /** Coordinates one shared native-operation suspension across nested adapters. */
6
+ export declare function createNativeOperationLease(suspend?: () => void, resume?: () => void): NativeOperationLease;
@@ -0,0 +1,77 @@
1
+ /** Requested evidence only: none of these fields establishes dispatch or quiescence. */
2
+ export interface NativeMaterializationRecoveryContext {
3
+ kind: "materialization";
4
+ jobId: string;
5
+ dispatchId: string;
6
+ requestedTarget: {
7
+ libraryUid: string;
8
+ eventUid: string;
9
+ projectUid: string;
10
+ sequenceUid: string;
11
+ };
12
+ artifactDigest: string;
13
+ desiredDigest: string;
14
+ destination?: {
15
+ mode: "versioned";
16
+ projectUid: string;
17
+ sequenceUid: string;
18
+ projectName: string;
19
+ sequenceName: string;
20
+ };
21
+ executorIdentity: null;
22
+ nativeQuiescence: "unproven";
23
+ }
24
+ /** Requested library only; it is not a verified native target. */
25
+ export interface NativePublishRecoveryContext {
26
+ kind: "publish";
27
+ jobId: string;
28
+ dispatchId: string;
29
+ requestedTarget: {
30
+ libraryPath: string;
31
+ };
32
+ artifactDigest: string;
33
+ executorIdentity: null;
34
+ nativeQuiescence: "unproven";
35
+ }
36
+ /** A planned receiver identity and target, not proof that dispatch or completion occurred. */
37
+ export type RecoverableNativeContext = (Omit<NativeMaterializationRecoveryContext, "executorIdentity"> | Omit<NativePublishRecoveryContext, "executorIdentity">) & {
38
+ executorIdentity: string;
39
+ dispatchState: "intent";
40
+ canonicalTarget: Record<string, string>;
41
+ expectedCanonicalDigest: string;
42
+ expectedRestoreDigest?: string;
43
+ };
44
+ export type NativeRecoveryContext = NativeMaterializationRecoveryContext | NativePublishRecoveryContext | RecoverableNativeContext;
45
+ export declare function validRecoveryContext(value: unknown, operation: string): value is NativeMaterializationRecoveryContext | NativePublishRecoveryContext;
46
+ /** Observational evidence, never an authorization to recover or dispatch. */
47
+ export interface NativeRecoveryInspection {
48
+ status: "clear" | "recovery-required" | "unknown";
49
+ nativeQuiescence: "unproven";
50
+ recoveryEligibility: "unavailable";
51
+ sender: {
52
+ status: "untracked" | "active-or-interrupted" | "sender-settled" | "unknown";
53
+ };
54
+ reservation?: {
55
+ version: 2 | 3 | 4;
56
+ reservationId: string;
57
+ operation: string;
58
+ jobId?: string;
59
+ dispatchId?: string;
60
+ jobCorrelation?: "unverified";
61
+ };
62
+ dispatchState?: "possibly-dispatched";
63
+ boundaryEvidence?: "dispatch-possible-recorded" | "unknown";
64
+ missingEvidence?: ["receiver-terminal-quiescence", "independent-target-outcome", "legacy-writer-exclusion"];
65
+ safeNextActions?: ["inspect", "retain-reservation"];
66
+ intent?: {
67
+ requestedTarget: NativeRecoveryContext["requestedTarget"];
68
+ artifactDigest: string;
69
+ desiredDigest?: string;
70
+ destination?: NativeMaterializationRecoveryContext["destination"];
71
+ };
72
+ }
73
+ /**
74
+ * Read-only, point-in-time observation; old writers do not share a lock, so even
75
+ * repeated reads cannot exclude concurrent changes or establish quiescence.
76
+ */
77
+ export declare function inspectNativeRecoveryReadOnly(path: string): Promise<NativeRecoveryInspection>;
@@ -0,0 +1,130 @@
1
+ import type { ContextRevision } from "../../../../packages/runtime/src/index.js";
2
+ import type { DisposableNativeEditWorkflow } from "./disposable-native.js";
3
+ import type { NativeFinalCutEditor } from "./native.js";
4
+ import type { NativeFinalCutReadiness } from "./native.js";
5
+ import type { FileCanonicalRecoveryGuard } from "./canonical-recovery-guard.js";
6
+ export type NativeOperationSessionState = "planned" | "waiting_for_final_cut" | "executing" | "verifying" | "completed" | "rolled_back" | "failed" | "cancelled";
7
+ export interface NativeOperationSessionRequest {
8
+ operation: string;
9
+ previewToken: string;
10
+ projectId: string;
11
+ sequenceId: string;
12
+ targetIdentity: string;
13
+ baseRevision: ContextRevision;
14
+ idempotencyKey: string;
15
+ }
16
+ export interface NativeOperationReadinessResult {
17
+ readiness: NativeFinalCutReadiness;
18
+ error?: {
19
+ code: string;
20
+ message: string;
21
+ };
22
+ }
23
+ export interface NativeOperationSessionEvidence {
24
+ readback: {
25
+ status: "verified" | "unverified";
26
+ revision?: ContextRevision;
27
+ detail: string;
28
+ };
29
+ diff: {
30
+ added: number;
31
+ removed: number;
32
+ modified: number;
33
+ };
34
+ verification: {
35
+ status: "verified" | "failed";
36
+ checks: Array<{
37
+ name: string;
38
+ passed: boolean;
39
+ detail: string;
40
+ }>;
41
+ };
42
+ rollback: {
43
+ status: "available" | "restored" | "not-required" | "failed" | "unknown";
44
+ operationId?: string;
45
+ detail: string;
46
+ };
47
+ }
48
+ export interface NativeOperationSessionExecution {
49
+ outcome: "completed" | "rolled_back";
50
+ evidence: NativeOperationSessionEvidence;
51
+ }
52
+ export interface NativeOperationExecutionContext {
53
+ signal: AbortSignal;
54
+ markMutationStarted(): void;
55
+ }
56
+ export interface NativeOperationSessionExecutor {
57
+ checkReadiness(request: NativeOperationSessionRequest, options: Pick<NativeOperationExecutionContext, "signal">): Promise<NativeOperationReadinessResult>;
58
+ revalidate(request: NativeOperationSessionRequest, options: Pick<NativeOperationExecutionContext, "signal">): Promise<void>;
59
+ execute(request: NativeOperationSessionRequest, context: NativeOperationExecutionContext): Promise<NativeOperationSessionExecution>;
60
+ }
61
+ export interface NativeOperationSessionError {
62
+ code: string;
63
+ message: string;
64
+ retryable: boolean;
65
+ recovery?: "required";
66
+ }
67
+ export interface NativeOperationSessionJob {
68
+ jobId: string;
69
+ operation: string;
70
+ previewToken: string;
71
+ projectId: string;
72
+ sequenceId: string;
73
+ targetIdentity: string;
74
+ baseRevision: ContextRevision;
75
+ idempotencyKey: string;
76
+ state: NativeOperationSessionState;
77
+ accepted: boolean;
78
+ completed: boolean;
79
+ verified: boolean;
80
+ restored: boolean;
81
+ cancelRequested: boolean;
82
+ submittedAt: string;
83
+ updatedAt: string;
84
+ expiresAt: string;
85
+ readiness?: NativeOperationReadinessResult["readiness"];
86
+ evidence?: NativeOperationSessionEvidence;
87
+ error?: NativeOperationSessionError;
88
+ }
89
+ export interface NativeOperationSessionOptions {
90
+ executor: NativeOperationSessionExecutor;
91
+ now?: () => number;
92
+ jobTtlMs?: number;
93
+ jobRetentionMs?: number;
94
+ }
95
+ /**
96
+ * Coordinates previewed native work without turning unavailable Final Cut UI
97
+ * into a blocking MCP request. Job records intentionally remain process-local.
98
+ */
99
+ export declare class NativeOperationSession {
100
+ private readonly options;
101
+ private readonly jobs;
102
+ private readonly idempotency;
103
+ private readonly now;
104
+ private readonly jobTtlMs;
105
+ private readonly jobRetentionMs;
106
+ constructor(options: NativeOperationSessionOptions);
107
+ submit(request: NativeOperationSessionRequest): Promise<NativeOperationSessionJob>;
108
+ status(jobId: string): NativeOperationSessionJob;
109
+ retry(jobId: string): Promise<NativeOperationSessionJob>;
110
+ cancel(jobId: string): Promise<NativeOperationSessionJob>;
111
+ private process;
112
+ private handleFailure;
113
+ private expire;
114
+ private isExpired;
115
+ private expireIfNeeded;
116
+ private pruneExpiredJobs;
117
+ private setState;
118
+ private requireJob;
119
+ private snapshot;
120
+ }
121
+ export interface DisposableNativeOperationSessionOptions {
122
+ workflow: Pick<DisposableNativeEditWorkflow, "execute" | "getPreview">;
123
+ native: Pick<NativeFinalCutEditor, "inspect" | "trackNativeDispatch">;
124
+ recoveryGuard?: Pick<FileCanonicalRecoveryGuard, "beginNative">;
125
+ now?: () => number;
126
+ jobTtlMs?: number;
127
+ jobRetentionMs?: number;
128
+ }
129
+ /** Adapts the existing canonical disposable rename workflow to session jobs. */
130
+ export declare function createDisposableNativeOperationSession(options: DisposableNativeOperationSessionOptions): NativeOperationSession;