@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.
Files changed (30) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
  3. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  4. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  5. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  6. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  7. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  9. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  10. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +75 -3
  11. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +443 -0
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  14. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  15. package/dist-package/apps/mcp-server/src/headless-projects.js +139 -0
  16. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  17. package/dist-package/apps/mcp-server/src/main.js +22 -1
  18. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  19. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  20. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  21. package/dist-package/apps/mcp-server/src/server.js +214 -31
  22. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  23. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  24. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  25. package/dist-package/packages/runtime/src/index.js +6 -0
  26. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  27. package/dist-package/packages/runtime/src/render/render-contract.js +143 -0
  28. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  29. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  30. 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: createFinalCutNativeTargetResolver(nativeEditor),
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: 1,
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 || job.jobId !== jobId)
89
+ if (job.jobId !== jobId || (job.schemaVersion !== 1 && job.schemaVersion !== 2)) {
77
90
  throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
78
- return structuredClone(job);
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
+ }