@morshoto/framekit 0.1.17 → 0.2.2

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 (58) hide show
  1. package/README.md +25 -14
  2. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  7. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
  10. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  11. package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
  12. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  14. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  15. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
  18. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
  19. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
  21. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  22. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  23. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  24. package/dist-package/apps/cli/src/main.js +76 -19
  25. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  26. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  27. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  28. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  29. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  30. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  31. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  32. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  33. package/dist-package/apps/mcp-server/src/main.js +50 -21
  34. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  35. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  36. package/dist-package/apps/mcp-server/src/server.js +986 -180
  37. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  38. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  39. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  40. package/dist-package/apps/mcp-server/src/version.js +21 -2
  41. package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
  42. package/dist-package/packages/headless-application/src/index.js +1 -0
  43. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  44. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  45. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  46. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  47. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  48. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  49. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  50. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  51. package/dist-package/packages/runtime/src/index.js +1 -0
  52. package/dist-package/packages/runtime/src/runtime.js +22 -7
  53. package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
  54. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  55. package/dist-package/packages/testkit/src/index.js +1 -0
  56. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  57. package/package.json +36 -14
  58. package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
@@ -0,0 +1 @@
1
+ export * from "./headless-projects.js";
@@ -121,10 +121,14 @@ export class MediaAnalysisService {
121
121
  }
122
122
  async understandMedia(mediaId) {
123
123
  const project = await this.project.inspectProject();
124
+ return this.understandMediaInProject(mediaId, project, true);
125
+ }
126
+ async understandMediaInProject(mediaId, project, attachToLiveContext = false) {
124
127
  const media = findMedia(project, mediaId);
125
128
  const cached = await this.loadCachedUnderstanding(project, media);
126
129
  if (cached) {
127
- this.context.attachMediaUnderstanding(cached);
130
+ if (attachToLiveContext)
131
+ this.context.attachMediaUnderstanding(cached);
128
132
  return structuredClone(cached);
129
133
  }
130
134
  const input = { project, media };
@@ -160,7 +164,8 @@ export class MediaAnalysisService {
160
164
  ],
161
165
  analysisRevision: project.revision,
162
166
  };
163
- this.context.attachMediaUnderstanding(understanding);
167
+ if (attachToLiveContext)
168
+ this.context.attachMediaUnderstanding(understanding);
164
169
  await this.options.semanticMediaIndexStore?.save(understanding);
165
170
  return structuredClone(understanding);
166
171
  }
@@ -179,10 +184,15 @@ export class MediaAnalysisService {
179
184
  }
180
185
  async planRoughCut(request) {
181
186
  const project = await this.project.inspectProject();
187
+ return this.planRoughCutInProject(request, project);
188
+ }
189
+ async planRoughCutInProject(request, project) {
182
190
  const { maxShots: _maxShots, ...query } = request;
183
191
  const current = this.indexFromProject(project, query);
184
192
  const persisted = await this.persistedIndexEntries(query);
185
- return planRoughCut(mergeIndexEntries(persisted, current), project.revision, request);
193
+ const projectMedia = project.media.map(sourceIdentityOf);
194
+ const matchingPersisted = persisted.filter((entry) => projectMedia.some((source) => sameMediaSourceIdentity(source, entry.sourceIdentity)));
195
+ return planRoughCut(mergeIndexEntries(matchingPersisted, current), project.revision, request);
186
196
  }
187
197
  async inspectTimelineSemanticContext(query = {}) {
188
198
  const project = await this.project.inspectProject();
@@ -706,7 +716,7 @@ function emptySemanticDescription() {
706
716
  };
707
717
  }
