@morshoto/framekit 0.1.11 → 0.1.13

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 (29) 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/canonical-recovery.js +31 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical.js +978 -98
  6. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +26 -7
  7. package/dist-package/adapters/final-cut/typescript/src/index.js +3 -0
  8. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +2 -0
  9. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  10. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +71 -17
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  12. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  13. package/dist-package/apps/mcp-server/src/headless-sessions.js +47 -4
  14. package/dist-package/apps/mcp-server/src/main.js +33 -1
  15. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  16. package/dist-package/apps/mcp-server/src/server.js +87 -28
  17. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  18. package/dist-package/packages/runtime/src/context/context-engine.js +313 -8
  19. package/dist-package/packages/runtime/src/context/context-service.js +5 -2
  20. package/dist-package/packages/runtime/src/context/project-catalog.js +58 -2
  21. package/dist-package/packages/runtime/src/domain/incremental-sync.js +153 -0
  22. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  23. package/dist-package/packages/runtime/src/editing/edit-service.js +8 -2
  24. package/dist-package/packages/runtime/src/runtime.js +5 -2
  25. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  26. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  27. package/dist-package/packages/runtime/src/timeline/editing-session.js +13 -0
  28. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +169 -10
  29. package/package.json +9 -5
@@ -0,0 +1,230 @@
1
+ import { createHash } from "node:crypto";
2
+ import { timelineIrDigest, validateTimelineIr } from "../../../../packages/runtime/src/index.js";
3
+ import { decodeFinalCutKeyedArchive, } from "./sqlite-experiment.js";
4
+ /**
5
+ * Phase 5 gate. This never invents an NSKeyedArchiver encoder: the caller must
6
+ * provide one and the bytes must be exactly identical for this proof to pass.
7
+ */
8
+ export async function proveFinalCutArchiveByteRoundTrip(payload, decoder, encoder) {
9
+ const decoded = await decodeFinalCutKeyedArchive(payload, decoder);
10
+ const encoded = await encoder(decoded);
11
+ if (!Buffer.from(payload).equals(Buffer.from(encoded))) {
12
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_ROUND_TRIP_UNPROVEN: decode/encode bytes are not identical");
13
+ }
14
+ return {
15
+ originalDigest: digest(payload),
16
+ encodedDigest: digest(encoded),
17
+ byteIdentical: true,
18
+ };
19
+ }
20
+ /**
21
+ * Phase 6 compiler. IDs are allocated from observed maxima and identifiers are
22
+ * deterministic, content-bound, and collision checked. Existing names are not
23
+ * update targets; every node is an insert into a new versioned graph.
24
+ */
25
+ export async function compileFinalCutVersionedGraphRecipe(request) {
26
+ validateTimelineIr(request.timeline);
27
+ requireText(request.projectUid, "projectUid");
28
+ requireText(request.sequenceUid, "sequenceUid");
29
+ validateAllocation(request.existing);
30
+ const timelineDigest = timelineIrDigest(request.timeline);
31
+ const digestPrefix = timelineDigest.slice(0, 16);
32
+ const usedCollection = new Set(request.existing.existingCollectionPrimaryKeys);
33
+ const usedMetadata = new Set(request.existing.existingMetadataPrimaryKeys);
34
+ const usedCatalog = new Set(request.existing.existingCatalogPrimaryKeys);
35
+ const usedIdentifiers = new Set(request.existing.existingIdentifiers);
36
+ const collectionNext = nextPositive(usedCollection);
37
+ const metadataNext = nextPositive(usedMetadata);
38
+ const catalogNext = nextPositive(usedCatalog);
39
+ let nextCollection = collectionNext;
40
+ let nextMetadata = metadataNext;
41
+ let nextCatalog = catalogNext;
42
+ const entityByType = new Map();
43
+ for (const entry of Object.values(request.existing.primaryKeyMaxByEntity))
44
+ entityByType.set(entry.entity, entry.max);
45
+ const descriptors = [
46
+ { logicalId: `project:${request.timeline.project.id}`, kind: "project", name: versionedName(request.timeline.project.name, digestPrefix) },
47
+ { logicalId: `sequence:${request.timeline.sequence.id}`, kind: "sequence", name: versionedName(request.timeline.sequence.name, digestPrefix) },
48
+ ...request.timeline.resources.map((resource) => ({ logicalId: `resource:${resource.id}`, kind: "resource", name: resource.name })),
49
+ ...request.timeline.sequence.occurrences.map((item) => ({ logicalId: `occurrence:${item.id}`, kind: "occurrence", name: item.name })),
50
+ ...request.timeline.sequence.storyElements.map((item) => ({ logicalId: `story-element:${item.id}`, kind: "story-element", name: item.kind })),
51
+ ...request.timeline.sequence.markers.map((item) => ({ logicalId: `marker:${item.id}`, kind: "marker", name: item.name })),
52
+ ...request.timeline.sequence.captions.map((item) => ({ logicalId: `caption:${item.id}`, kind: "caption", name: item.text })),
53
+ ];
54
+ const nodes = [];
55
+ const nodeByLogicalId = new Map();
56
+ for (const descriptor of descriptors) {
57
+ const entityEntry = entityForKind(descriptor.kind, request.existing.primaryKeyMaxByEntity);
58
+ if (!entityEntry)
59
+ throw new Error(`FINAL_CUT_SHADOW_RECIPE_UNPROVEN: entity allocation is missing for ${descriptor.kind}`);
60
+ const identifier = allocateIdentifier(`framekit-${descriptor.kind}`, descriptor.logicalId, digestPrefix, usedIdentifiers);
61
+ const catalogIdentifier = allocateIdentifier("framekit-catalog", descriptor.logicalId, digestPrefix, usedIdentifiers);
62
+ const node = {
63
+ logicalId: descriptor.logicalId,
64
+ kind: descriptor.kind,
65
+ entity: entityEntry.entity,
66
+ primaryKey: allocateNumber(usedCollection, () => nextCollection++),
67
+ optimisticVersion: 1,
68
+ identifier,
69
+ name: descriptor.name,
70
+ catalogPrimaryKey: allocateNumber(usedCatalog, () => nextCatalog++),
71
+ catalogIdentifier,
72
+ metadataPrimaryKey: allocateNumber(usedMetadata, () => nextMetadata++),
73
+ metadataIdentifier: `${identifier}-metadata`,
74
+ archive: await request.archiveEncoder(descriptor),
75
+ };
76
+ if (!Buffer.from(node.archive).subarray(0, 8).equals(Buffer.from("bplist00", "ascii"))) {
77
+ throw new Error(`FINAL_CUT_SHADOW_ARCHIVE_UNSUPPORTED: encoder returned a non-binary-plist archive for ${descriptor.logicalId}`);
78
+ }
79
+ nodes.push(node);
80
+ nodeByLogicalId.set(descriptor.logicalId, node);
81
+ entityByType.set(node.entity, (entityByType.get(node.entity) ?? entityEntry.max) + 1);
82
+ }
83
+ const edges = [];
84
+ const project = nodeByLogicalId.get(`project:${request.timeline.project.id}`);
85
+ const sequence = nodeByLogicalId.get(`sequence:${request.timeline.sequence.id}`);
86
+ edges.push({ parentPrimaryKey: project.primaryKey, childPrimaryKey: sequence.primaryKey });
87
+ for (const resource of request.timeline.resources)
88
+ edges.push({ parentPrimaryKey: sequence.primaryKey, childPrimaryKey: nodeByLogicalId.get(`resource:${resource.id}`).primaryKey });
89
+ for (const occurrence of request.timeline.sequence.occurrences)
90
+ edges.push({ parentPrimaryKey: sequence.primaryKey, childPrimaryKey: nodeByLogicalId.get(`occurrence:${occurrence.id}`).primaryKey });
91
+ for (const item of request.timeline.sequence.storyElements)
92
+ edges.push({ parentPrimaryKey: sequence.primaryKey, childPrimaryKey: nodeByLogicalId.get(`story-element:${item.id}`).primaryKey });
93
+ for (const marker of request.timeline.sequence.markers)
94
+ edges.push({ parentPrimaryKey: sequence.primaryKey, childPrimaryKey: nodeByLogicalId.get(`marker:${marker.id}`).primaryKey });
95
+ for (const caption of request.timeline.sequence.captions)
96
+ edges.push({ parentPrimaryKey: sequence.primaryKey, childPrimaryKey: nodeByLogicalId.get(`caption:${caption.id}`).primaryKey });
97
+ const primaryKeyUpdates = [...entityByType.entries()].map(([entity, nextMax]) => {
98
+ const original = Object.values(request.existing.primaryKeyMaxByEntity).find((entry) => entry.entity === entity);
99
+ return { entity, expectedMax: original.max, nextMax };
100
+ }).filter((entry) => entry.nextMax > entry.expectedMax).sort((left, right) => left.entity - right.entity);
101
+ return {
102
+ kind: "versioned-project-materialization",
103
+ fingerprint: request.fingerprint,
104
+ timelineDigest,
105
+ projectUid: request.projectUid,
106
+ sequenceUid: request.sequenceUid,
107
+ nodes,
108
+ edges,
109
+ primaryKeyUpdates,
110
+ catalogEntity: request.existing.catalogEntity,
111
+ metadataEntity: request.existing.metadataEntity,
112
+ };
113
+ }
114
+ /** Build the only SQL accepted for a versioned graph recipe. */
115
+ export function buildFinalCutVersionedGraphSql(recipe) {
116
+ if (recipe.kind !== "versioned-project-materialization" || recipe.nodes.length === 0) {
117
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_INVALID: versioned graph is empty or unsupported");
118
+ }
119
+ const statements = ["BEGIN IMMEDIATE;"];
120
+ for (const update of recipe.primaryKeyUpdates) {
121
+ statements.push(`UPDATE Z_PRIMARYKEY SET Z_MAX = ${number(update.nextMax)} WHERE Z_ENT = ${number(update.entity)} AND Z_MAX = ${number(update.expectedMax)}; SELECT changes();`);
122
+ }
123
+ for (const node of recipe.nodes) {
124
+ statements.push(`INSERT INTO ZCATALOGROOT (Z_PK, Z_ENT, Z_OPT, ZIDENTIFIER, ZNAME) VALUES (${number(node.catalogPrimaryKey)}, ${number(recipe.catalogEntity)}, 1, '${sqlText(node.catalogIdentifier)}', '${sqlText(node.name)}');`);
125
+ }
126
+ for (const node of recipe.nodes) {
127
+ statements.push(`INSERT INTO ZCOLLECTION (Z_PK, Z_ENT, Z_OPT, ZCATALOG, ZMETADATA, ZIDENTIFIER, ZNAME, ZTYPE) VALUES (${number(node.primaryKey)}, ${number(node.entity)}, 1, ${number(node.catalogPrimaryKey)}, ${number(node.metadataPrimaryKey)}, '${sqlText(node.identifier)}', '${sqlText(node.name)}', '${sqlText(node.kind)}');`);
128
+ }
129
+ for (const node of recipe.nodes) {
130
+ statements.push(`INSERT INTO ZCOLLECTIONMD (Z_PK, Z_ENT, Z_OPT, ZCOLLECTION, ZIDENTIFIER, ZDICTIONARYDATA) VALUES (${number(node.metadataPrimaryKey)}, ${number(recipe.metadataEntity)}, 1, ${number(node.primaryKey)}, '${sqlText(node.metadataIdentifier)}', x'${hex(node.archive)}');`);
131
+ }
132
+ for (const edge of recipe.edges) {
133
+ statements.push(`INSERT INTO Z_3CHILDCOLLECTIONS (Z_3PARENTCOLLECTIONS, Z_3CHILDCOLLECTIONS) VALUES (${number(edge.parentPrimaryKey)}, ${number(edge.childPrimaryKey)});`);
134
+ }
135
+ statements.push("COMMIT;");
136
+ return { sql: statements.join(" "), expectedCasUpdates: recipe.primaryKeyUpdates.length };
137
+ }
138
+ /**
139
+ * Phase 8 gate. Reopen and export are injected headed operations; a digest or
140
+ * target mismatch can never be reported as native completion.
141
+ */
142
+ export async function verifyFinalCutNativeReopen(target, desired, reopen, exportTarget) {
143
+ try {
144
+ validateTimelineIr(desired);
145
+ requireText(target.projectUid, "target.projectUid");
146
+ requireText(target.sequenceUid, "target.sequenceUid");
147
+ await reopen();
148
+ const readback = await exportTarget(target);
149
+ if (readback.target.projectUid !== target.projectUid || readback.target.sequenceUid !== target.sequenceUid) {
150
+ return { status: "not_completed", reason: "FINAL_CUT_NATIVE_TARGET_MISMATCH" };
151
+ }
152
+ validateTimelineIr(readback.timeline);
153
+ const desiredDigest = timelineIrDigest(desired);
154
+ const readbackDigest = timelineIrDigest(readback.timeline);
155
+ if (desiredDigest !== readbackDigest)
156
+ return { status: "not_completed", reason: "FINAL_CUT_NATIVE_TIMELINE_MISMATCH" };
157
+ return { status: "native_completed", target: structuredClone(target), desiredDigest, readbackDigest };
158
+ }
159
+ catch (error) {
160
+ return { status: "not_completed", reason: error instanceof Error ? error.message : String(error) };
161
+ }
162
+ }
163
+ function validateAllocation(allocation) {
164
+ for (const key of ["existingCollectionPrimaryKeys", "existingMetadataPrimaryKeys", "existingCatalogPrimaryKeys", "existingIdentifiers"]) {
165
+ if (!Array.isArray(allocation[key]))
166
+ throw new Error(`FINAL_CUT_SHADOW_RECIPE_INVALID: ${key} is required`);
167
+ }
168
+ if (!Number.isSafeInteger(allocation.catalogEntity) || !Number.isSafeInteger(allocation.metadataEntity)) {
169
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_INVALID: catalog and metadata entities are required");
170
+ }
171
+ }
172
+ function entityForKind(kind, values) {
173
+ const aliases = {
174
+ project: ["project", "FFMediaEventProject"],
175
+ sequence: ["sequence", "FFAnchoredSequence"],
176
+ resource: ["resource", "FFAsset", "FFMediaRep"],
177
+ occurrence: ["occurrence", "FFAnchoredClip"],
178
+ "story-element": ["story-element"],
179
+ marker: ["marker"],
180
+ caption: ["caption"],
181
+ };
182
+ for (const alias of aliases[kind])
183
+ if (values[alias])
184
+ return values[alias];
185
+ return undefined;
186
+ }
187
+ function allocateIdentifier(prefix, logicalId, digestPrefix, used) {
188
+ const base = `${prefix}-${shortHash(`${logicalId}:${digestPrefix}`)}`;
189
+ let value = base;
190
+ let suffix = 2;
191
+ while (used.has(value))
192
+ value = `${base}-${suffix++}`;
193
+ used.add(value);
194
+ return value;
195
+ }
196
+ function allocateNumber(used, next) {
197
+ let value = next();
198
+ while (used.has(value))
199
+ value = next();
200
+ used.add(value);
201
+ return value;
202
+ }
203
+ function nextPositive(values) {
204
+ return Math.max(0, ...values) + 1;
205
+ }
206
+ function versionedName(name, digestPrefix) {
207
+ return `${name} (Framekit ${digestPrefix})`;
208
+ }
209
+ function requireText(value, label) {
210
+ if (typeof value !== "string" || value.length === 0 || value.includes("\0"))
211
+ throw new Error(`FINAL_CUT_SHADOW_RECIPE_INVALID: ${label} must be non-empty text`);
212
+ }
213
+ function number(value) {
214
+ if (!Number.isSafeInteger(value) || value < 0)
215
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_INVALID: numeric field is unsafe");
216
+ return String(value);
217
+ }
218
+ function sqlText(value) {
219
+ requireText(value, "SQL text");
220
+ return value.replaceAll("'", "''");
221
+ }
222
+ function hex(value) {
223
+ return Buffer.from(value).toString("hex");
224
+ }
225
+ function digest(value) {
226
+ return createHash("sha256").update(value).digest("hex");
227
+ }
228
+ function shortHash(value) {
229
+ return createHash("sha256").update(value).digest("hex").slice(0, 16);
230
+ }
@@ -2,10 +2,20 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
2
2
  import { dirname, join, resolve } from "node:path";
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import { EditingSession, } from "../../../packages/runtime/src/index.js";
5
+ export function createCanonicalSessionChangeSource(readCurrent) {
6
+ return {
7
+ changesSince: async (revision) => ({
8
+ from: revision,
9
+ to: (await readCurrent()).revision,
10
+ }),
11
+ };
12
+ }
5
13
  export class EditingSessionRepository {
6
14
  directory;
7
- constructor(directory) {
15
+ changeSource;
16
+ constructor(directory, changeSource) {
8
17
  this.directory = directory;
18
+ this.changeSource = changeSource;
9
19
  }
10
20
  async create(input) {
11
21
  const sessionId = input.sessionId ?? `session-${randomUUID()}`;
@@ -19,15 +29,19 @@ export class EditingSessionRepository {
19
29
  }
20
30
  async preview(sessionId, operations, expectedRevision) {
21
31
  const session = await this.load(sessionId);
32
+ await this.refreshLoaded(sessionId, session);
22
33
  return session.preview(operations, expectedRevision);
23
34
  }
24
35
  async execute(sessionId, operations, expectedRevision) {
25
36
  const session = await this.load(sessionId);
37
+ await this.refreshLoaded(sessionId, session);
26
38
  session.apply(operations, expectedRevision);
27
39
  return this.save(sessionId, session);
28
40
  }
29
41
  async status(sessionId) {
30
- const { document } = await this.inspect(sessionId);
42
+ const session = await this.load(sessionId);
43
+ await this.refreshLoaded(sessionId, session);
44
+ const document = session.document();
31
45
  return {
32
46
  sessionId,
33
47
  state: document.state,
@@ -68,8 +82,22 @@ export class EditingSessionRepository {
68
82
  const stored = await this.save(sessionId, session);
69
83
  return { ...stored, observation, change };
70
84
  }
71
- loadForMaterialization(sessionId) {
72
- return this.load(sessionId);
85
+ async refresh(sessionId) {
86
+ const session = await this.load(sessionId);
87
+ if (!this.changeSource)
88
+ throw new Error("CAPABILITY_UNAVAILABLE: session provider change stream");
89
+ const change = await this.refreshLoaded(sessionId, session);
90
+ return {
91
+ sessionId,
92
+ document: session.document(),
93
+ providerRevision: change.to,
94
+ change: sameRevision(change.from, change.to) ? "unchanged" : "changed",
95
+ };
96
+ }
97
+ async loadForMaterialization(sessionId) {
98
+ const session = await this.load(sessionId);
99
+ await this.refreshLoaded(sessionId, session);
100
+ return session;
73
101
  }
74
102
  checkpoint(sessionId, session) {
75
103
  return this.save(sessionId, session);
@@ -85,6 +113,18 @@ export class EditingSessionRepository {
85
113
  throw error;
86
114
  }
87
115
  }
116
+ async refreshLoaded(sessionId, session) {
117
+ if (!this.changeSource)
118
+ return undefined;
119
+ const change = await this.changeSource.changesSince(session.base().revision);
120
+ if (!sameRevision(change.from, session.base().revision)) {
121
+ throw new Error("SESSION_CHANGE_STREAM_BASE_MISMATCH: provider change stream did not start at the session base");
122
+ }
123
+ const freshness = session.observeProviderRevision(change.to);
124
+ if (freshness === "changed")
125
+ await this.save(sessionId, session);
126
+ return change;
127
+ }
88
128
  async save(sessionId, session) {
89
129
  const path = this.path(sessionId);
90
130
  await mkdir(dirname(path), { recursive: true });
@@ -110,3 +150,6 @@ export class EditingSessionRepository {
110
150
  return join(this.directory, `${sessionId}.json`);
111
151
  }
112
152
  }
153
+ function sameRevision(left, right) {
154
+ return left.id === right.id && left.sequence === right.sequence;
155
+ }
@@ -6,6 +6,7 @@ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapte
6
6
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
7
7
  import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
8
8
  import { createMcpServer } from "./server.js";
9
+ import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
9
10
  const fixture = new InMemoryEditorAdapter({
10
11
  projectId: "project-1",
11
12
  projectName: "Phase 2 Fixture",
@@ -85,6 +86,7 @@ const nativeEditor = liveMode
85
86
  const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
86
87
  ? new FinalCutNativeAutomationAdapter({
87
88
  enabled: true,
89
+ liveState: () => liveAdapter.readLiveState(),
88
90
  nativeOperationLease,
89
91
  })
90
92
  : nativeEditor;
@@ -96,12 +98,39 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
96
98
  const result = await canonicalNativeMutationEditor.edit({ type: "rename-selected-clip", name });
97
99
  return { operationId: result.operationId, undoAvailable: result.undoAvailable };
98
100
  },
101
+ trimSelectedClipToRange: async (range) => {
102
+ const result = await canonicalNativeMutationEditor.trimSelectedClipToRange(range);
103
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
104
+ },
105
+ addMarkerAtTime: async (marker) => {
106
+ const result = await canonicalNativeMutationEditor.addMarkerAtTime(marker);
107
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
108
+ },
109
+ rippleDeleteRange: async (range) => {
110
+ const preview = await canonicalNativeMutationEditor.previewDeleteRange(range);
111
+ const result = await canonicalNativeMutationEditor.executeDeleteRange(preview.previewToken);
112
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
113
+ },
114
+ setSelectedClipGain: async (gainDb) => {
115
+ const result = await canonicalNativeMutationEditor.edit({ type: "set-selected-clip-gain", gainDb });
116
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
117
+ },
99
118
  undo: async (operationId) => {
100
119
  const result = await canonicalNativeMutationEditor.undo(operationId);
101
120
  return { undone: result.undone, verification: result.verification };
102
121
  },
103
122
  },
104
- readSnapshot: () => new FinalCutCanonicalSnapshotSource().readSnapshot(),
123
+ readSnapshot: async () => {
124
+ const live = await liveAdapter.readLiveState();
125
+ const projectId = live.project?.id;
126
+ const sequenceId = live.sequence?.id;
127
+ if (!projectId || projectId.startsWith("final-cut:") || !sequenceId || sequenceId.startsWith("final-cut:")) {
128
+ throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
129
+ }
130
+ return new FinalCutCanonicalSnapshotSource({
131
+ target: { projectId, projectUid: projectId, sequenceId },
132
+ }).readSnapshot();
133
+ },
105
134
  resolveTarget: createFinalCutNativeTargetResolver(nativeEditor),
106
135
  backgroundCatalog: backgroundLibraryProvider,
107
136
  })
@@ -133,6 +162,8 @@ const editor = liveMode
133
162
  const analyzers = liveMode
134
163
  ? createCommandAnalyzers({
135
164
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
165
+ speechProviderVersion: process.env.FRAMEKIT_SPEECH_ANALYZER_VERSION,
166
+ speechRequireVad: process.env.FRAMEKIT_SPEECH_REQUIRE_VAD === "1",
136
167
  audioCommand: process.env.FRAMEKIT_AUDIO_ANALYZER,
137
168
  visualCommand: process.env.FRAMEKIT_VISUAL_ANALYZER,
138
169
  metadataCommand: process.env.FRAMEKIT_METADATA_ANALYZER,
@@ -191,6 +222,7 @@ const server = createMcpServer(runtime, {
191
222
  ...(sessionMaterializationPublisher?.isAvailable() ? { sessionMaterializationPublisher } : {}),
192
223
  videoExporter,
193
224
  sessionDirectory: join(framekitStateDirectory, "sessions"),
225
+ sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
194
226
  materializationDirectory: join(framekitStateDirectory, "materializations"),
195
227
  sqliteObservationProvider,
196
228
  });
@@ -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",