@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.
- package/README.md +17 -12
- package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
- package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
- package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
- package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
- package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
- package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
- package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
- package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
- package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
- package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
- package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
- package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
- package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
- package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
- package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
- package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
- package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
- package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
- package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
- package/dist-package/apps/cli/src/dev-doctor.js +198 -0
- package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
- package/dist-package/apps/cli/src/headless-projects.js +5 -0
- package/dist-package/apps/cli/src/main.d.ts +10 -0
- package/dist-package/apps/cli/src/main.js +42 -0
- package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
- package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
- package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
- package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
- package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
- package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
- package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
- package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
- package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
- package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
- package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
- package/dist-package/apps/mcp-server/src/main.js +24 -19
- package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
- package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
- package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
- package/dist-package/apps/mcp-server/src/routing.js +2 -0
- package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
- package/dist-package/apps/mcp-server/src/server.js +813 -158
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
- package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
- package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
- package/dist-package/packages/headless-application/src/external-edit.js +72 -0
- package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
- package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
- package/dist-package/packages/headless-application/src/index.d.ts +2 -0
- package/dist-package/packages/headless-application/src/index.js +2 -0
- package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
- package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
- package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
- package/dist-package/packages/runtime/src/application/project-service.js +5 -1
- package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
- package/dist-package/packages/runtime/src/application/project-store.js +13 -36
- package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
- package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
- package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
- package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
- package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
- package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
- package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
- package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
- package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
- package/dist-package/packages/runtime/src/capabilities.js +1 -1
- package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
- package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
- package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
- package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
- package/dist-package/packages/runtime/src/context/context-service.js +2 -2
- package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
- package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
- package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
- package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
- package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
- package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
- package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
- package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
- package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
- package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
- package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
- package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
- package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
- package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
- package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
- package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
- package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
- package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
- package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
- package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
- package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
- package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
- package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
- package/dist-package/packages/runtime/src/index.d.ts +32 -0
- package/dist-package/packages/runtime/src/index.js +2 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
- package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
- package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
- package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
- package/dist-package/packages/runtime/src/runtime.js +16 -7
- package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
- package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
- package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
- package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
- package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
- package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
- package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
- package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
- package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
- package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
- package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
- package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
- package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
- package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
- package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
- package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
- package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
- package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
- package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
- package/dist-package/packages/testkit/src/index.d.ts +4 -0
- package/dist-package/packages/testkit/src/index.js +1 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
- package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
- package/package.json +41 -14
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import type { ProjectCatalog, RationalTime } from "../../../../packages/runtime/src/index.js";
|
|
2
|
+
export declare const FINAL_CUT_LIBRARY_INSPECTION_BACKEND: "final-cut-background-library";
|
|
3
|
+
export declare const FINAL_CUT_LIBRARY_INSPECTION_TIMEOUT_MS = 30000;
|
|
4
|
+
export type FinalCutLibraryInspectionIssueCode = "FINAL_CUT_LIBRARY_FIELD_UNAVAILABLE" | "FINAL_CUT_LIBRARY_INSPECTION_UNAVAILABLE" | "FINAL_CUT_LIBRARY_RESPONSE_INVALID" | "FINAL_CUT_LIBRARY_TIME_INVALID";
|
|
5
|
+
export interface FinalCutLibraryInspectionIssue {
|
|
6
|
+
code: FinalCutLibraryInspectionIssueCode;
|
|
7
|
+
message: string;
|
|
8
|
+
path?: string;
|
|
9
|
+
retryable: boolean;
|
|
10
|
+
}
|
|
11
|
+
export type FinalCutLibraryInspectionField<T> = {
|
|
12
|
+
status: "available";
|
|
13
|
+
value: T;
|
|
14
|
+
} | {
|
|
15
|
+
status: "unavailable";
|
|
16
|
+
issue: FinalCutLibraryInspectionIssue;
|
|
17
|
+
};
|
|
18
|
+
export interface FinalCutLibraryInspectionSequence {
|
|
19
|
+
id: string;
|
|
20
|
+
name: string;
|
|
21
|
+
startTime: FinalCutLibraryInspectionField<RationalTime>;
|
|
22
|
+
duration: FinalCutLibraryInspectionField<RationalTime>;
|
|
23
|
+
frameDuration: FinalCutLibraryInspectionField<RationalTime>;
|
|
24
|
+
}
|
|
25
|
+
export interface FinalCutLibraryInspectionProject {
|
|
26
|
+
id: string;
|
|
27
|
+
name: string;
|
|
28
|
+
sequences: FinalCutLibraryInspectionSequence[];
|
|
29
|
+
}
|
|
30
|
+
export interface FinalCutLibraryInspectionEvent {
|
|
31
|
+
id: string;
|
|
32
|
+
name: string;
|
|
33
|
+
projects: FinalCutLibraryInspectionProject[];
|
|
34
|
+
}
|
|
35
|
+
export interface FinalCutLibraryInspectionLibrary {
|
|
36
|
+
id: string;
|
|
37
|
+
name: string;
|
|
38
|
+
path?: string;
|
|
39
|
+
events: FinalCutLibraryInspectionEvent[];
|
|
40
|
+
}
|
|
41
|
+
export interface FinalCutLibraryInspectionCatalog {
|
|
42
|
+
libraries: FinalCutLibraryInspectionLibrary[];
|
|
43
|
+
}
|
|
44
|
+
export interface FinalCutLibraryInspectionError {
|
|
45
|
+
code: FinalCutLibraryInspectionIssueCode;
|
|
46
|
+
message: string;
|
|
47
|
+
retryable: boolean;
|
|
48
|
+
}
|
|
49
|
+
export type FinalCutLibraryInspectionResult = {
|
|
50
|
+
status: "available";
|
|
51
|
+
catalog: FinalCutLibraryInspectionCatalog;
|
|
52
|
+
} | {
|
|
53
|
+
status: "partial";
|
|
54
|
+
catalog: FinalCutLibraryInspectionCatalog;
|
|
55
|
+
issues: FinalCutLibraryInspectionIssue[];
|
|
56
|
+
} | {
|
|
57
|
+
status: "unavailable";
|
|
58
|
+
error: FinalCutLibraryInspectionError;
|
|
59
|
+
} | {
|
|
60
|
+
status: "error";
|
|
61
|
+
error: FinalCutLibraryInspectionError;
|
|
62
|
+
};
|
|
63
|
+
export interface FinalCutLibraryInspectionProviderOptions {
|
|
64
|
+
executor?: (script: string, timeoutMs: number) => Promise<string>;
|
|
65
|
+
applicationIdentifier?: string;
|
|
66
|
+
}
|
|
67
|
+
/** Structured failure raised when project.list cannot use the background provider. */
|
|
68
|
+
export declare class FinalCutLibraryInspectionProviderError extends Error {
|
|
69
|
+
readonly failure: FinalCutLibraryInspectionError;
|
|
70
|
+
readonly code: FinalCutLibraryInspectionIssueCode;
|
|
71
|
+
readonly retryable: boolean;
|
|
72
|
+
constructor(failure: FinalCutLibraryInspectionError);
|
|
73
|
+
toJSON(): FinalCutLibraryInspectionError;
|
|
74
|
+
}
|
|
75
|
+
export declare function serializeFinalCutLibraryInspectionError(error: unknown): FinalCutLibraryInspectionError | undefined;
|
|
76
|
+
/** Read-only Final Cut library inspection through direct Apple Events. */
|
|
77
|
+
export declare class FinalCutLibraryInspectionProvider {
|
|
78
|
+
readonly backend: "final-cut-background-library";
|
|
79
|
+
private readonly executor;
|
|
80
|
+
private readonly applicationIdentifier;
|
|
81
|
+
constructor(options?: FinalCutLibraryInspectionProviderOptions);
|
|
82
|
+
inspect(): Promise<FinalCutLibraryInspectionResult>;
|
|
83
|
+
listProjects(): Promise<ProjectCatalog>;
|
|
84
|
+
/** Bind a newly imported project to the exact library location requested by its FCPXML. */
|
|
85
|
+
resolveProjectBinding(libraryPath: string, identity: {
|
|
86
|
+
projectName: string;
|
|
87
|
+
sequenceName: string;
|
|
88
|
+
}): Promise<{
|
|
89
|
+
projectId: string;
|
|
90
|
+
sequenceId: string;
|
|
91
|
+
libraryId: string;
|
|
92
|
+
eventId: string;
|
|
93
|
+
libraryPath: string;
|
|
94
|
+
}>;
|
|
95
|
+
}
|
|
96
|
+
/** Build the JXA program used for direct, read-only Final Cut Apple Events. */
|
|
97
|
+
export declare function buildFinalCutLibraryInspectionScript(applicationIdentifier?: string): string;
|
|
98
|
+
/** Parse the JSON envelope returned by the direct Final Cut Apple Event query. */
|
|
99
|
+
export declare function parseFinalCutLibraryInspectionResponse(input: string | unknown): FinalCutLibraryInspectionResult;
|
|
100
|
+
/** Flatten safely discoverable project identities for the existing project.list contract. */
|
|
101
|
+
export declare function toFinalCutProjectCatalog(catalog: FinalCutLibraryInspectionCatalog): ProjectCatalog;
|
|
@@ -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;
|
|
@@ -13,6 +13,8 @@ const READ_ONLY_LIVE_METHODS = new Set([
|
|
|
13
13
|
"projects",
|
|
14
14
|
"snapshot",
|
|
15
15
|
]);
|
|
16
|
+
// The extension waits up to five seconds for NSWorkspace's completion handler.
|
|
17
|
+
const DOCUMENT_DELIVERY_TIMEOUT_MS = 7_000;
|
|
16
18
|
/** Newline-delimited JSON transport for the local Workflow Extension socket. */
|
|
17
19
|
export class UnixSocketFinalCutLiveTransport {
|
|
18
20
|
socketPath;
|
|
@@ -52,7 +54,7 @@ export class UnixSocketFinalCutLiveTransport {
|
|
|
52
54
|
};
|
|
53
55
|
const timer = setTimeout(() => {
|
|
54
56
|
finish(() => reject(new Error(`FINAL_CUT_LIVE_TIMEOUT: ${this.socketPath}`)));
|
|
55
|
-
}, this.timeoutMs);
|
|
57
|
+
}, request.method === "deliver-fcpxml" ? Math.max(this.timeoutMs, DOCUMENT_DELIVERY_TIMEOUT_MS) : this.timeoutMs);
|
|
56
58
|
socket = createConnection(this.socketPath);
|
|
57
59
|
socket.setEncoding("utf8");
|
|
58
60
|
socket.on("connect", () => {
|
|
@@ -90,6 +92,7 @@ export class UnixSocketFinalCutLiveTransport {
|
|
|
90
92
|
export class FinalCutLiveAdapter {
|
|
91
93
|
transport;
|
|
92
94
|
socketPath;
|
|
95
|
+
selectedTarget;
|
|
93
96
|
constructor(transport, socketPath = "configured-socket") {
|
|
94
97
|
this.transport = transport;
|
|
95
98
|
this.socketPath = socketPath;
|
|
@@ -125,6 +128,11 @@ export class FinalCutLiveAdapter {
|
|
|
125
128
|
throw new Error("FINAL_CUT_LIVE_PROTOCOL: snapshot response was empty");
|
|
126
129
|
validateCanonicalSnapshot(response.snapshot);
|
|
127
130
|
validateSnapshotTarget(response.snapshot, await this.listProjects());
|
|
131
|
+
if (this.selectedTarget
|
|
132
|
+
&& (response.snapshot.projectId !== this.selectedTarget.projectId
|
|
133
|
+
|| response.snapshot.timeline.id !== this.selectedTarget.sequenceId)) {
|
|
134
|
+
throw new Error("TARGET_MISMATCH: live canonical snapshot differs from the explicitly selected project and sequence");
|
|
135
|
+
}
|
|
128
136
|
return response.snapshot;
|
|
129
137
|
}
|
|
130
138
|
async apply(operation, expectedRevision) {
|
|
@@ -133,6 +141,7 @@ export class FinalCutLiveAdapter {
|
|
|
133
141
|
if (capabilities.editor.canonicalTimelineMode !== "canonical-write") {
|
|
134
142
|
throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut canonical mutation");
|
|
135
143
|
}
|
|
144
|
+
await this.assertSelectedTargetActive();
|
|
136
145
|
const response = await this.request({ method: "apply", operation, expectedRevision });
|
|
137
146
|
if (!response.revision)
|
|
138
147
|
throw new Error("FINAL_CUT_LIVE_PROTOCOL: apply response revision was empty");
|
|
@@ -148,6 +157,10 @@ export class FinalCutLiveAdapter {
|
|
|
148
157
|
if (capabilities.editor.canonicalTimelineMode !== "canonical-write") {
|
|
149
158
|
throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut canonical rollback");
|
|
150
159
|
}
|
|
160
|
+
await this.assertSelectedTargetActive();
|
|
161
|
+
if (this.selectedTarget && (snapshot.projectId !== this.selectedTarget.projectId || snapshot.timeline.id !== this.selectedTarget.sequenceId)) {
|
|
162
|
+
throw new Error("TARGET_MISMATCH: rollback snapshot differs from the explicitly selected project and sequence");
|
|
163
|
+
}
|
|
151
164
|
await this.request({ method: "restore", snapshot, expectedRevision });
|
|
152
165
|
}
|
|
153
166
|
async readLiveState() {
|
|
@@ -204,7 +217,19 @@ export class FinalCutLiveAdapter {
|
|
|
204
217
|
if (!response.revision)
|
|
205
218
|
throw new Error("FINAL_CUT_LIVE_PROTOCOL: project selection response revision was empty");
|
|
206
219
|
validateRevision(response.revision, "project selection response revision");
|
|
207
|
-
|
|
220
|
+
const result = createProjectSelectionResult(response.catalog, selection, response.revision);
|
|
221
|
+
this.selectedTarget = { ...result.observedActiveTarget };
|
|
222
|
+
return result;
|
|
223
|
+
}
|
|
224
|
+
async assertSelectedTargetActive() {
|
|
225
|
+
const selected = this.selectedTarget;
|
|
226
|
+
if (!selected)
|
|
227
|
+
return;
|
|
228
|
+
const catalog = await this.listProjects();
|
|
229
|
+
if (this.selectedTarget !== selected
|
|
230
|
+
|| catalog.activeProjectId !== selected.projectId || catalog.activeSequenceId !== selected.sequenceId) {
|
|
231
|
+
throw new Error("TARGET_MISMATCH: active project and sequence differ from the explicitly selected target");
|
|
232
|
+
}
|
|
208
233
|
}
|
|
209
234
|
async request(input) {
|
|
210
235
|
const response = await this.transport.request({
|
|
@@ -262,6 +287,14 @@ function validateCanonicalSnapshot(snapshot) {
|
|
|
262
287
|
requireNonEmpty(media.source, `media ${media.mediaId} source`);
|
|
263
288
|
if (media.duration !== undefined)
|
|
264
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
|
+
}
|
|
265
298
|
}
|
|
266
299
|
const mediaIds = uniqueIds(snapshot.media, ({ mediaId }) => mediaId, "media");
|
|
267
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,175 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { constants } from "node:fs";
|
|
3
|
+
import { lstat, open } from "node:fs/promises";
|
|
4
|
+
import { isAbsolute, join } from "node:path";
|
|
5
|
+
function validPublishContext(value, operation) {
|
|
6
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
7
|
+
return false;
|
|
8
|
+
const c = value;
|
|
9
|
+
const path = c.requestedTarget?.libraryPath;
|
|
10
|
+
return c.kind === "publish"
|
|
11
|
+
&& typeof c.jobId === "string" && /^publish-job-[a-z0-9-]{1,80}$/.test(c.jobId)
|
|
12
|
+
&& operation === `native.publish.${createHash("sha256").update(c.jobId).digest("hex")}`
|
|
13
|
+
&& typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
|
|
14
|
+
&& typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
|
|
15
|
+
&& typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
|
|
16
|
+
&& c.executorIdentity === null && c.nativeQuiescence === "unproven";
|
|
17
|
+
}
|
|
18
|
+
export function validRecoveryContext(value, operation) {
|
|
19
|
+
return validMaterializationContext(value, operation) || validPublishContext(value, operation);
|
|
20
|
+
}
|
|
21
|
+
function validRecoverableContext(value, operation) {
|
|
22
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
23
|
+
return false;
|
|
24
|
+
const c = value;
|
|
25
|
+
if (typeof c.executorIdentity !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(c.executorIdentity)
|
|
26
|
+
|| c.dispatchState !== "intent" || !/^[a-f0-9]{64}$/.test(c.expectedCanonicalDigest)
|
|
27
|
+
|| (c.expectedRestoreDigest !== undefined && !/^[a-f0-9]{64}$/.test(c.expectedRestoreDigest))
|
|
28
|
+
|| !validRecoveryContext({ ...c, executorIdentity: null }, operation))
|
|
29
|
+
return false;
|
|
30
|
+
const t = c.canonicalTarget;
|
|
31
|
+
if (!t || typeof t !== "object" || Array.isArray(t))
|
|
32
|
+
return false;
|
|
33
|
+
const keys = c.kind === "publish" ? ["libraryPath", "projectUid", "sequenceUid"] : ["libraryUid", "eventUid", "projectUid", "sequenceUid"];
|
|
34
|
+
if (Object.keys(t).length !== keys.length || !keys.every((key) => typeof t[key] === "string" && t[key].trim().length > 0 && t[key].length <= 1024))
|
|
35
|
+
return false;
|
|
36
|
+
if (c.kind === "publish")
|
|
37
|
+
return t.libraryPath === c.requestedTarget.libraryPath;
|
|
38
|
+
return keys.every((key) => t[key] === c.requestedTarget[key])
|
|
39
|
+
&& c.expectedCanonicalDigest === c.desiredDigest;
|
|
40
|
+
}
|
|
41
|
+
function validMaterializationContext(value, operation) {
|
|
42
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
43
|
+
return false;
|
|
44
|
+
const c = value;
|
|
45
|
+
const t = c.requestedTarget;
|
|
46
|
+
return c.kind === "materialization"
|
|
47
|
+
&& typeof c.jobId === "string" && /^materialization-[a-z0-9-]{1,80}$/.test(c.jobId)
|
|
48
|
+
&& operation === `native.materialize.${createHash("sha256").update(c.jobId).digest("hex")}`
|
|
49
|
+
&& typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
|
|
50
|
+
&& Boolean(t && [t.libraryUid, t.eventUid, t.projectUid, t.sequenceUid].every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024))
|
|
51
|
+
&& typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
|
|
52
|
+
&& typeof c.desiredDigest === "string" && /^[a-f0-9]{64}$/.test(c.desiredDigest)
|
|
53
|
+
&& (c.destination === undefined || (c.destination.mode === "versioned" &&
|
|
54
|
+
[c.destination.projectUid, c.destination.sequenceUid, c.destination.projectName, c.destination.sequenceName]
|
|
55
|
+
.every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024)))
|
|
56
|
+
&& c.executorIdentity === null && c.nativeQuiescence === "unproven";
|
|
57
|
+
}
|
|
58
|
+
const unknown = () => ({ status: "unknown", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } });
|
|
59
|
+
const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
|
60
|
+
/** Read a bounded regular file, refusing symlinks, replacement and in-place changes. */
|
|
61
|
+
async function readStable(path) {
|
|
62
|
+
let handle;
|
|
63
|
+
try {
|
|
64
|
+
handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
65
|
+
const before = await handle.stat();
|
|
66
|
+
if (!before.isFile() || before.size > 16_384)
|
|
67
|
+
throw new Error("invalid evidence file");
|
|
68
|
+
const data = await handle.readFile();
|
|
69
|
+
const after = await handle.stat();
|
|
70
|
+
const current = await lstat(path);
|
|
71
|
+
if (!current.isFile() || before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
|
|
72
|
+
|| before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || data.length !== after.size)
|
|
73
|
+
throw new Error("evidence changed");
|
|
74
|
+
return data.toString("utf8");
|
|
75
|
+
}
|
|
76
|
+
catch (error) {
|
|
77
|
+
if (error.code === "ENOENT")
|
|
78
|
+
return undefined;
|
|
79
|
+
throw error;
|
|
80
|
+
}
|
|
81
|
+
finally {
|
|
82
|
+
await handle?.close();
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
async function exists(path) {
|
|
86
|
+
try {
|
|
87
|
+
await lstat(path);
|
|
88
|
+
return true;
|
|
89
|
+
}
|
|
90
|
+
catch (error) {
|
|
91
|
+
if (error.code === "ENOENT")
|
|
92
|
+
return false;
|
|
93
|
+
throw error;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
async function readSettlement(path, id) {
|
|
97
|
+
const directory = `${path}.sender-settled`;
|
|
98
|
+
try {
|
|
99
|
+
const info = await lstat(directory);
|
|
100
|
+
if (!info.isDirectory() || info.isSymbolicLink())
|
|
101
|
+
throw new Error("invalid sender directory");
|
|
102
|
+
return await readStable(join(directory, id));
|
|
103
|
+
}
|
|
104
|
+
catch (error) {
|
|
105
|
+
if (error.code === "ENOENT")
|
|
106
|
+
return undefined;
|
|
107
|
+
throw error;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
function markerMatches(raw, reservationId) {
|
|
111
|
+
try {
|
|
112
|
+
const value = JSON.parse(raw);
|
|
113
|
+
return value !== null && value.reservationId === reservationId && typeof value.owner === "string" && uuid.test(value.owner);
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Read-only, point-in-time observation; old writers do not share a lock, so even
|
|
121
|
+
* repeated reads cannot exclude concurrent changes or establish quiescence.
|
|
122
|
+
*/
|
|
123
|
+
export async function inspectNativeRecoveryReadOnly(path) {
|
|
124
|
+
try {
|
|
125
|
+
if (await exists(`${path}.lock`))
|
|
126
|
+
return unknown();
|
|
127
|
+
const contents = await readStable(path);
|
|
128
|
+
const active = await readStable(`${path}.active`);
|
|
129
|
+
if (contents === undefined) {
|
|
130
|
+
if (active !== undefined || await exists(`${path}.lock`) || await readStable(path) !== undefined || await readStable(`${path}.active`) !== undefined)
|
|
131
|
+
return unknown();
|
|
132
|
+
return { status: "clear", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } };
|
|
133
|
+
}
|
|
134
|
+
const record = JSON.parse(contents);
|
|
135
|
+
if (!record || typeof record !== "object" || Array.isArray(record) || ![2, 3, 4].includes(record.version)
|
|
136
|
+
|| record.kind !== "native-operation" || typeof record.owner !== "string" || !uuid.test(record.owner)
|
|
137
|
+
|| typeof record.operation !== "string" || !/^[a-z][a-z0-9.-]{0,127}$/.test(record.operation))
|
|
138
|
+
return unknown();
|
|
139
|
+
if (record.version === 3 && !validRecoveryContext(record.recoveryContext, record.operation))
|
|
140
|
+
return unknown();
|
|
141
|
+
if (record.version === 4 && !validRecoverableContext(record.recoveryContext, record.operation))
|
|
142
|
+
return unknown();
|
|
143
|
+
if (record.senderTracked !== undefined && typeof record.senderTracked !== "boolean")
|
|
144
|
+
return unknown();
|
|
145
|
+
const reservationId = createHash("sha256").update(contents).digest("hex");
|
|
146
|
+
const boundary = await readStable(`${path}.dispatch-${reservationId}`);
|
|
147
|
+
let boundaryEvidence = "unknown";
|
|
148
|
+
if (boundary !== undefined) {
|
|
149
|
+
try {
|
|
150
|
+
const marker = JSON.parse(boundary);
|
|
151
|
+
if (marker.version === 1 && marker.reservationId === reservationId && marker.owner === record.owner)
|
|
152
|
+
boundaryEvidence = "dispatch-possible-recorded";
|
|
153
|
+
}
|
|
154
|
+
catch { /* A damaged marker provides no proof. */ }
|
|
155
|
+
}
|
|
156
|
+
const settled = await readSettlement(path, reservationId);
|
|
157
|
+
const sender = record.senderTracked !== true ? (active !== undefined || settled !== undefined ? "unknown" : "untracked")
|
|
158
|
+
: active !== undefined ? (settled === undefined && markerMatches(active, reservationId) ? "active-or-interrupted" : "unknown")
|
|
159
|
+
: settled !== undefined && markerMatches(settled, reservationId) ? "sender-settled" : "unknown";
|
|
160
|
+
if (await exists(`${path}.lock`) || await readStable(path) !== contents || await readStable(`${path}.active`) !== active
|
|
161
|
+
|| await readSettlement(path, reservationId) !== settled || await readStable(`${path}.dispatch-${reservationId}`) !== boundary)
|
|
162
|
+
return unknown();
|
|
163
|
+
const context = record.version === 3 || record.version === 4 ? record.recoveryContext : undefined;
|
|
164
|
+
return { status: "recovery-required", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: sender },
|
|
165
|
+
dispatchState: "possibly-dispatched", boundaryEvidence, missingEvidence: ["receiver-terminal-quiescence", "independent-target-outcome", "legacy-writer-exclusion"],
|
|
166
|
+
safeNextActions: ["inspect", "retain-reservation"],
|
|
167
|
+
...(context ? { intent: { requestedTarget: context.requestedTarget, artifactDigest: context.artifactDigest,
|
|
168
|
+
...(context.kind === "materialization" ? { desiredDigest: context.desiredDigest, ...(context.destination ? { destination: context.destination } : {}) } : {}) } } : {}),
|
|
169
|
+
reservation: { version: record.version, reservationId, operation: record.operation,
|
|
170
|
+
...(context ? { jobId: context.jobId, dispatchId: context.dispatchId, jobCorrelation: "unverified" } : {}) } };
|
|
171
|
+
}
|
|
172
|
+
catch {
|
|
173
|
+
return unknown();
|
|
174
|
+
}
|
|
175
|
+
}
|