708
718
  function matchesMediaIndexQuery(entry, query) {
709
- const text = query.query?.trim().toLowerCase();
719
+ const terms = query.query?.trim().toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
710
720
  const values = [
711
721
  entry.sourceIdentity.mediaId,
712
722
  entry.sourceIdentity.source,
@@ -717,7 +727,7 @@ function matchesMediaIndexQuery(entry, query) {
717
727
  ...entry.semantic.timeOfDay.map((tag) => tag.value),
718
728
  ...entry.semantic.moods.map((tag) => tag.value),
719
729
  ].map((value) => value.toLowerCase());
720
- if (text && !values.some((value) => value.includes(text)))
730
+ if (terms.length > 0 && !values.some((value) => terms.some((term) => value.includes(term))))
721
731
  return false;
722
732
  if (query.subject && !matchesTag(entry.semantic.subjects, query.subject))
723
733
  return false;
@@ -11,6 +11,10 @@ export class ProjectService {
11
11
  this.options = options;
12
12
  }
13
13
  async inspectProject() {
14
+ const inspect = () => this.inspectProjectInScope();
15
+ return this.adapter.withCanonicalReadScope?.(inspect) ?? inspect();
16
+ }
17
+ async inspectProjectInScope() {
14
18
  const identity = await this.adapter.getIdentity();
15
19
  const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(await this.adapter.getCapabilities(), {
16
20
  backend: identity.backend,
@@ -91,7 +95,7 @@ export class ProjectService {
91
95
  return this.adapter.listProjects();
92
96
  }
93
97
  async selectProject(selection) {
94
- const capabilities = await this.adapter.getCapabilities();
98
+ const capabilities = await this.adapter.getCapabilities({ probeCanonicalSnapshot: false });
95
99
  if (!capabilities.editor.projectSelection || !this.adapter.selectProject) {
96
100
  const identity = await this.adapter.getIdentity();
97
101
  throw new CapabilityUnavailableError("project.select", "editor.projectSelection", {
@@ -1,4 +1,4 @@
1
- import { mkdir as nodeMkdir, readFile as nodeReadFile, rename as nodeRename, unlink as nodeUnlink, writeFile as nodeWriteFile } from "node:fs/promises";
1
+ import { link as nodeLink, mkdir as nodeMkdir, readFile as nodeReadFile, rename as nodeRename, unlink as nodeUnlink, writeFile as nodeWriteFile } from "node:fs/promises";
2
2
  import { dirname } from "node:path";
3
3
  import { randomUUID } from "node:crypto";
4
4
  import { validateTimelineIr } from "../timeline/editing-session.js";
@@ -17,6 +17,7 @@ const fileSystem = {
17
17
  mkdir: async (path, options) => { await nodeMkdir(path, options); },
18
18
  readFile: async (path, encoding) => nodeReadFile(path, encoding),
19
19
  writeFile: async (path, data, options) => { await nodeWriteFile(path, data, options); },
20
+ link: async (from, to) => { await nodeLink(from, to); },
20
21
  rename: async (from, to) => { await nodeRename(from, to); },
21
22
  unlink: async (path) => { await nodeUnlink(path); },
22
23
  };
@@ -39,7 +40,7 @@ export class FramekitProjectStore {
39
40
  if (!isMissingFile(error))
40
41
  throw error;
41
42
  }
42
- return this.saveUnlocked(project);
43
+ return this.saveUnlocked(project, undefined, true);
43
44
  });
44
45
  }
45
46
  async load() {
@@ -65,7 +66,7 @@ export class FramekitProjectStore {
65
66
  async save(project, expectedRevision) {
66
67
  return this.withProjectLock(() => this.saveUnlocked(project, expectedRevision));
67
68
  }
68
- async saveUnlocked(project, expectedRevision) {
69
+ async saveUnlocked(project, expectedRevision, createOnly = false) {
69
70
  try {
70
71
  validateFramekitProject(project);
71
72
  }
@@ -82,10 +83,16 @@ export class FramekitProjectStore {
82
83
  try {
83
84
  await this.fs.mkdir(dirname(this.path), { recursive: true });
84
85
  await this.fs.writeFile(temporary, `${encodeFramekitProject(project)}\n`, { encoding: "utf8", flag: "wx" });
85
- await this.fs.rename(temporary, this.path);
86
+ if (createOnly)
87
+ await this.fs.link(temporary, this.path);
88
+ else
89
+ await this.fs.rename(temporary, this.path);
86
90
  return structuredClone(project);
87
91
  }
88
92
  catch (error) {
93
+ if (createOnly && isAlreadyExists(error)) {
94
+ throw new ProjectPersistenceError("PROJECT_ALREADY_EXISTS", `project file already exists: ${this.path}`, { path: this.path }, { cause: error });
95
+ }
89
96
  throw new ProjectPersistenceError("PROJECT_SAVE_FAILED", `atomic project write failed: ${this.path}`, { path: this.path }, { cause: error });
90
97
  }
91
98
  finally {
@@ -105,8 +112,8 @@ export class FramekitProjectStore {
105
112
  if (!isAlreadyExists(error)) {
106
113
  throw new ProjectPersistenceError("PROJECT_SAVE_FAILED", `could not acquire project lock: ${this.path}`, { path: this.path }, { cause: error });
107
114
  }
108
- if (await this.removeStaleLock(lockPath))
109
- continue;
115
+ // An empty or dead-PID lock may still belong to a live writer, or be
116
+ // replaced between inspection and unlink. Never reclaim it here.
110
117
  if (Date.now() >= deadline) {
111
118
  throw new ProjectPersistenceError("PROJECT_SAVE_FAILED", `could not acquire project lock: ${this.path}`, { path: this.path }, { cause: error });
112
119
  }
@@ -120,26 +127,6 @@ export class FramekitProjectStore {
120
127
  await this.removeTemporaryFile(lockPath);
121
128
  }
122
129
  }
123
- async removeStaleLock(lockPath) {
124
- let owner;
125
- try {
126
- owner = await this.fs.readFile(lockPath, "utf8");
127
- }
128
- catch (error) {
129
- return isMissingFile(error);
130
- }
131
- const pid = Number.parseInt(owner.trim(), 10);
132
- if (!Number.isInteger(pid) || pid <= 0 || isProcessDead(pid)) {
133
- try {
134
- await this.fs.unlink(lockPath);
135
- return true;
136
- }
137
- catch (error) {
138
- return isMissingFile(error);
139
- }
140
- }
141
- return false;
142
- }
143
130
  async removeTemporaryFile(path) {
144
131
  try {
145
132
  await this.fs.unlink(path);
@@ -222,13 +209,3 @@ function isMissingFile(error) {
222
209
  function isAlreadyExists(error) {
223
210
  return typeof error === "object" && error !== null && error.code === "EEXIST";
224
211
  }
225
- function isProcessDead(pid) {
226
- try {
227
- process.kill(pid, 0);
228
- return false;
229
- }
230
- catch (error) {
231
- const code = error.code;
232
- return code !== "EPERM";
233
- }
234
- }
@@ -1,4 +1,4 @@
1
- export class TransactionStore {
1
+ export class InMemoryTransactionStore {
2
2
  transactions = new Map();
3
3
  set(transaction) {
4
4
  this.transactions.set(transaction.id, transaction);
@@ -156,7 +156,7 @@ export function withCapabilityFamilies(capabilities, options = {}) {
156
156
  editing: editingFamily(editor, editing, options.editingBackend ?? previous?.editing?.compositeTransactions.backend ?? backend),
157
157
  native: nativeFamily(native, options.nativeBackend ?? previous?.native.selectionWrite.backend ?? backend),
158
158
  publishing: {
159
- projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, "verified", "new project publishing is unavailable"),
159
+ projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, options.publishingGuarantee ?? "verified", "new project publishing is unavailable"),
160
160
  },
161
161
  export: {
162
162
  timeline: exportDescriptor(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable", "headed-native"),
@@ -16,7 +16,9 @@ export class ContextEngine {
16
16
  return enriched;
17
17
  }
18
18
  async changesSince(revision) {
19
- const capabilities = await this.editor.getCapabilities();
19
+ const capabilities = await this.editor.getCapabilities({ probeCanonicalSnapshot: false });
20
+ if (requiresHeadedCanonicalRead(capabilities))
21
+ throw new Error("CAPABILITY_UNAVAILABLE: canonical timeline changes require an explicitly authorized headed read");
20
22
  if (capabilities.editor.incrementalChanges) {
21
23
  const incremental = await this.editor.readChanges?.(revision);
22
24
  if (incremental?.timeline)
@@ -32,8 +34,9 @@ export class ContextEngine {
32
34
  }
33
35
  async timelineChangesSince(request) {
34
36
  const identity = await this.editor.getIdentity();
35
- const capabilities = await this.editor.getCapabilities();
36
- const canonical = capabilities.editor.canonicalTimelineMode !== "metadata-only"
37
+ const capabilities = await this.editor.getCapabilities({ probeCanonicalSnapshot: false });
38
+ const canonical = !requiresHeadedCanonicalRead(capabilities)
39
+ && capabilities.editor.canonicalTimelineMode !== "metadata-only"
37
40
  && (capabilities.editor.timelineSnapshotRead || capabilities.editor.incrementalChanges);
38
41
  const source = {
39
42
  source: identity.name,
@@ -143,20 +146,20 @@ export class ContextEngine {
143
146
  if (cursor?.target)
144
147
  await this.validateCursorTarget(revision, cursor.target);
145
148
  const identity = await this.editor.getIdentity();
146
- const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(await this.editor.getCapabilities(), {
149
+ const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(await this.editor.getCapabilities({ probeCanonicalSnapshot: false }), {
147
150
  backend: identity.backend,
148
151
  }));
149
- const incremental = capabilities.editor.incrementalChanges
152
+ const incremental = capabilities.editor.incrementalChanges && !requiresHeadedCanonicalRead(capabilities)
150
153
  ? await this.editor.readChanges?.(revision)
151
154
  : undefined;
152
- const timeline = canonicalTimelineAvailable(capabilities)
155
+ const timeline = canonicalTimelineAvailable(capabilities) && !requiresHeadedCanonicalRead(capabilities)
153
156
  ? incremental?.timeline ?? await this.optionalTimelineChanges(revision)
154
157
  : undefined;
155
158
  const stateChanges = [
156
159
  ...(incremental?.stateChanges ?? []),
157
160
  ...(await this.liveChangesSince(revision, waitMs)),
158
161
  ];
159
- const assetChanges = canonicalTimelineAvailable(capabilities)
162
+ const assetChanges = canonicalTimelineAvailable(capabilities) && !requiresHeadedCanonicalRead(capabilities)
160
163
  ? incremental?.assetChanges ?? []
161
164
  : [];
162
165
  // Canonical timeline revisions and live metadata revisions may come from
@@ -204,9 +207,9 @@ export class ContextEngine {
204
207
  throw new Error(`TARGET_MISMATCH: cursor target ${formatContextTarget(target)} does not match the active target`);
205
208
  }
206
209
  }
207
- async inspectContext(capabilities) {
210
+ async inspectContext(capabilities, options = {}) {
208
211
  const identity = await this.editor.getIdentity();
209
- const project = canonicalTimelineAvailable(capabilities)
212
+ const project = options.includeCanonicalSnapshot !== false && canonicalTimelineAvailable(capabilities)
210
213
  ? await this.inspectProject()
211
214
  : undefined;
212
215
  const editorState = await this.optionalLiveState();
@@ -216,7 +219,7 @@ export class ContextEngine {
216
219
  const target = contextTarget(project, editorState ? [
217
220
  { kind: "active-sequence-changed", revision: editorState.revision, state: editorState },
218
221
  ] : []);
219
- const provenance = primaryContextProvenance(identity.backend, capabilities, target);
222
+ const provenance = primaryContextProvenance(identity.backend, capabilities, target, Boolean(project));
220
223
  const cursor = { revision, ...(target ? { target } : {}) };
221
224
  return {
222
225
  revision,
@@ -287,8 +290,8 @@ export class ContextEngine {
287
290
  return this.editor.listAssets(query);
288
291
  }
289
292
  async optionalTimelineChanges(revision) {
290
- const capabilities = await this.editor.getCapabilities();
291
- if (!capabilities.editor.timelineSnapshotRead)
293
+ const capabilities = await this.editor.getCapabilities({ probeCanonicalSnapshot: false });
294
+ if (!capabilities.editor.timelineSnapshotRead || requiresHeadedCanonicalRead(capabilities))
292
295
  return undefined;
293
296
  return this.changesSince(revision);
294
297
  }
@@ -343,15 +346,18 @@ export class ContextEngine {
343
346
  return next;
344
347
  }
345
348
  }
349
+ function requiresHeadedCanonicalRead(capabilities) {
350
+ return capabilities.families?.canonicalDocument.read.evidenceTier === "headed-native";
351
+ }
346
352
  function canonicalTimelineAvailable(capabilities) {
347
353
  return Boolean(capabilities.editor.projectRead
348
354
  && capabilities.editor.timelineSnapshotRead
349
355
  && capabilities.editor.canonicalTimelineMode !== "metadata-only");
350
356
  }
351
- function primaryContextProvenance(provider, capabilities, target) {
357
+ function primaryContextProvenance(provider, capabilities, target, canonicalObserved = true) {
352
358
  const artifact = capabilities.editor.timelineArtifactWrite && !capabilities.editor.timelineWrite;
353
- const canonical = capabilities.editor.canonicalTimelineMode === "canonical-read"
354
- || capabilities.editor.canonicalTimelineMode === "canonical-write";
359
+ const canonical = canonicalObserved && (capabilities.editor.canonicalTimelineMode === "canonical-read"
360
+ || capabilities.editor.canonicalTimelineMode === "canonical-write");
355
361
  const headedNative = canonical && provider.includes("native");
356
362
  const source = provider === "fixture"
357
363
  ? "deterministic-fixture"
@@ -377,7 +383,7 @@ function primaryContextProvenance(provider, capabilities, target) {
377
383
  };
378
384
  }
379
385
  function contextProvenanceSet(provider, capabilities, target, changes) {
380
- const base = primaryContextProvenance(provider, capabilities, target);
386
+ const base = primaryContextProvenance(provider, capabilities, target, !requiresHeadedCanonicalRead(capabilities));
381
387
  const result = [];
382
388
  if (changes.timeline || changes.assetChanges.length > 0)
383
389
  result.push(base);
@@ -5,8 +5,8 @@ export class ContextService {
5
5
  this.adapter = adapter;
6
6
  this.context = context;
7
7
  }
8
- async inspectContext(capabilities) {
9
- return this.context.inspectContext(capabilities);
8
+ async inspectContext(capabilities, options = {}) {
9
+ return this.context.inspectContext(capabilities, options);
10
10
  }
11
11
  async inspectLiveEditor() {
12
12
  return this.liveAdapter().readLiveState();
@@ -4,7 +4,7 @@ import { diffSnapshots } from "../timeline/snapshot-diff.js";
4
4
  import { canonicalSnapshotDigest } from "../timeline/snapshot-digest.js";
5
5
  import { assertValidMaskConfiguration } from "../domain/editing.js";
6
6
  import { sameRevision } from "../context/revision.js";
7
- import { parseRational } from "../timeline/rational-time.js";
7
+ import { addRationalTimes, parseRational } from "../timeline/rational-time.js";
8
8
  import { assertValidVerificationPolicy } from "../verification/verification.js";
9
9
  export class EditService {
10
10
  adapter;
@@ -203,7 +203,8 @@ export class EditService {
203
203
  }
204
204
  this.assertTarget(preview.target, before);
205
205
  preview.operations.forEach(assertValidWorkflowOperation);
206
- await this.assertCompositeCapabilities(preview.operations, preview.target.kind);
206
+ const executionCapabilities = (await this.adapter.getCapabilities()).editor;
207
+ await this.assertCompositeCapabilities(preview.operations, preview.target.kind, executionCapabilities);
207
208
  if (!this.adapter.applyTransaction) {
208
209
  throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction execution");
209
210
  }
@@ -243,7 +244,12 @@ export class EditService {
243
244
  verificationPolicy,
244
245
  status: "APPLIED",
245
246
  };
246
- const authorizedDiffCheck = sameDiffContent(transaction.diff, preview.expectedDiff)
247
+ const markerOperation = preview.operations.length === 1 && preview.operations[0]?.type === "add-marker"
248
+ && preview.target.kind === "editor.timeline"
249
+ && executionCapabilities.markerIdentityMode === "editor-assigned"
250
+ && executionCapabilities.semanticOperations?.["add-marker"] === true
251
+ ? preview.operations[0] : undefined;
252
+ const authorizedDiffCheck = sameDiffContent(transaction.diff, preview.expectedDiff, markerOperation?.marker.id, before.timeline.markers.map((marker) => marker.id))
247
253
  ? undefined
248
254
  : {
249
255
  name: "authorized-diff",
@@ -477,18 +483,78 @@ function postWriteAnalysisRequirements(policy) {
477
483
  visual: assertions.some((assertion) => assertion.type === "visual-content"),
478
484
  };
479
485
  }
480
- function sameDiffContent(left, right) {
486
+ function sameDiffContent(left, right, requestedMarkerId, existingMarkerIds = []) {
487
+ const actual = structuredClone(left);
488
+ const expectedMarker = right.markerChanges[0];
489
+ const actualMarker = actual.markerChanges[0];
490
+ const expectedChange = right.changes.filter((change) => change.scope === "marker");
491
+ const actualChange = actual.changes.filter((change) => change.scope === "marker");
492
+ if (requestedMarkerId && right.markerChanges.length === 1 && actual.markerChanges.length === 1
493
+ && expectedMarker?.type === "MARKER_ADDED" && actualMarker?.type === "MARKER_ADDED"
494
+ && expectedMarker.itemId === requestedMarkerId && expectedMarker.marker.id === requestedMarkerId
495
+ && expectedMarker.after?.id === requestedMarkerId && !expectedMarker.before
496
+ && actualMarker.itemId && actualMarker.marker.id === actualMarker.itemId && actualMarker.after?.id === actualMarker.itemId && !actualMarker.before
497
+ && !existingMarkerIds.includes(requestedMarkerId) && !existingMarkerIds.includes(actualMarker.itemId)
498
+ && expectedChange.length === 1 && actualChange.length === 1
499
+ && expectedChange[0]?.type === "MARKER_ADDED" && expectedChange[0].itemId === requestedMarkerId && expectedChange[0].after?.id === requestedMarkerId
500
+ && actualChange[0]?.type === "MARKER_ADDED" && actualChange[0].itemId === actualMarker.itemId && actualChange[0].after?.id === actualMarker.itemId) {
501
+ actualMarker.itemId = requestedMarkerId;
502
+ actualMarker.marker.id = requestedMarkerId;
503
+ actualMarker.after.id = requestedMarkerId;
504
+ actualChange[0].itemId = requestedMarkerId;
505
+ actualChange[0].after.id = requestedMarkerId;
506
+ }
481
507
  const comparable = (diff) => {
482
- const { from: _from, to: _to, provenance, ...content } = diff;
508
+ const normalized = structuredClone(diff);
509
+ const normalize = (value) => addRationalTimes(value, { value: "0", timescale: "1" }, "INVALID_PROJECT_STATE");
510
+ const normalizeItem = (value) => {
511
+ if (!value || typeof value !== "object" || Array.isArray(value))
512
+ return;
513
+ const item = value;
514
+ for (const key of ["startTime", "durationTime", "sourceStartTime"]) {
515
+ if (item[key] !== undefined)
516
+ item[key] = normalize(item[key]);
517
+ }
518
+ };
519
+ for (const change of [...normalized.added, ...normalized.removed, ...normalized.modified]) {
520
+ normalizeItem(change.before);
521
+ normalizeItem(change.after);
522
+ }
523
+ for (const change of [...normalized.markerChanges, ...normalized.captionChanges, ...normalized.storyElementChanges]) {
524
+ normalizeItem(change.before);
525
+ normalizeItem(change.after);
526
+ if ("marker" in change)
527
+ normalizeItem(change.marker);
528
+ if ("caption" in change)
529
+ normalizeItem(change.caption);
530
+ if ("element" in change)
531
+ normalizeItem(change.element);
532
+ }
533
+ for (const change of normalized.changes) {
534
+ if (change.scope !== "media") {
535
+ normalizeItem(change.before);
536
+ normalizeItem(change.after);
537
+ }
538
+ }
539
+ for (const range of normalized.affectedRanges)
540
+ normalizeItem(range);
541
+ normalized.durationDeltaTime = normalize(normalized.durationDeltaTime);
542
+ if (normalized.playheadChange?.before)
543
+ normalized.playheadChange.before = normalize(normalized.playheadChange.before);
544
+ if (normalized.playheadChange?.after)
545
+ normalized.playheadChange.after = normalize(normalized.playheadChange.after);
546
+ const { from: _from, to: _to, provenance, ...content } = normalized;
483
547
  return {
484
- target: provenance ? {
485
- projectId: provenance.projectId,
486
- sequenceId: provenance.sequenceId,
487
- } : undefined,
548
+ target: provenance ? { projectId: provenance.projectId, sequenceId: provenance.sequenceId } : undefined,
488
549
  ...content,
489
550
  };
490
551
  };
491
- return JSON.stringify(comparable(left)) === JSON.stringify(comparable(right));
552
+ try {
553
+ return JSON.stringify(comparable(actual)) === JSON.stringify(comparable(right));
554
+ }
555
+ catch {
556
+ return false;
557
+ }
492
558
  }
493
559
  function assertValidWorkflowOperation(operation) {
494
560
  if (operation.type === "timeline.mask.add") {
@@ -12,6 +12,7 @@ export * from "./render/render-and-verify.js";
12
12
  export * from "./timeline/drift-reconciliation.js";
13
13
  export * from "./timeline/fast-observation.js";
14
14
  export * from "./application/project-store.js";
15
+ export * from "./application/transaction-store.js";
15
16
  export * from "./application/local-media.js";
16
17
  export * from "./application/project-transactions.js";
17
18
  export * from "./application/semantic-media-index-store.js";
@@ -7,13 +7,14 @@ import { FillerRemovalService } from "./editing/filler-removal-service.js";
7
7
  import { MediaAnalysisService } from "./application/media-analysis-service.js";
8
8
  import { MusicService } from "./editing/music-service.js";
9
9
  import { ProjectService } from "./application/project-service.js";
10
- import { TransactionStore } from "./application/transaction-store.js";
10
+ import { InMemoryTransactionStore } from "./application/transaction-store.js";
11
11
  import { DurationPolicyService } from "./application/duration-policy-service.js";
12
12
  import { DialogueNormalizationService } from "./editing/dialogue-normalization-service.js";
13
13
  import { SkillRuntime } from "./skills/runtime.js";
14
14
  import { builtinSkills } from "./skills/builtin.js";
15
15
  /** Stable runtime façade exposed to the MCP server and editor adapters. */
16
16
  export class AgentVideoRuntime {
17
+ editor;
17
18
  projects;
18
19
  contexts;
19
20
  media;
@@ -24,9 +25,10 @@ export class AgentVideoRuntime {
24
25
  dialogueNormalization;
25
26
  skills;
26
27
  constructor(adapter, options = {}) {
28
+ this.editor = adapter;
27
29
  const context = new ContextEngine(adapter);
28
30
  const verificationEngine = options.verificationEngine ?? new DefaultVerificationEngine();
29
- const transactions = new TransactionStore();
31
+ const transactions = new InMemoryTransactionStore();
30
32
  this.projects = new ProjectService(adapter, context, options);
31
33
  this.contexts = new ContextService(adapter, context);
32
34
  this.media = new MediaAnalysisService(this.projects, context, options);
@@ -37,11 +39,14 @@ export class AgentVideoRuntime {
37
39
  this.durationPolicy = new DurationPolicyService();
38
40
  this.skills = new SkillRuntime(this.projects, this.media, this.edits, options);
39
41
  }
42
+ withCanonicalReadScope(operation) {
43
+ return this.editor.withCanonicalReadScope?.(operation) ?? operation();
44
+ }
40
45
  async inspectProject() {
41
- return this.projects.inspectProject();
46
+ return this.withCanonicalReadScope(() => this.projects.inspectProject());
42
47
  }
43
48
  async inspectTimeline() {
44
- return this.projects.inspectTimeline();
49
+ return this.withCanonicalReadScope(() => this.projects.inspectTimeline());
45
50
  }
46
51
  async inspectArtifact() {
47
52
  return this.projects.inspectArtifact();
@@ -66,9 +71,13 @@ export class AgentVideoRuntime {
66
71
  async inspectEditor(options = {}) {
67
72
  return this.projects.inspectEditor(options);
68
73
  }
69
- async inspectContext() {
70
- const editor = await this.inspectEditor();
71
- return this.contexts.inspectContext(editor.capabilities);
74
+ async inspectContext(options = {}) {
75
+ const inspect = async () => {
76
+ const editor = await this.inspectEditor({ ...options, probeCanonicalSnapshot: options.probeCanonicalSnapshot === true });
77
+ const headedRead = editor.capabilities.families?.canonicalDocument.read.evidenceTier === "headed-native";
78
+ return this.contexts.inspectContext(editor.capabilities, { includeCanonicalSnapshot: !headedRead || options.probeCanonicalSnapshot === true });
79
+ };
80
+ return options.probeCanonicalSnapshot === true ? this.withCanonicalReadScope(inspect) : inspect();
72
81
  }
73
82
  async inspectLiveEditor() {
74
83
  return this.contexts.inspectLiveEditor();
@@ -165,6 +174,9 @@ export class AgentVideoRuntime {
165
174
  async understandMedia(mediaId) {
166
175
  return this.media.understandMedia(mediaId);
167
176
  }
177
+ async understandMediaInProject(mediaId, project) {
178
+ return this.media.understandMediaInProject(mediaId, project);
179
+ }
168
180
  planDuration(request) {
169
181
  return this.durationPolicy.plan(request);
170
182
  }
@@ -180,6 +192,9 @@ export class AgentVideoRuntime {
180
192
  async planRoughCut(request) {
181
193
  return this.media.planRoughCut(request);
182
194
  }
195
+ async planRoughCutInProject(request, project) {
196
+ return this.media.planRoughCutInProject(request, project);
197
+ }
183
198
  async inspectTimelineSemanticContext(query = {}) {
184
199
  return this.media.inspectTimelineSemanticContext(query);
185
200
  }
@@ -182,6 +182,7 @@ export function createTimelineIrFromProjectSnapshot(snapshot, provider) {
182
182
  ...(clip.sourceStartTime ? { sourceStartTime: normalizeRationalTime(clip.sourceStartTime) } : {}),
183
183
  track: clip.track,
184
184
  ...(clip.role ? { role: clip.role } : {}),
185
+ ...(clip.nativeAudioRole ? { nativeAudioRole: clip.nativeAudioRole } : {}),
185
186
  ...(clip.mediaId ? { mediaId: clip.mediaId } : {}),
186
187
  ...(clip.gainDb !== undefined ? { gainDb: clip.gainDb } : {}),
187
188
  ...(clip.scale !== undefined || clip.position ? {
@@ -306,6 +307,12 @@ export function validateTimelineIr(timeline) {
306
307
  throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id} source range exceeds resource ${resource.id}`);
307
308
  }
308
309
  }
310
+ if (occurrence.nativeAudioRole !== undefined && (typeof occurrence.nativeAudioRole !== "string"
311
+ || !/^dialogue(?:\.[^.]+)?$/.test(occurrence.nativeAudioRole)
312
+ || occurrence.role === "music"
313
+ || occurrence.role === "title")) {
314
+ throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id}.nativeAudioRole is unsupported or inconsistent`);
315
+ }
309
316
  if (occurrence.gainDb !== undefined && !Number.isFinite(occurrence.gainDb))
310
317
  throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id}.gainDb must be finite`);
311
318
  if (occurrence.transform)
@@ -386,8 +393,13 @@ function validateMediaMetadata(metadata, field) {
386
393
  if (stream.codec !== undefined)
387
394
  requireText(stream.codec, `${streamField}.codec`);
388
395
  if (stream.kind === "video") {
389
- requirePositiveInteger(stream.width, `${streamField}.width`);
390
- requirePositiveInteger(stream.height, `${streamField}.height`);
396
+ if ((stream.width === undefined) !== (stream.height === undefined)) {
397
+ throw new Error(`TIMELINE_IR_INVALID: ${streamField}.width and height must be provided together`);
398
+ }
399
+ if (stream.width !== undefined && stream.height !== undefined) {
400
+ requirePositiveInteger(stream.width, `${streamField}.width`);
401
+ requirePositiveInteger(stream.height, `${streamField}.height`);
402
+ }
391
403
  if (!stream.frameRate)
392
404
  throw new Error(`TIMELINE_IR_INVALID: ${streamField}.frameRate is required`);
393
405
  validateRational(stream.frameRate, `${streamField}.frameRate`, true);
@@ -454,6 +466,15 @@ function applyOperation(timeline, operation) {
454
466
  canonicalizeOccurrences(timeline);
455
467
  return;
456
468
  case "split-occurrence": {
469
+ if (occurrence.fadeIn !== undefined || occurrence.fadeOut !== undefined) {
470
+ throw new Error("TIMELINE_IR_OPERATION_INVALID: splitting an occurrence with fades is unsupported");
471
+ }
472
+ if (occurrence.attachedTo || timeline.sequence.occurrences.some((item) => item.attachedTo === occurrenceId)) {
473
+ throw new Error("TIMELINE_IR_OPERATION_INVALID: splitting attached occurrences is unsupported");
474
+ }
475
+ if (timeline.sequence.storyElements.some((element) => element.occurrenceId === occurrenceId || element.attachedTo === occurrenceId)) {
476
+ throw new Error("TIMELINE_IR_OPERATION_INVALID: splitting an occurrence referenced by a story element is unsupported");
477
+ }
457
478
  requireText(operation.newOccurrenceId, "operation.newOccurrenceId");
458
479
  if (timeline.sequence.occurrences.some(({ id }) => id === operation.newOccurrenceId)) {
459
480
  throw new Error(`TIMELINE_IR_OPERATION_INVALID: occurrence already exists: ${operation.newOccurrenceId}`);
@@ -733,10 +733,10 @@ export class InMemoryEditorAdapter {
733
733
  applyRippleDelete(snapshot, timelineId, start, end) {
734
734
  if (timelineId !== snapshot.timeline.id)
735
735
  throw new Error(`TIMELINE_NOT_FOUND: ${timelineId}`);
736
- if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start) {
737
- throw new Error("INVALID_OPERATION: ripple delete range must be positive");
736
+ if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
737
+ throw new Error(`INVALID_OPERATION: ripple delete range [${start}, ${end}) must be increasing`);
738
738
  }
739
- if (end > snapshot.timeline.duration) {
739
+ if (start < 0 || end > snapshot.timeline.duration) {
740
740
  throw new Error(`INVALID_OPERATION: ripple delete range [${start}, ${end}) must fit timeline bounds [0, ${snapshot.timeline.duration})`);
741
741
  }
742
742
  const removedDuration = end - start;
@@ -1,3 +1,4 @@
1
1
  export * from "./in-memory-editor.js";
2
2
  export * from "./fixture-analyzers.js";
3
3
  export * from "./skill-fixtures.js";
4
+ export * from "./sender-lifecycle-fixture.js";