@morshoto/framekit 0.1.18 → 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 (51) hide show
  1. package/README.md +17 -12
  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 +538 -77
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  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 +22 -8
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +27 -2
  11. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  14. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +1 -0
  15. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  16. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +3 -1
  18. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  19. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +32 -14
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  21. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  22. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  23. package/dist-package/apps/cli/src/main.js +42 -0
  24. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  25. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  26. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  27. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  28. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  29. package/dist-package/apps/mcp-server/src/main.js +24 -19
  30. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  31. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  32. package/dist-package/apps/mcp-server/src/server.js +737 -152
  33. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  34. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  35. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  36. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +391 -58
  37. package/dist-package/packages/headless-application/src/index.js +1 -0
  38. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  39. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  40. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  41. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  42. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  43. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  44. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  45. package/dist-package/packages/runtime/src/index.js +1 -0
  46. package/dist-package/packages/runtime/src/runtime.js +16 -7
  47. package/dist-package/packages/runtime/src/timeline/editing-session.js +16 -0
  48. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  49. package/dist-package/packages/testkit/src/index.js +1 -0
  50. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  51. package/package.json +32 -10
@@ -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();
@@ -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)
@@ -459,6 +466,15 @@ function applyOperation(timeline, operation) {
459
466
  canonicalizeOccurrences(timeline);
460
467
  return;
461
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
+ }
462
478
  requireText(operation.newOccurrenceId, "operation.newOccurrenceId");
463
479
  if (timeline.sequence.occurrences.some(({ id }) => id === operation.newOccurrenceId)) {
464
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";