@morshoto/framekit 0.1.13 → 0.1.16
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/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +75 -3
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +443 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +139 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +22 -1
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +214 -31
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/index.js +6 -0
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +143 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { readdir, readFile, rename, writeFile, mkdir } from "node:fs/promises";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, } from "../../../packages/runtime/src/index.js";
|
|
5
|
+
export class HeadlessProjectService {
|
|
6
|
+
directory;
|
|
7
|
+
mediaProbe;
|
|
8
|
+
renderer;
|
|
9
|
+
verifier;
|
|
10
|
+
clock;
|
|
11
|
+
constructor(options) {
|
|
12
|
+
this.directory = options.directory;
|
|
13
|
+
this.mediaProbe = options.mediaProbe;
|
|
14
|
+
this.renderer = options.renderer;
|
|
15
|
+
this.verifier = options.verifier;
|
|
16
|
+
this.clock = options.clock ?? (() => new Date().toISOString());
|
|
17
|
+
}
|
|
18
|
+
async create(timeline) {
|
|
19
|
+
const store = this.store(timeline.project.id);
|
|
20
|
+
const timestamp = this.clock();
|
|
21
|
+
return store.create({
|
|
22
|
+
schemaVersion: 1,
|
|
23
|
+
metadata: { createdAt: timestamp, updatedAt: timestamp },
|
|
24
|
+
timeline,
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
async list() {
|
|
28
|
+
await mkdir(this.directory, { recursive: true });
|
|
29
|
+
const entries = await readdir(this.directory, { withFileTypes: true });
|
|
30
|
+
const summaries = [];
|
|
31
|
+
for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith(".json") && !candidate.name.startsWith("render-"))) {
|
|
32
|
+
const projectId = entry.name.slice(0, -".json".length);
|
|
33
|
+
const project = await this.store(projectId).load();
|
|
34
|
+
summaries.push(toSummary(project, this.projectPath(projectId)));
|
|
35
|
+
}
|
|
36
|
+
return summaries.sort((left, right) => left.projectId.localeCompare(right.projectId));
|
|
37
|
+
}
|
|
38
|
+
async open(projectId) {
|
|
39
|
+
const project = await this.store(projectId).load();
|
|
40
|
+
const hasLocalMedia = project.timeline.resources.some((resource) => resource.sourceKind === "local-file");
|
|
41
|
+
if (hasLocalMedia && !this.mediaProbe) {
|
|
42
|
+
throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: local-file resources require a configured media probe");
|
|
43
|
+
}
|
|
44
|
+
if (this.mediaProbe)
|
|
45
|
+
await new LocalMediaRegistrar(this.store(projectId), this.mediaProbe).reopen();
|
|
46
|
+
return project;
|
|
47
|
+
}
|
|
48
|
+
async inspect(projectId) {
|
|
49
|
+
return this.open(projectId);
|
|
50
|
+
}
|
|
51
|
+
async registerMedia(projectId, sourcePath, expectedRevision) {
|
|
52
|
+
if (!this.mediaProbe)
|
|
53
|
+
throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: no local media metadata probe is configured");
|
|
54
|
+
return new LocalMediaRegistrar(this.store(projectId), this.mediaProbe, { clock: this.clock }).register(sourcePath, expectedRevision);
|
|
55
|
+
}
|
|
56
|
+
async previewEdit(projectId, command, sequenceId) {
|
|
57
|
+
await this.open(projectId);
|
|
58
|
+
const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
|
|
59
|
+
return transaction.preview({
|
|
60
|
+
...command,
|
|
61
|
+
target: command.target ?? { projectId, sequenceId },
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
async executeEdit(projectId, command, sequenceId) {
|
|
65
|
+
await this.open(projectId);
|
|
66
|
+
const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
|
|
67
|
+
return transaction.execute({
|
|
68
|
+
...command,
|
|
69
|
+
target: command.target ?? { projectId, sequenceId },
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
async render(projectId, sequenceId, parameters, expectedRevision) {
|
|
73
|
+
if (!this.renderer || !this.verifier)
|
|
74
|
+
throw new Error("HEADLESS_RENDER_UNAVAILABLE: renderer and verifier are not configured");
|
|
75
|
+
const project = await this.open(projectId);
|
|
76
|
+
const request = createFramekitRenderRequest({
|
|
77
|
+
timeline: project.timeline,
|
|
78
|
+
target: { projectId, sequenceId },
|
|
79
|
+
...(expectedRevision ? { revision: expectedRevision } : {}),
|
|
80
|
+
parameters,
|
|
81
|
+
});
|
|
82
|
+
const outcome = await renderAndVerifyFramekitProject(request, this.renderer, this.verifier);
|
|
83
|
+
const renderId = `render-${randomUUID()}`;
|
|
84
|
+
const record = {
|
|
85
|
+
renderId,
|
|
86
|
+
projectId,
|
|
87
|
+
sequenceId,
|
|
88
|
+
requestedRevision: request.projectRevision,
|
|
89
|
+
createdAt: this.clock(),
|
|
90
|
+
status: outcome.status,
|
|
91
|
+
outcome,
|
|
92
|
+
};
|
|
93
|
+
await this.saveRender(record);
|
|
94
|
+
return record;
|
|
95
|
+
}
|
|
96
|
+
async inspectRender(renderId) {
|
|
97
|
+
validateRenderId(renderId);
|
|
98
|
+
try {
|
|
99
|
+
return JSON.parse(await readFile(join(this.directory, `${renderId}.json`), "utf8"));
|
|
100
|
+
}
|
|
101
|
+
catch (error) {
|
|
102
|
+
if (error.code === "ENOENT")
|
|
103
|
+
throw new Error(`HEADLESS_RENDER_NOT_FOUND: render record does not exist: ${renderId}`);
|
|
104
|
+
throw error;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
store(projectId) {
|
|
108
|
+
return new FramekitProjectStore(this.projectPath(projectId));
|
|
109
|
+
}
|
|
110
|
+
projectPath(projectId) {
|
|
111
|
+
validateProjectId(projectId);
|
|
112
|
+
return join(this.directory, `${projectId}.json`);
|
|
113
|
+
}
|
|
114
|
+
async saveRender(record) {
|
|
115
|
+
await mkdir(this.directory, { recursive: true });
|
|
116
|
+
const path = join(this.directory, `${record.renderId}.json`);
|
|
117
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
118
|
+
await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "wx" });
|
|
119
|
+
await rename(temporary, path);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
function toSummary(project, path) {
|
|
123
|
+
return {
|
|
124
|
+
projectId: project.timeline.project.id,
|
|
125
|
+
projectName: project.timeline.project.name,
|
|
126
|
+
sequenceId: project.timeline.sequence.id,
|
|
127
|
+
sequenceName: project.timeline.sequence.name,
|
|
128
|
+
revision: project.timeline.revision,
|
|
129
|
+
path,
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
function validateProjectId(projectId) {
|
|
133
|
+
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(projectId))
|
|
134
|
+
throw new Error("HEADLESS_PROJECT_INVALID: projectId must be a safe logical identifier");
|
|
135
|
+
}
|
|
136
|
+
function validateRenderId(renderId) {
|
|
137
|
+
if (!/^render-[0-9a-f-]{36}$/.test(renderId))
|
|
138
|
+
throw new Error("HEADLESS_RENDER_INVALID: renderId is invalid");
|
|
139
|
+
}
|
|
@@ -99,6 +99,9 @@ export class EditingSessionRepository {
|
|
|
99
99
|
await this.refreshLoaded(sessionId, session);
|
|
100
100
|
return session;
|
|
101
101
|
}
|
|
102
|
+
hasChangeSource() {
|
|
103
|
+
return this.changeSource !== undefined;
|
|
104
|
+
}
|
|
102
105
|
checkpoint(sessionId, session) {
|
|
103
106
|
return this.save(sessionId, session);
|
|
104
107
|
}
|
|
@@ -7,6 +7,8 @@ import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, F
|
|
|
7
7
|
import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
|
|
8
8
|
import { createMcpServer } from "./server.js";
|
|
9
9
|
import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
|
|
10
|
+
import { HeadlessProjectService } from "./headless-projects.js";
|
|
11
|
+
import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
|
|
10
12
|
const fixture = new InMemoryEditorAdapter({
|
|
11
13
|
projectId: "project-1",
|
|
12
14
|
projectName: "Phase 2 Fixture",
|
|
@@ -90,6 +92,9 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
|
|
|
90
92
|
nativeOperationLease,
|
|
91
93
|
})
|
|
92
94
|
: nativeEditor;
|
|
95
|
+
const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
|
|
96
|
+
? createFinalCutNativeTargetResolver(nativeEditor)
|
|
97
|
+
: undefined;
|
|
93
98
|
const canonicalNativeProvider = canonicalNativeProviderEnabled
|
|
94
99
|
? new FinalCutCanonicalNativeProvider({
|
|
95
100
|
live: liveAdapter,
|
|
@@ -131,7 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
|
|
|
131
136
|
target: { projectId, projectUid: projectId, sequenceId },
|
|
132
137
|
}).readSnapshot();
|
|
133
138
|
},
|
|
134
|
-
resolveTarget:
|
|
139
|
+
resolveTarget: canonicalNativeTargetResolver,
|
|
135
140
|
backgroundCatalog: backgroundLibraryProvider,
|
|
136
141
|
})
|
|
137
142
|
: undefined;
|
|
@@ -177,12 +182,24 @@ const analyzers = liveMode
|
|
|
177
182
|
};
|
|
178
183
|
const runtime = new AgentVideoRuntime(editor, analyzers);
|
|
179
184
|
const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
|
|
185
|
+
const headlessProjects = new HeadlessProjectService({
|
|
186
|
+
directory: join(framekitStateDirectory, "projects"),
|
|
187
|
+
mediaProbe: new FfmpegMediaMetadataProbe(),
|
|
188
|
+
renderer: new FfmpegTimelineRenderer(),
|
|
189
|
+
verifier: new FfmpegRenderVerifier(),
|
|
190
|
+
});
|
|
180
191
|
const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
|
|
181
192
|
const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
|
|
182
193
|
? new DisposableNativeEditWorkflow({
|
|
183
194
|
native: nativeEditor,
|
|
184
195
|
readCanonicalSnapshot: () => runtime.inspectProject(),
|
|
185
196
|
readCanonicalCapabilities: async () => (await runtime.inspectEditor()).capabilities,
|
|
197
|
+
...(nativeEditor ? {
|
|
198
|
+
prepareTarget: async (target, snapshot) => {
|
|
199
|
+
const occurrenceIndex = snapshot.timeline.clips.findIndex((clip) => clip.id === target.id) + 1;
|
|
200
|
+
await nativeEditor.selectCanonicalOccurrence(target.name, occurrenceIndex);
|
|
201
|
+
},
|
|
202
|
+
} : {}),
|
|
186
203
|
})
|
|
187
204
|
: undefined;
|
|
188
205
|
const nativeOperationSession = disposableNative && nativeEditor
|
|
@@ -192,6 +209,9 @@ const projectPublisher = liveMode && fcpxmlPath
|
|
|
192
209
|
? new FinalCutProjectPublisher({
|
|
193
210
|
enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
|
|
194
211
|
sourcePath: fcpxmlPath,
|
|
212
|
+
documentDelivery: liveAdapter,
|
|
213
|
+
targetLibraryUid: process.env.FRAMEKIT_FINAL_CUT_LIBRARY_UID,
|
|
214
|
+
allowHeadedFallback: process.env.FRAMEKIT_FINAL_CUT_ALLOW_HEADED_IMPORT === "1",
|
|
195
215
|
liveState: () => liveAdapter.readLiveState(),
|
|
196
216
|
})
|
|
197
217
|
: undefined;
|
|
@@ -225,6 +245,7 @@ const server = createMcpServer(runtime, {
|
|
|
225
245
|
sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
|
|
226
246
|
materializationDirectory: join(framekitStateDirectory, "materializations"),
|
|
227
247
|
sqliteObservationProvider,
|
|
248
|
+
headlessProjects,
|
|
228
249
|
});
|
|
229
250
|
const transport = new StdioServerTransport();
|
|
230
251
|
let shuttingDown = false;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createHash, randomUUID } from "node:crypto";
|
|
2
2
|
import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
|
|
3
3
|
import { dirname, join } from "node:path";
|
|
4
|
-
import { timelineIrDigest } from "../../../packages/runtime/src/index.js";
|
|
4
|
+
import { timelineIrDigest, validateTimelineIr } from "../../../packages/runtime/src/index.js";
|
|
5
5
|
import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
6
|
export class SessionMaterializationJobs {
|
|
7
7
|
directory;
|
|
@@ -25,6 +25,8 @@ export class SessionMaterializationJobs {
|
|
|
25
25
|
destination: artifact.destination,
|
|
26
26
|
collisionPolicy: "create-only",
|
|
27
27
|
artifactDigest: artifact.digest,
|
|
28
|
+
coverage: artifact.coverage,
|
|
29
|
+
provenance: artifact.provenance,
|
|
28
30
|
evidence: { artifact: { verified: true, format: "fcpxml", digest: artifact.digest } },
|
|
29
31
|
};
|
|
30
32
|
}
|
|
@@ -43,7 +45,7 @@ export class SessionMaterializationJobs {
|
|
|
43
45
|
session.markWaitingForMaterialization();
|
|
44
46
|
await this.sessions.checkpoint(sessionId, session);
|
|
45
47
|
let job = {
|
|
46
|
-
schemaVersion:
|
|
48
|
+
schemaVersion: 2,
|
|
47
49
|
jobId,
|
|
48
50
|
sessionId,
|
|
49
51
|
state: "blocked",
|
|
@@ -54,6 +56,10 @@ export class SessionMaterializationJobs {
|
|
|
54
56
|
destination: artifact.destination,
|
|
55
57
|
desired: structuredClone(desired),
|
|
56
58
|
desiredDigest: timelineIrDigest(desired),
|
|
59
|
+
baseDigest: timelineIrDigest(session.base()),
|
|
60
|
+
baseRevision: structuredClone(session.base().revision),
|
|
61
|
+
coverage: artifact.coverage,
|
|
62
|
+
provenance: artifact.provenance,
|
|
57
63
|
sessionDigest: digestSession(session),
|
|
58
64
|
evidence: {
|
|
59
65
|
artifact: { verified: true, format: "fcpxml", digest: artifact.digest },
|
|
@@ -61,6 +67,13 @@ export class SessionMaterializationJobs {
|
|
|
61
67
|
canonicalReadback: false,
|
|
62
68
|
headedNative: false,
|
|
63
69
|
},
|
|
70
|
+
verification: {
|
|
71
|
+
tier: "artifact",
|
|
72
|
+
status: "blocked",
|
|
73
|
+
artifactDigest: artifact.digest,
|
|
74
|
+
desiredDigest: timelineIrDigest(desired),
|
|
75
|
+
reason: "No Final Cut materialization publisher is configured; retry when a provider is available",
|
|
76
|
+
},
|
|
64
77
|
error: {
|
|
65
78
|
code: "MATERIALIZATION_PROVIDER_UNAVAILABLE",
|
|
66
79
|
message: "No Final Cut materialization publisher is configured; retry when a provider is available",
|
|
@@ -73,9 +86,10 @@ export class SessionMaterializationJobs {
|
|
|
73
86
|
async status(jobId) {
|
|
74
87
|
try {
|
|
75
88
|
const job = JSON.parse(await readFile(this.jobPath(jobId), "utf8"));
|
|
76
|
-
if (job.schemaVersion !== 1
|
|
89
|
+
if (job.jobId !== jobId || (job.schemaVersion !== 1 && job.schemaVersion !== 2)) {
|
|
77
90
|
throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
|
|
78
|
-
|
|
91
|
+
}
|
|
92
|
+
return structuredClone(normalizePersistedJob(job));
|
|
79
93
|
}
|
|
80
94
|
catch (error) {
|
|
81
95
|
if (error.code === "ENOENT") {
|
|
@@ -92,6 +106,59 @@ export class SessionMaterializationJobs {
|
|
|
92
106
|
throw new Error(`MATERIALIZATION_NOT_RETRYABLE: job ${jobId} cannot be retried`);
|
|
93
107
|
return this.attempt(job);
|
|
94
108
|
}
|
|
109
|
+
async resync(jobId, sessionId) {
|
|
110
|
+
const job = await this.status(jobId);
|
|
111
|
+
if (job.state !== "completed") {
|
|
112
|
+
throw new Error("MATERIALIZATION_NOT_COMPLETED: canonical continuation requires a completed handoff");
|
|
113
|
+
}
|
|
114
|
+
const verification = job.verification;
|
|
115
|
+
const target = verification?.canonicalTarget;
|
|
116
|
+
if (!target) {
|
|
117
|
+
throw new Error("MATERIALIZATION_TARGET_UNAVAILABLE: completed handoff has no verified target identity");
|
|
118
|
+
}
|
|
119
|
+
if (!this.publisher?.readCanonicalTarget) {
|
|
120
|
+
throw new Error("MATERIALIZATION_CANONICAL_RESYNC_UNAVAILABLE: no target-bound canonical readback capability is configured");
|
|
121
|
+
}
|
|
122
|
+
const result = await this.publisher.readCanonicalTarget({ target: structuredClone(target) });
|
|
123
|
+
validateTimelineIr(result.canonicalReadback);
|
|
124
|
+
if (!sameTarget(result.canonicalTarget, target)
|
|
125
|
+
|| result.canonicalReadback.project.id !== target.projectUid
|
|
126
|
+
|| result.canonicalReadback.sequence.id !== target.sequenceUid) {
|
|
127
|
+
throw new Error("MATERIALIZATION_RESYNC_TARGET_MISMATCH: canonical readback does not identify the completed handoff target");
|
|
128
|
+
}
|
|
129
|
+
const readbackDigest = timelineIrDigest(result.canonicalReadback);
|
|
130
|
+
const changeSinceHandoff = verification.canonicalReadbackDigest
|
|
131
|
+
? readbackDigest === verification.canonicalReadbackDigest ? "unchanged" : "changed"
|
|
132
|
+
: "unknown";
|
|
133
|
+
const created = await this.sessions.create({
|
|
134
|
+
sessionId,
|
|
135
|
+
base: result.canonicalReadback,
|
|
136
|
+
provider: { id: job.target.provider },
|
|
137
|
+
});
|
|
138
|
+
const continuation = {
|
|
139
|
+
state: "resynced",
|
|
140
|
+
reason: changeSinceHandoff === "changed"
|
|
141
|
+
? "Canonical state changed after handoff; a fresh session was created from the current target readback."
|
|
142
|
+
: changeSinceHandoff === "unchanged"
|
|
143
|
+
? "Canonical state matches the handoff readback; a fresh session was created from the current target readback."
|
|
144
|
+
: "A fresh session was created from target-bound canonical readback; comparison with the handoff snapshot was unavailable.",
|
|
145
|
+
sessionId,
|
|
146
|
+
readbackDigest,
|
|
147
|
+
changeSinceHandoff,
|
|
148
|
+
...(result.delivery ? { delivery: result.delivery } : {}),
|
|
149
|
+
};
|
|
150
|
+
await this.save({ ...job, continuation });
|
|
151
|
+
return {
|
|
152
|
+
jobId,
|
|
153
|
+
state: continuation.state,
|
|
154
|
+
sessionId,
|
|
155
|
+
changeSinceHandoff,
|
|
156
|
+
canonicalTarget: structuredClone(result.canonicalTarget),
|
|
157
|
+
readbackDigest,
|
|
158
|
+
document: created.document,
|
|
159
|
+
...(result.delivery ? { delivery: result.delivery } : {}),
|
|
160
|
+
};
|
|
161
|
+
}
|
|
95
162
|
async attempt(job) {
|
|
96
163
|
if (!this.publisher || job.state === "publishing")
|
|
97
164
|
return job;
|
|
@@ -115,6 +182,10 @@ export class SessionMaterializationJobs {
|
|
|
115
182
|
collisionPolicy: "create-only",
|
|
116
183
|
desired: structuredClone(claimed.desired),
|
|
117
184
|
desiredDigest: claimed.desiredDigest,
|
|
185
|
+
baseDigest: claimed.baseDigest,
|
|
186
|
+
baseRevision: structuredClone(claimed.baseRevision),
|
|
187
|
+
coverage: structuredClone(claimed.coverage),
|
|
188
|
+
provenance: structuredClone(claimed.provenance),
|
|
118
189
|
});
|
|
119
190
|
if (result.state === "blocked") {
|
|
120
191
|
const blocked = {
|
|
@@ -123,6 +194,14 @@ export class SessionMaterializationJobs {
|
|
|
123
194
|
nextAction: "retry",
|
|
124
195
|
claim: undefined,
|
|
125
196
|
evidence: { ...claimed.evidence, providerRequested: true },
|
|
197
|
+
verification: {
|
|
198
|
+
tier: verificationTierForBlockedCode(result.code),
|
|
199
|
+
status: "blocked",
|
|
200
|
+
artifactDigest: claimed.verification?.artifactDigest ?? claimed.artifactDigest,
|
|
201
|
+
desiredDigest: claimed.verification?.desiredDigest ?? claimed.desiredDigest,
|
|
202
|
+
reason: result.message,
|
|
203
|
+
...(result.delivery ? { delivery: result.delivery } : { delivery: deliveryEvidenceForBlockedCode(result.code) }),
|
|
204
|
+
},
|
|
126
205
|
error: { code: result.code, message: result.message, retryable: result.retryable },
|
|
127
206
|
};
|
|
128
207
|
await this.save(blocked);
|
|
@@ -134,6 +213,8 @@ export class SessionMaterializationJobs {
|
|
|
134
213
|
message: "Canonical provider readback does not match the desired Timeline IR",
|
|
135
214
|
retryable: false,
|
|
136
215
|
providerRequested: true,
|
|
216
|
+
verificationTier: "delivery",
|
|
217
|
+
structuralDiff: createMaterializationStructuralDiff(claimed.desired, result.canonicalReadback),
|
|
137
218
|
});
|
|
138
219
|
}
|
|
139
220
|
const expectedTarget = {
|
|
@@ -162,6 +243,22 @@ export class SessionMaterializationJobs {
|
|
|
162
243
|
headedNative: result.headedNativeVerified,
|
|
163
244
|
},
|
|
164
245
|
error: undefined,
|
|
246
|
+
verification: {
|
|
247
|
+
tier: "canonical-verified",
|
|
248
|
+
status: "verified",
|
|
249
|
+
artifactDigest: claimed.artifactDigest,
|
|
250
|
+
desiredDigest: claimed.desiredDigest,
|
|
251
|
+
canonicalReadbackDigest: timelineIrDigest(result.canonicalReadback),
|
|
252
|
+
canonicalTarget: structuredClone(result.canonicalTarget),
|
|
253
|
+
delivery: result.delivery ?? {
|
|
254
|
+
state: result.headedNativeVerified ? "activated" : "background",
|
|
255
|
+
route: result.headedNativeVerified ? "headed" : "background",
|
|
256
|
+
},
|
|
257
|
+
},
|
|
258
|
+
continuation: {
|
|
259
|
+
state: "canonical-resync-required",
|
|
260
|
+
reason: "Canonical readback verified this handoff once. Re-read the materialized target before later edits to detect subsequent manual Final Cut changes.",
|
|
261
|
+
},
|
|
165
262
|
};
|
|
166
263
|
await this.save(completed);
|
|
167
264
|
return completed;
|
|
@@ -181,6 +278,40 @@ export class SessionMaterializationJobs {
|
|
|
181
278
|
retryable: false,
|
|
182
279
|
};
|
|
183
280
|
}
|
|
281
|
+
if (!job.coverage || !job.provenance) {
|
|
282
|
+
return {
|
|
283
|
+
code: "MATERIALIZATION_JOB_METADATA_UNAVAILABLE",
|
|
284
|
+
message: "This persisted materialization job predates target-bound coverage and provenance; execute a new preview before retrying",
|
|
285
|
+
retryable: false,
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
if (job.provenance.timelineDigest !== job.desiredDigest
|
|
289
|
+
|| job.provenance.projectId !== job.desired.project.id
|
|
290
|
+
|| job.provenance.sequenceId !== job.desired.sequence.id
|
|
291
|
+
|| job.provenance.revision?.id !== job.desired.revision.id
|
|
292
|
+
|| job.provenance.revision?.sequence !== job.desired.revision.sequence
|
|
293
|
+
|| job.provenance.revision?.timestamp !== job.desired.revision.timestamp
|
|
294
|
+
|| job.provenance.target?.libraryUid !== job.target.libraryUid
|
|
295
|
+
|| job.provenance.target?.eventUid !== job.target.eventUid
|
|
296
|
+
|| job.provenance.target?.projectUid !== job.target.projectUid
|
|
297
|
+
|| job.provenance.target?.sequenceUid !== job.target.sequenceUid
|
|
298
|
+
|| job.provenance.destination?.projectUid !== job.destination.projectUid
|
|
299
|
+
|| job.provenance.destination?.sequenceUid !== job.destination.sequenceUid) {
|
|
300
|
+
return {
|
|
301
|
+
code: "MATERIALIZATION_PROVENANCE_INVALID",
|
|
302
|
+
message: "The persisted materialization provenance does not bind to the desired revision and target",
|
|
303
|
+
retryable: false,
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
if (!Array.isArray(job.coverage.exact) || !Array.isArray(job.coverage.degraded) || !Array.isArray(job.coverage.unsupported)
|
|
307
|
+
|| ![...job.coverage.exact, ...job.coverage.degraded, ...job.coverage.unsupported].every((value) => typeof value === "string" && value.trim())
|
|
308
|
+
|| job.coverage.unsupported.length > 0) {
|
|
309
|
+
return {
|
|
310
|
+
code: "MATERIALIZATION_COVERAGE_INVALID",
|
|
311
|
+
message: "The persisted materialization coverage is unsupported or malformed",
|
|
312
|
+
retryable: false,
|
|
313
|
+
};
|
|
314
|
+
}
|
|
184
315
|
if (!job.sessionDigest) {
|
|
185
316
|
return {
|
|
186
317
|
code: "MATERIALIZATION_SESSION_SNAPSHOT_INVALID",
|
|
@@ -188,8 +319,31 @@ export class SessionMaterializationJobs {
|
|
|
188
319
|
retryable: false,
|
|
189
320
|
};
|
|
190
321
|
}
|
|
322
|
+
if (!job.baseDigest || !job.baseRevision) {
|
|
323
|
+
return {
|
|
324
|
+
code: "MATERIALIZATION_BASE_PROVENANCE_INVALID",
|
|
325
|
+
message: "The materialization job has no immutable canonical base digest and revision",
|
|
326
|
+
retryable: false,
|
|
327
|
+
};
|
|
328
|
+
}
|
|
329
|
+
if (!this.sessions.hasChangeSource()) {
|
|
330
|
+
return {
|
|
331
|
+
code: "MATERIALIZATION_BASE_UNAVAILABLE",
|
|
332
|
+
message: "A canonical session change source is required to verify the staged base before publication",
|
|
333
|
+
retryable: false,
|
|
334
|
+
};
|
|
335
|
+
}
|
|
191
336
|
try {
|
|
192
337
|
const session = await this.sessions.loadForMaterialization(job.sessionId);
|
|
338
|
+
if (session.state() === "possibly_stale" || session.state() === "conflicted"
|
|
339
|
+
|| timelineIrDigest(session.base()) !== job.baseDigest
|
|
340
|
+
|| !sameRevision(session.base().revision, job.baseRevision)) {
|
|
341
|
+
return {
|
|
342
|
+
code: "MATERIALIZATION_BASE_CHANGED",
|
|
343
|
+
message: "The bound canonical base project, sequence, or revision changed after materialization staging",
|
|
344
|
+
retryable: false,
|
|
345
|
+
};
|
|
346
|
+
}
|
|
193
347
|
if (digestSession(session) !== job.sessionDigest) {
|
|
194
348
|
return {
|
|
195
349
|
code: "MATERIALIZATION_SESSION_CHANGED",
|
|
@@ -279,6 +433,15 @@ export class SessionMaterializationJobs {
|
|
|
279
433
|
message: failure.message,
|
|
280
434
|
retryable: failure.retryable,
|
|
281
435
|
},
|
|
436
|
+
verification: {
|
|
437
|
+
tier: failure.verificationTier ?? "artifact",
|
|
438
|
+
status: "failed",
|
|
439
|
+
artifactDigest: job.artifactDigest,
|
|
440
|
+
desiredDigest: job.desiredDigest,
|
|
441
|
+
reason: failure.message,
|
|
442
|
+
...(failure.structuralDiff ? { structuralDiff: failure.structuralDiff } : {}),
|
|
443
|
+
...(failure.delivery ? { delivery: failure.delivery } : {}),
|
|
444
|
+
},
|
|
282
445
|
};
|
|
283
446
|
await this.save(failed);
|
|
284
447
|
return failed;
|
|
@@ -313,11 +476,77 @@ function compileTimelineIrToFcxmlVersioned(desired, target) {
|
|
|
313
476
|
}
|
|
314
477
|
return compileTimelineIrToFcpxml(desired, { target: { ...target, materialization: "versioned" } });
|
|
315
478
|
}
|
|
479
|
+
function normalizePersistedJob(job) {
|
|
480
|
+
if (job.schemaVersion === 2)
|
|
481
|
+
return job;
|
|
482
|
+
if (job.coverage && job.provenance)
|
|
483
|
+
return { ...job, schemaVersion: 2 };
|
|
484
|
+
return {
|
|
485
|
+
...job,
|
|
486
|
+
schemaVersion: 2,
|
|
487
|
+
state: "failed",
|
|
488
|
+
nextAction: "none",
|
|
489
|
+
claim: undefined,
|
|
490
|
+
error: {
|
|
491
|
+
code: "MATERIALIZATION_JOB_METADATA_UNAVAILABLE",
|
|
492
|
+
message: "This persisted materialization job predates target-bound coverage and provenance; execute a new preview before retrying",
|
|
493
|
+
retryable: false,
|
|
494
|
+
},
|
|
495
|
+
};
|
|
496
|
+
}
|
|
316
497
|
function materializationFailure(error, providerRequested) {
|
|
317
498
|
const message = error instanceof Error ? error.message : String(error);
|
|
318
499
|
const code = message.match(/^([A-Z][A-Z0-9_]*):/)?.[1] ?? "MATERIALIZATION_PUBLISH_FAILED";
|
|
319
500
|
return { code, message, retryable: false, providerRequested };
|
|
320
501
|
}
|
|
502
|
+
function verificationTierForBlockedCode(code) {
|
|
503
|
+
return /INTERACTION_REQUIRED|CONSOLE_LOCKED|PROMPT/i.test(code) ? "interaction-required" : "artifact";
|
|
504
|
+
}
|
|
505
|
+
function deliveryEvidenceForBlockedCode(code) {
|
|
506
|
+
if (/INTERACTION_REQUIRED/i.test(code))
|
|
507
|
+
return { state: "interaction-required", route: "headed" };
|
|
508
|
+
if (/PROMPT/i.test(code))
|
|
509
|
+
return { state: "prompted", route: "headed" };
|
|
510
|
+
return { state: "failed", route: "unknown" };
|
|
511
|
+
}
|
|
512
|
+
function createMaterializationStructuralDiff(desired, actual) {
|
|
513
|
+
const changes = [];
|
|
514
|
+
collectStructuralChanges(desired, actual, "", changes);
|
|
515
|
+
return {
|
|
516
|
+
target: { projectId: desired.project.id, sequenceId: desired.sequence.id },
|
|
517
|
+
desiredDigest: timelineIrDigest(desired),
|
|
518
|
+
actualDigest: timelineIrDigest(actual),
|
|
519
|
+
changes,
|
|
520
|
+
};
|
|
521
|
+
}
|
|
522
|
+
function collectStructuralChanges(before, after, path, changes) {
|
|
523
|
+
if (JSON.stringify(before) === JSON.stringify(after))
|
|
524
|
+
return;
|
|
525
|
+
if (Array.isArray(before) && Array.isArray(after)) {
|
|
526
|
+
const length = Math.max(before.length, after.length);
|
|
527
|
+
for (let index = 0; index < length; index += 1) {
|
|
528
|
+
collectStructuralChanges(before[index], after[index], `${path}[${index}]`, changes);
|
|
529
|
+
}
|
|
530
|
+
return;
|
|
531
|
+
}
|
|
532
|
+
if (isRecord(before) && isRecord(after)) {
|
|
533
|
+
const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
|
|
534
|
+
for (const key of keys) {
|
|
535
|
+
collectStructuralChanges(before[key], after[key], path ? `${path}.${key}` : key, changes);
|
|
536
|
+
}
|
|
537
|
+
return;
|
|
538
|
+
}
|
|
539
|
+
changes.push({ path, ...(before !== undefined ? { before } : {}), ...(after !== undefined ? { after } : {}) });
|
|
540
|
+
}
|
|
541
|
+
function isRecord(value) {
|
|
542
|
+
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
543
|
+
}
|
|
544
|
+
function sameRevision(left, right) {
|
|
545
|
+
return right !== undefined
|
|
546
|
+
&& left.id === right.id
|
|
547
|
+
&& left.sequence === right.sequence
|
|
548
|
+
&& left.timestamp === right.timestamp;
|
|
549
|
+
}
|
|
321
550
|
function sameTarget(actual, expected) {
|
|
322
551
|
return actual?.libraryUid === expected.libraryUid
|
|
323
552
|
&& actual.eventUid === expected.eventUid
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export function chooseTimelineReadback(request) {
|
|
2
|
+
if (!request.hasCanonicalBase)
|
|
3
|
+
return { route: "canonical-resync", reason: "no target-bound canonical base is available" };
|
|
4
|
+
if (request.requestedCanonical || request.finalVerification)
|
|
5
|
+
return { route: "canonical-resync", reason: "the caller requires a canonical checkpoint" };
|
|
6
|
+
if (request.sessionState === "possibly_stale" || request.sessionState === "conflicted") {
|
|
7
|
+
return { route: "canonical-resync", reason: "the editing session requires canonical resync" };
|
|
8
|
+
}
|
|
9
|
+
const fast = request.fastObservation;
|
|
10
|
+
if (fast?.available && (!fast.coverageComplete
|
|
11
|
+
|| fast.status === "possibly-stale"
|
|
12
|
+
|| fast.status === "canonical-resync-required"
|
|
13
|
+
|| fast.status === "target-mismatch"
|
|
14
|
+
|| fast.status === "provider-incompatible")) {
|
|
15
|
+
return { route: "canonical-resync", reason: "fast observation is incomplete or stale" };
|
|
16
|
+
}
|
|
17
|
+
if (fast?.available && fast.status === "conflicted")
|
|
18
|
+
return { route: "canonical-resync", reason: "fast observation reported a conflict" };
|
|
19
|
+
if (fast?.available && fast.coverageComplete
|
|
20
|
+
&& (fast.status === "unchanged"
|
|
21
|
+
|| fast.status === "advanced-by-framekit"
|
|
22
|
+
|| fast.status === "proven-structural-delta")) {
|
|
23
|
+
return { route: "fast-observation", reason: "fast observation is complete and reconciled" };
|
|
24
|
+
}
|
|
25
|
+
return { route: "session", reason: "the bound session remains usable without a fresh observation" };
|
|
26
|
+
}
|