@morshoto/framekit 0.1.10 → 0.1.12

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 (31) hide show
  1. package/README.md +1 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
  3. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
  7. package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
  11. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  12. package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
  13. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
  14. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  15. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  16. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  18. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  19. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  20. package/dist-package/apps/mcp-server/src/main.js +36 -2
  21. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  23. package/dist-package/apps/mcp-server/src/server.js +146 -12
  24. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  25. package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
  26. package/dist-package/packages/runtime/src/index.js +2 -0
  27. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  28. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  29. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  30. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  31. package/package.json +10 -6
@@ -0,0 +1,326 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
3
+ import { dirname, join } from "node:path";
4
+ import { timelineIrDigest } from "../../../packages/runtime/src/index.js";
5
+ import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ export class SessionMaterializationJobs {
7
+ directory;
8
+ sessions;
9
+ publisher;
10
+ constructor(directory, sessions, publisher) {
11
+ this.directory = directory;
12
+ this.sessions = sessions;
13
+ this.publisher = publisher;
14
+ }
15
+ async preview(sessionId, target) {
16
+ const session = await this.sessions.loadForMaterialization(sessionId);
17
+ this.assertProvider(session.document().provider?.id, target.provider);
18
+ session.assertMaterializationReady(session.base().revision);
19
+ const artifact = compileTimelineIrToFcxmlVersioned(session.desired(), target);
20
+ return {
21
+ sessionId,
22
+ mutating: false,
23
+ sessionState: session.state(),
24
+ target: artifact.target,
25
+ destination: artifact.destination,
26
+ collisionPolicy: "create-only",
27
+ artifactDigest: artifact.digest,
28
+ evidence: { artifact: { verified: true, format: "fcpxml", digest: artifact.digest } },
29
+ };
30
+ }
31
+ async execute(sessionId, target, confirm) {
32
+ if (!confirm)
33
+ throw new Error("MATERIALIZATION_CONFIRMATION_REQUIRED: set confirm=true to stage and publish a versioned project");
34
+ const session = await this.sessions.loadForMaterialization(sessionId);
35
+ this.assertProvider(session.document().provider?.id, target.provider);
36
+ session.assertMaterializationReady(session.base().revision);
37
+ const desired = session.desired();
38
+ const artifact = compileTimelineIrToFcxmlVersioned(desired, target);
39
+ const jobId = `materialization-${randomUUID()}`;
40
+ const artifactPath = join(this.directory, "artifacts", `${jobId}.fcpxml`);
41
+ await mkdir(dirname(artifactPath), { recursive: true });
42
+ await writeFile(artifactPath, artifact.xml, { encoding: "utf8", flag: "wx" });
43
+ session.markWaitingForMaterialization();
44
+ await this.sessions.checkpoint(sessionId, session);
45
+ let job = {
46
+ schemaVersion: 1,
47
+ jobId,
48
+ sessionId,
49
+ state: "blocked",
50
+ nextAction: "retry",
51
+ artifactPath,
52
+ artifactDigest: artifact.digest,
53
+ target: artifact.target,
54
+ destination: artifact.destination,
55
+ desired: structuredClone(desired),
56
+ desiredDigest: timelineIrDigest(desired),
57
+ sessionDigest: digestSession(session),
58
+ evidence: {
59
+ artifact: { verified: true, format: "fcpxml", digest: artifact.digest },
60
+ providerRequested: false,
61
+ canonicalReadback: false,
62
+ headedNative: false,
63
+ },
64
+ error: {
65
+ code: "MATERIALIZATION_PROVIDER_UNAVAILABLE",
66
+ message: "No Final Cut materialization publisher is configured; retry when a provider is available",
67
+ retryable: true,
68
+ },
69
+ };
70
+ await this.save(job);
71
+ return this.attempt(job);
72
+ }
73
+ async status(jobId) {
74
+ try {
75
+ const job = JSON.parse(await readFile(this.jobPath(jobId), "utf8"));
76
+ if (job.schemaVersion !== 1 || job.jobId !== jobId)
77
+ throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
78
+ return structuredClone(job);
79
+ }
80
+ catch (error) {
81
+ if (error.code === "ENOENT") {
82
+ throw new Error(`MATERIALIZATION_JOB_NOT_FOUND: unknown materialization job ${jobId}`);
83
+ }
84
+ throw error;
85
+ }
86
+ }
87
+ async retry(jobId) {
88
+ const job = await this.status(jobId);
89
+ if (job.state === "publishing" || job.state === "completed" || job.state === "failed")
90
+ return job;
91
+ if (!job.error?.retryable)
92
+ throw new Error(`MATERIALIZATION_NOT_RETRYABLE: job ${jobId} cannot be retried`);
93
+ return this.attempt(job);
94
+ }
95
+ async attempt(job) {
96
+ if (!this.publisher || job.state === "publishing")
97
+ return job;
98
+ const initialFailure = await this.validateStagedJob(job);
99
+ if (initialFailure)
100
+ return this.fail(job, initialFailure);
101
+ const claim = await this.claim(job);
102
+ if (!claim.owned)
103
+ return claim.job;
104
+ const claimed = claim.job;
105
+ try {
106
+ const finalFailure = await this.validateStagedJob(claimed);
107
+ if (finalFailure)
108
+ return this.fail(claimed, finalFailure);
109
+ const result = await this.publisher.publish({
110
+ jobId: claimed.jobId,
111
+ artifactPath: claimed.artifactPath,
112
+ artifactDigest: claimed.artifactDigest,
113
+ target: claimed.target,
114
+ destination: claimed.destination,
115
+ collisionPolicy: "create-only",
116
+ desired: structuredClone(claimed.desired),
117
+ desiredDigest: claimed.desiredDigest,
118
+ });
119
+ if (result.state === "blocked") {
120
+ const blocked = {
121
+ ...claimed,
122
+ state: "blocked",
123
+ nextAction: "retry",
124
+ claim: undefined,
125
+ evidence: { ...claimed.evidence, providerRequested: true },
126
+ error: { code: result.code, message: result.message, retryable: result.retryable },
127
+ };
128
+ await this.save(blocked);
129
+ return blocked;
130
+ }
131
+ if (timelineIrDigest(result.canonicalReadback) !== claimed.desiredDigest) {
132
+ return this.fail(claimed, {
133
+ code: "MATERIALIZATION_READBACK_MISMATCH",
134
+ message: "Canonical provider readback does not match the desired Timeline IR",
135
+ retryable: false,
136
+ providerRequested: true,
137
+ });
138
+ }
139
+ const expectedTarget = {
140
+ libraryUid: claimed.target.libraryUid,
141
+ eventUid: claimed.target.eventUid,
142
+ projectUid: claimed.destination.projectUid,
143
+ sequenceUid: claimed.destination.sequenceUid,
144
+ };
145
+ if (!sameTarget(result.canonicalTarget, expectedTarget)) {
146
+ return this.fail(claimed, {
147
+ code: "MATERIALIZATION_TARGET_READBACK_MISMATCH",
148
+ message: "Canonical provider readback does not identify the staged versioned target",
149
+ retryable: false,
150
+ providerRequested: true,
151
+ });
152
+ }
153
+ const completed = {
154
+ ...claimed,
155
+ state: "completed",
156
+ nextAction: "none",
157
+ claim: undefined,
158
+ evidence: {
159
+ ...claimed.evidence,
160
+ providerRequested: true,
161
+ canonicalReadback: true,
162
+ headedNative: result.headedNativeVerified,
163
+ },
164
+ error: undefined,
165
+ };
166
+ await this.save(completed);
167
+ return completed;
168
+ }
169
+ catch (error) {
170
+ return this.fail(claimed, materializationFailure(error, true));
171
+ }
172
+ finally {
173
+ await this.release(claimed.jobId, claimed.claim.id);
174
+ }
175
+ }
176
+ async validateStagedJob(job) {
177
+ if (!job.desired || !job.desiredDigest || timelineIrDigest(job.desired) !== job.desiredDigest) {
178
+ return {
179
+ code: "MATERIALIZATION_DESIRED_SNAPSHOT_INVALID",
180
+ message: "The staged desired Timeline IR is unavailable or does not match its immutable digest",
181
+ retryable: false,
182
+ };
183
+ }
184
+ if (!job.sessionDigest) {
185
+ return {
186
+ code: "MATERIALIZATION_SESSION_SNAPSHOT_INVALID",
187
+ message: "The materialization job has no immutable session snapshot digest",
188
+ retryable: false,
189
+ };
190
+ }
191
+ try {
192
+ const session = await this.sessions.loadForMaterialization(job.sessionId);
193
+ if (digestSession(session) !== job.sessionDigest) {
194
+ return {
195
+ code: "MATERIALIZATION_SESSION_CHANGED",
196
+ message: "The editing session changed after materialization staging; reconcile before retrying",
197
+ retryable: false,
198
+ };
199
+ }
200
+ const artifact = await readFile(job.artifactPath, "utf8");
201
+ if (createHash("sha256").update(artifact).digest("hex") !== job.artifactDigest) {
202
+ return {
203
+ code: "MATERIALIZATION_ARTIFACT_CHANGED",
204
+ message: "The staged FCPXML artifact no longer matches its immutable digest",
205
+ retryable: false,
206
+ };
207
+ }
208
+ return undefined;
209
+ }
210
+ catch (error) {
211
+ return materializationFailure(error, false);
212
+ }
213
+ }
214
+ async claim(job) {
215
+ const claimPath = this.claimPath(job.jobId);
216
+ const claim = { id: randomUUID(), claimedAt: new Date().toISOString() };
217
+ try {
218
+ await writeFile(claimPath, `${JSON.stringify({ jobId: job.jobId, ...claim })}\n`, { encoding: "utf8", flag: "wx" });
219
+ }
220
+ catch (error) {
221
+ if (error.code !== "EEXIST")
222
+ throw error;
223
+ const current = await this.status(job.jobId);
224
+ if (current.state !== "blocked")
225
+ return { job: current, owned: false };
226
+ try {
227
+ const existing = JSON.parse(await readFile(claimPath, "utf8"));
228
+ if (existing.id && existing.claimedAt) {
229
+ return {
230
+ job: { ...current, state: "publishing", nextAction: "status", claim: { id: existing.id, claimedAt: existing.claimedAt } },
231
+ owned: false,
232
+ };
233
+ }
234
+ }
235
+ catch {
236
+ // The owner may be between creating the claim and persisting state.
237
+ }
238
+ return { job: { ...current, state: "publishing", nextAction: "status" }, owned: false };
239
+ }
240
+ const claimed = {
241
+ ...job,
242
+ state: "publishing",
243
+ nextAction: "status",
244
+ claim,
245
+ };
246
+ try {
247
+ await this.save(claimed);
248
+ return { job: claimed, owned: true };
249
+ }
250
+ catch (error) {
251
+ await unlink(claimPath).catch(() => undefined);
252
+ throw error;
253
+ }
254
+ }
255
+ async release(jobId, claimId) {
256
+ const path = this.claimPath(jobId);
257
+ try {
258
+ const current = JSON.parse(await readFile(path, "utf8"));
259
+ if (current.id === claimId)
260
+ await unlink(path);
261
+ }
262
+ catch (error) {
263
+ if (error.code !== "ENOENT")
264
+ throw error;
265
+ }
266
+ }
267
+ async fail(job, failure) {
268
+ const failed = {
269
+ ...job,
270
+ state: "failed",
271
+ nextAction: "none",
272
+ claim: undefined,
273
+ evidence: {
274
+ ...job.evidence,
275
+ providerRequested: failure.providerRequested ?? job.evidence.providerRequested,
276
+ },
277
+ error: {
278
+ code: failure.code,
279
+ message: failure.message,
280
+ retryable: failure.retryable,
281
+ },
282
+ };
283
+ await this.save(failed);
284
+ return failed;
285
+ }
286
+ async save(job) {
287
+ const path = this.jobPath(job.jobId);
288
+ await mkdir(dirname(path), { recursive: true });
289
+ const temporary = `${path}.${randomUUID()}.tmp`;
290
+ await writeFile(temporary, `${JSON.stringify(job)}\n`, { encoding: "utf8", flag: "wx" });
291
+ await rename(temporary, path);
292
+ }
293
+ jobPath(jobId) {
294
+ if (!/^materialization-[A-Za-z0-9-]+$/.test(jobId))
295
+ throw new Error("MATERIALIZATION_JOB_ID_INVALID: invalid jobId");
296
+ return join(this.directory, "jobs", `${jobId}.json`);
297
+ }
298
+ claimPath(jobId) {
299
+ return `${this.jobPath(jobId)}.claim`;
300
+ }
301
+ assertProvider(sessionProvider, targetProvider) {
302
+ if (sessionProvider && sessionProvider !== targetProvider) {
303
+ throw new Error(`SESSION_PROVIDER_MISMATCH: expected ${sessionProvider}, received ${targetProvider}`);
304
+ }
305
+ }
306
+ }
307
+ function digestSession(session) {
308
+ return createHash("sha256").update(session.serialize()).digest("hex");
309
+ }
310
+ function compileTimelineIrToFcxmlVersioned(desired, target) {
311
+ if (target.materialization === "reuse-existing") {
312
+ throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_REUSE_FORBIDDEN: materialization jobs are create-only");
313
+ }
314
+ return compileTimelineIrToFcpxml(desired, { target: { ...target, materialization: "versioned" } });
315
+ }
316
+ function materializationFailure(error, providerRequested) {
317
+ const message = error instanceof Error ? error.message : String(error);
318
+ const code = message.match(/^([A-Z][A-Z0-9_]*):/)?.[1] ?? "MATERIALIZATION_PUBLISH_FAILED";
319
+ return { code, message, retryable: false, providerRequested };
320
+ }
321
+ function sameTarget(actual, expected) {
322
+ return actual?.libraryUid === expected.libraryUid
323
+ && actual.eventUid === expected.eventUid
324
+ && actual.projectUid === expected.projectUid
325
+ && actual.sequenceUid === expected.sequenceUid;
326
+ }
@@ -99,6 +99,7 @@ export function resolveEditingRoute(request, context) {
99
99
  const missingRequirements = requirements.filter((requirement) => !requirement.satisfied(context));
100
100
  const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
101
101
  const editor = context.editor?.identity;
102
+ const readiness = routingReadiness(context);
102
103
  const workflow = request.operation === "artifact.edit"
103
104
  ? BACKGROUND_ARTIFACT_WORKFLOW
104
105
  : request.operation === "project.list"
@@ -113,6 +114,7 @@ export function resolveEditingRoute(request, context) {
113
114
  requiredCapabilities,
114
115
  missingCapabilities,
115
116
  ...(editor ? { editor } : {}),
117
+ ...(readiness ? { readiness } : {}),
116
118
  workflow: [...workflow],
117
119
  reason: {
118
120
  code: "EXTERNAL_FALLBACK_SELECTED",
@@ -133,6 +135,7 @@ export function resolveEditingRoute(request, context) {
133
135
  requiredCapabilities,
134
136
  missingCapabilities,
135
137
  ...(editor ? { editor } : {}),
138
+ ...(readiness ? { readiness } : {}),
136
139
  workflow: [...workflow],
137
140
  reason: editorUnavailableReason(context, missingRequirements),
138
141
  };
@@ -145,6 +148,7 @@ export function resolveEditingRoute(request, context) {
145
148
  requiredCapabilities,
146
149
  missingCapabilities,
147
150
  ...(editor ? { editor } : {}),
151
+ ...(readiness ? { readiness } : {}),
148
152
  workflow: [...workflow],
149
153
  reason: capabilityUnavailableReason(context, missingRequirements, request.operation),
150
154
  };
@@ -157,6 +161,7 @@ export function resolveEditingRoute(request, context) {
157
161
  requiredCapabilities,
158
162
  missingCapabilities: [],
159
163
  ...(provider ? { provider } : {}),
164
+ ...(readiness ? { readiness } : {}),
160
165
  editor,
161
166
  workflow: [...workflow],
162
167
  reason: {
@@ -166,6 +171,18 @@ export function resolveEditingRoute(request, context) {
166
171
  },
167
172
  };
168
173
  }
174
+ function routingReadiness(context) {
175
+ const readiness = context.nativeReadiness;
176
+ if (!readiness)
177
+ return undefined;
178
+ return {
179
+ state: readiness.state,
180
+ nextAction: readiness.nextAction,
181
+ retryable: readiness.retryable,
182
+ ...(readiness.firstMissing ? { firstMissing: readiness.firstMissing } : {}),
183
+ guidance: readiness.guidance,
184
+ };
185
+ }
169
186
  function canonicalRequirement() {
170
187
  return {
171
188
  name: "canonicalDocument.read",
@@ -3,9 +3,11 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
3
  import { resolve as resolvePath } from "node:path";
4
4
  import { z } from "zod";
5
5
  import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
6
- import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
7
  import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
8
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
9
+ import { EditingSessionRepository } from "./headless-sessions.js";
10
+ import { SessionMaterializationJobs, } from "./materialization-jobs.js";
9
11
  const revisionValueSchema = z.object({
10
12
  id: z.string(),
11
13
  sequence: z.number().int().nonnegative(),
@@ -645,6 +647,21 @@ function jsonResult(value) {
645
647
  content: [{ type: "text", text: JSON.stringify(value) }],
646
648
  };
647
649
  }
650
+ async function sessionResult(action) {
651
+ try {
652
+ return jsonResult(await action());
653
+ }
654
+ catch (error) {
655
+ const message = error instanceof Error ? error.message : String(error);
656
+ return {
657
+ isError: true,
658
+ content: [{
659
+ type: "text",
660
+ text: JSON.stringify({ code: message.split(":", 1)[0] || "SESSION_ERROR", message }),
661
+ }],
662
+ };
663
+ }
664
+ }
648
665
  function capabilityErrorResult(operation, capabilityName, capability) {
649
666
  return {
650
667
  isError: true,
@@ -685,6 +702,20 @@ function nativeMediaImportErrorResult(error) {
685
702
  }],
686
703
  };
687
704
  }
705
+ async function nativeMutationResult(action) {
706
+ try {
707
+ return jsonResult(await action());
708
+ }
709
+ catch (error) {
710
+ const serialized = serializeNativeFinalCutPartialMutationError(error);
711
+ if (!serialized)
712
+ throw error;
713
+ return {
714
+ isError: true,
715
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
716
+ };
717
+ }
718
+ }
688
719
  function capabilityUnavailableErrorResult(error) {
689
720
  const serialized = serializeCapabilityUnavailableError(error);
690
721
  if (!serialized)
@@ -787,6 +818,99 @@ export function createMcpServer(runtime, options = {}) {
787
818
  runtime.registerBuiltinSkills();
788
819
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
789
820
  const nativeTransitionAssets = new Map();
821
+ const sessions = options.sessionDirectory ? new EditingSessionRepository(options.sessionDirectory) : undefined;
822
+ const materializations = sessions && options.materializationDirectory
823
+ ? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
824
+ : undefined;
825
+ const requireSessions = () => {
826
+ if (!sessions)
827
+ throw new Error("SESSION_STORAGE_UNAVAILABLE: configure a session directory");
828
+ return sessions;
829
+ };
830
+ const requireMaterializations = () => {
831
+ if (!materializations)
832
+ throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
833
+ return materializations;
834
+ };
835
+ const sessionOperationSchema = z.array(z.unknown());
836
+ server.registerTool("session.create", {
837
+ description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
838
+ inputSchema: {
839
+ sessionId: z.string().min(1).optional(),
840
+ provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }).optional(),
841
+ base: z.unknown(),
842
+ },
843
+ }, async ({ sessionId, provider, base }) => sessionResult(async () => requireSessions().create({
844
+ ...(sessionId ? { sessionId } : {}),
845
+ ...(provider ? { provider } : {}),
846
+ base: base,
847
+ })));
848
+ server.registerTool("session.inspect", {
849
+ description: "Inspect a persisted editing session and its exact base and desired Timeline IR.",
850
+ inputSchema: { sessionId: z.string().min(1) },
851
+ }, async ({ sessionId }) => sessionResult(async () => requireSessions().inspect(sessionId)));
852
+ server.registerTool("session.edit.preview", {
853
+ description: "Preview provider-neutral session edits without persisting or mutating Final Cut.",
854
+ inputSchema: {
855
+ sessionId: z.string().min(1),
856
+ expectedRevision: revisionValueSchema.optional(),
857
+ operations: sessionOperationSchema,
858
+ },
859
+ }, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().preview(sessionId, operations, expectedRevision)));
860
+ server.registerTool("session.edit.execute", {
861
+ description: "Apply edits only to a persisted session's desired Timeline IR.",
862
+ inputSchema: {
863
+ sessionId: z.string().min(1),
864
+ expectedRevision: revisionValueSchema.optional(),
865
+ operations: sessionOperationSchema,
866
+ },
867
+ }, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().execute(sessionId, operations, expectedRevision)));
868
+ server.registerTool("session.status", {
869
+ description: "Read editing-session readiness, provider binding, and revisions.",
870
+ inputSchema: { sessionId: z.string().min(1) },
871
+ }, async ({ sessionId }) => sessionResult(async () => requireSessions().status(sessionId)));
872
+ server.registerTool("session.reconcile", {
873
+ description: "Reconcile a fresh provider Timeline IR with the session base and desired state.",
874
+ inputSchema: {
875
+ sessionId: z.string().min(1),
876
+ provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }),
877
+ providerState: z.unknown(),
878
+ },
879
+ }, async ({ sessionId, provider, providerState }) => sessionResult(async () => requireSessions().reconcile(sessionId, provider, providerState)));
880
+ server.registerTool("session.observe", {
881
+ description: "Bind read-only non-canonical Final Cut SQLite evidence to session freshness.",
882
+ inputSchema: { sessionId: z.string().min(1), sourcePath: z.string().min(1) },
883
+ }, async ({ sessionId, sourcePath }) => sessionResult(async () => {
884
+ if (!options.sqliteObservationProvider) {
885
+ throw new Error("FINAL_CUT_SQLITE_INSPECTION_UNAVAILABLE: no read-only observation provider is configured");
886
+ }
887
+ return requireSessions().observe(sessionId, sourcePath, options.sqliteObservationProvider);
888
+ }));
889
+ const sessionMaterializationTargetSchema = z.object({
890
+ provider: z.literal("final-cut"),
891
+ libraryUid: z.string().min(1),
892
+ eventUid: z.string().min(1),
893
+ projectUid: z.string().min(1),
894
+ sequenceUid: z.string().min(1),
895
+ eventName: z.string().min(1).optional(),
896
+ materialization: z.literal("versioned").optional(),
897
+ }).strict();
898
+ server.registerTool("session.materialize.preview", {
899
+ description: "Preview deterministic versioned FCPXML materialization without staging or publishing it.",
900
+ inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema },
901
+ }, async ({ sessionId, target }) => sessionResult(async () => requireMaterializations().preview(sessionId, target)));
902
+ server.registerTool("session.materialize.execute", {
903
+ description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
904
+ inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
905
+ }, async ({ sessionId, target, confirm }) => sessionResult(async () => requireMaterializations().execute(sessionId, target, confirm)));
906
+ server.registerTool("session.materialize.status", {
907
+ description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
908
+ inputSchema: { jobId: z.string().min(1) },
909
+ }, async ({ jobId }) => sessionResult(async () => requireMaterializations().status(jobId)));
910
+ server.registerTool("session.materialize.retry", {
911
+ description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
912
+ inputSchema: { jobId: z.string().min(1) },
913
+ }, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
790
914
  server.registerTool("connection.status", {
791
915
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
792
916
  inputSchema: {},
@@ -1000,7 +1124,7 @@ export function createMcpServer(runtime, options = {}) {
1000
1124
  if (!options.nativeEditor)
1001
1125
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
1002
1126
  const operation = nativeEditSchema.parse(input);
1003
- return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
1127
+ return nativeMutationResult(() => options.nativeEditor.edit(operation, { signal: extra.signal }));
1004
1128
  });
1005
1129
  server.registerTool("editor.native.disposable.preview", {
1006
1130
  description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
@@ -1073,7 +1197,7 @@ export function createMcpServer(runtime, options = {}) {
1073
1197
  }, async ({ previewToken }, extra) => {
1074
1198
  if (!options.nativeEditor)
1075
1199
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
1076
- return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
1200
+ return nativeMutationResult(() => options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
1077
1201
  });
1078
1202
  server.registerTool("editor.native.picture-in-picture.preview", {
1079
1203
  description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
@@ -1091,7 +1215,7 @@ export function createMcpServer(runtime, options = {}) {
1091
1215
  if (!options.nativeEditor)
1092
1216
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
1093
1217
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
1094
- return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
1218
+ return nativeMutationResult(() => options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
1095
1219
  });
1096
1220
  server.registerTool("editor.native.transition.search", {
1097
1221
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
@@ -1126,7 +1250,7 @@ export function createMcpServer(runtime, options = {}) {
1126
1250
  }, async ({ previewToken }, extra) => {
1127
1251
  if (!options.nativeEditor)
1128
1252
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
1129
- return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
1253
+ return nativeMutationResult(() => options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
1130
1254
  });
1131
1255
  server.registerTool("editor.native.mask.preview", {
1132
1256
  description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
@@ -1142,7 +1266,7 @@ export function createMcpServer(runtime, options = {}) {
1142
1266
  }, async ({ previewToken }, extra) => {
1143
1267
  if (!options.nativeEditor)
1144
1268
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
1145
- return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
1269
+ return nativeMutationResult(() => options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
1146
1270
  });
1147
1271
  server.registerTool("editor.native.undo", {
1148
1272
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
@@ -1182,7 +1306,7 @@ export function createMcpServer(runtime, options = {}) {
1182
1306
  }, async ({ previewToken }, extra) => {
1183
1307
  if (!options.nativeEditor)
1184
1308
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
1185
- return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1309
+ return nativeMutationResult(() => options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1186
1310
  });
1187
1311
  server.registerTool("editor.native.media.append.selected.preview", {
1188
1312
  description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
@@ -1198,7 +1322,7 @@ export function createMcpServer(runtime, options = {}) {
1198
1322
  }, async ({ previewToken }, extra) => {
1199
1323
  if (!options.nativeEditor)
1200
1324
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1201
- return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1325
+ return nativeMutationResult(() => options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1202
1326
  });
1203
1327
  server.registerTool("editor.native.media.insert.preview", {
1204
1328
  description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
@@ -1214,7 +1338,7 @@ export function createMcpServer(runtime, options = {}) {
1214
1338
  }, async ({ previewToken }, extra) => {
1215
1339
  if (!options.nativeEditor)
1216
1340
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1217
- return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1341
+ return nativeMutationResult(() => options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1218
1342
  });
1219
1343
  server.registerTool("editor.native.timeline.locate", {
1220
1344
  description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
@@ -1246,7 +1370,7 @@ export function createMcpServer(runtime, options = {}) {
1246
1370
  }, async ({ previewToken }, extra) => {
1247
1371
  if (!options.nativeEditor)
1248
1372
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1249
- return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1373
+ return nativeMutationResult(() => options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1250
1374
  });
1251
1375
  server.registerTool("editor.native.delete-range.preview", {
1252
1376
  description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
@@ -1262,7 +1386,7 @@ export function createMcpServer(runtime, options = {}) {
1262
1386
  }, async ({ previewToken }, extra) => {
1263
1387
  if (!options.nativeEditor)
1264
1388
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1265
- return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1389
+ return nativeMutationResult(() => options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1266
1390
  });
1267
1391
  server.registerTool("editor.native.trim-to-duration.preview", {
1268
1392
  description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
@@ -1278,7 +1402,7 @@ export function createMcpServer(runtime, options = {}) {
1278
1402
  }, async ({ previewToken }, extra) => {
1279
1403
  if (!options.nativeEditor)
1280
1404
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1281
- return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1405
+ return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1282
1406
  });
1283
1407
  server.registerTool("artifact.publish.preview", {
1284
1408
  description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
@@ -2005,6 +2129,15 @@ async function requireEditingRoute(runtime, options, operation) {
2005
2129
  }
2006
2130
  async function editingRouteContext(runtime, options) {
2007
2131
  const connection = await effectiveConnectionStatus(runtime, options);
2132
+ let nativeReadiness;
2133
+ if (options.nativeEditor && typeof options.nativeEditor.inspect === "function") {
2134
+ try {
2135
+ nativeReadiness = (await options.nativeEditor.inspect()).readiness;
2136
+ }
2137
+ catch {
2138
+ nativeReadiness = undefined;
2139
+ }
2140
+ }
2008
2141
  let editor;
2009
2142
  try {
2010
2143
  editor = await inspectMcpEditor(runtime, options);
@@ -2016,5 +2149,6 @@ async function editingRouteContext(runtime, options) {
2016
2149
  connection,
2017
2150
  ...(editor ? { editor } : {}),
2018
2151
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2152
+ ...(nativeReadiness ? { nativeReadiness } : {}),
2019
2153
  };
2020
2154
  }