@morshoto/framekit 0.1.10 → 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +1 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
  3. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
  7. package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
  11. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  12. package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
  13. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
  14. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  15. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  16. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  18. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  19. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  20. package/dist-package/apps/mcp-server/src/main.js +36 -2
  21. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  23. package/dist-package/apps/mcp-server/src/server.js +146 -12
  24. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  25. package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
  26. package/dist-package/packages/runtime/src/index.js +2 -0
  27. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  28. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  29. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  30. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  31. package/package.json +10 -6
@@ -1,3 +1,4 @@
1
+ import { sameMediaSourceIdentity } from "../domain/media.js";
1
2
  import { planRoughCut } from "../planning/rough-cut.js";
2
3
  import { bindSpeechAnalysis } from "../speech/analysis.js";
3
4
  import { parseRational } from "../timeline/rational-time.js";
@@ -45,7 +46,22 @@ export class MediaAnalysisService {
45
46
  const sourceStart = clip.sourceStart ?? 0;
46
47
  const requestedRange = { start: sourceStart, end: sourceStart + clip.duration };
47
48
  const analysis = await this.options.audioAnalyzer.analyze({ project, media }, requestedRange);
48
- const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? clip.duration;
49
+ validateAudioProvenance(analysis, {
50
+ media,
51
+ mediaId,
52
+ project,
53
+ provider: this.options.audioAnalyzer.descriptor,
54
+ requestedRange,
55
+ });
56
+ const measuredRange = analysis.measuredRange ?? {
57
+ start: requestedRange.start,
58
+ end: requestedRange.start + (analysis.analyzedDurationSeconds ?? clip.duration),
59
+ };
60
+ validateAudioRange(measuredRange, requestedRange, "measured audio range");
61
+ const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? measuredRange.end - measuredRange.start;
62
+ if (Math.abs(analyzedDurationSeconds - (measuredRange.end - measuredRange.start)) > 0.000001) {
63
+ throw new Error("ANALYSIS_INVALID: audio measured duration does not match its measured range");
64
+ }
49
65
  const valid = analysis.valid !== false
50
66
  && Number.isFinite(analysis.integratedLufs)
51
67
  && Number.isFinite(analysis.truePeakDb)
@@ -56,12 +72,9 @@ export class MediaAnalysisService {
56
72
  mediaId,
57
73
  occurrenceId,
58
74
  requestedRange,
59
- measuredRange: {
60
- start: 0,
61
- end: Number.isFinite(analyzedDurationSeconds) ? analyzedDurationSeconds : clip.duration,
62
- },
75
+ measuredRange,
63
76
  revision: project.revision,
64
- provider: this.options.audioAnalyzer.descriptor ?? { id: "framekit.audio", provider: "unknown" },
77
+ provider: analysis.provider ?? this.options.audioAnalyzer.descriptor ?? { id: "framekit.audio", provider: "unknown" },
65
78
  dialoguePresent: analysis.dialoguePresent
66
79
  ?? Boolean(media.speech?.words.some((word) => word.filler !== true)),
67
80
  integratedLufs: analysis.integratedLufs,
@@ -470,3 +483,36 @@ function findMedia(project, mediaId) {
470
483
  throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
471
484
  return media;
472
485
  }
486
+ function validateAudioProvenance(analysis, expected) {
487
+ if (analysis.schemaVersion !== undefined && analysis.schemaVersion !== 1) {
488
+ throw new Error("ANALYSIS_INVALID: unsupported audio analysis schema version");
489
+ }
490
+ if (analysis.mediaId !== undefined && analysis.mediaId !== expected.mediaId) {
491
+ throw new Error("TARGET_MISMATCH: audio analysis media identity does not match the requested media");
492
+ }
493
+ if (analysis.sourceIdentity !== undefined
494
+ && !sameMediaSourceIdentity(analysis.sourceIdentity, sourceIdentityOf(expected.media))) {
495
+ throw new Error("TARGET_MISMATCH: audio analysis source identity does not match the requested media");
496
+ }
497
+ if (analysis.requestedRange !== undefined && !sameRange(analysis.requestedRange, expected.requestedRange)) {
498
+ throw new Error("ANALYSIS_INVALID: audio requested range does not match the runtime request");
499
+ }
500
+ if (analysis.revision !== undefined
501
+ && (analysis.revision.id !== expected.project.revision.id || analysis.revision.sequence !== expected.project.revision.sequence)) {
502
+ throw new Error("ANALYSIS_STALE: audio analysis revision does not match the inspected project");
503
+ }
504
+ if (analysis.provider !== undefined && expected.provider !== undefined
505
+ && !sameDescriptor(analysis.provider, expected.provider)) {
506
+ throw new Error("ANALYSIS_INVALID: audio provider identity does not match the configured analyzer");
507
+ }
508
+ }
509
+ function validateAudioRange(range, requested, label) {
510
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end)
511
+ || range.start < requested.start || range.end > requested.end || range.end <= range.start) {
512
+ throw new Error(`ANALYSIS_INVALID: ${label} must fit inside the requested occurrence range`);
513
+ }
514
+ }
515
+ function sameRange(left, right) {
516
+ return Math.abs(left.start - right.start) <= 0.000001
517
+ && Math.abs(left.end - right.end) <= 0.000001;
518
+ }
@@ -17,11 +17,21 @@ export function reconcileProjectCatalog(catalog, options) {
17
17
  const sequence = state?.sequence && projectDescriptor
18
18
  ? matchIdentity(projectDescriptor.sequences, state.sequence.id, state.sequence.name, (candidate) => candidate.id, (candidate) => candidate.name)
19
19
  : unresolvedIdentity(state?.sequence?.id);
20
+ const diagnostics = [
21
+ identityDiagnostic("project", project, state?.project?.name),
22
+ ...(state?.sequence && projectDescriptor
23
+ ? [identityDiagnostic("sequence", sequence, state.sequence.name)]
24
+ : []),
25
+ ].filter((diagnostic) => diagnostic !== undefined);
20
26
  let status = project.method === "stable-id"
21
27
  && sequence.method === "stable-id"
22
28
  ? "matched"
23
29
  : "unresolved";
24
- let reason = status === "unresolved" ? "stable project and sequence IDs could not be reconciled" : undefined;
30
+ let reason = diagnostics.length > 0
31
+ ? diagnostics.map(formatDiagnostic).join("; ")
32
+ : status === "unresolved"
33
+ ? "stable project and sequence IDs could not be reconciled"
34
+ : undefined;
25
35
  if (status === "matched"
26
36
  && ((catalog.activeProjectId !== undefined && catalog.activeProjectId !== project.catalogId)
27
37
  || (catalog.activeSequenceId !== undefined && catalog.activeSequenceId !== sequence.catalogId))) {
@@ -61,6 +71,7 @@ export function reconcileProjectCatalog(catalog, options) {
61
71
  sequence,
62
72
  ...(beforeRevision ? { beforeRevision: { ...beforeRevision } } : {}),
63
73
  ...(afterRevision ? { afterRevision: { ...afterRevision } } : {}),
74
+ ...(diagnostics.length > 0 ? { diagnostics } : {}),
64
75
  ...(reason ? { reason } : {}),
65
76
  },
66
77
  selection: { ...options.provenance.selection },
@@ -74,6 +85,13 @@ function matchIdentity(values, liveId, liveName, id, name) {
74
85
  const named = values.filter((value) => name(value) === liveName);
75
86
  if (named.length === 1)
76
87
  return { method: "name-only", catalogId: id(named[0]), liveId };
88
+ if (named.length > 1) {
89
+ return {
90
+ method: "ambiguous-name",
91
+ liveId,
92
+ candidateCatalogIds: named.map((value) => id(value)),
93
+ };
94
+ }
77
95
  return unresolvedIdentity(liveId);
78
96
  }
79
97
  function unresolvedIdentity(liveId) {
@@ -86,6 +104,33 @@ function sameTarget(left, right) {
86
104
  function sameRevision(left, right) {
87
105
  return left.id === right.id && left.sequence === right.sequence;
88
106
  }
107
+ function identityDiagnostic(scope, match, liveName) {
108
+ if (match.method === "stable-id")
109
+ return undefined;
110
+ const diagnostic = {
111
+ scope,
112
+ code: match.method === "ambiguous-name"
113
+ ? "ambiguous-name"
114
+ : match.liveId
115
+ ? "stable-id-mismatch"
116
+ : "identity-unresolved",
117
+ ...(match.liveId ? { liveId: match.liveId } : {}),
118
+ ...(liveName ? { liveName } : {}),
119
+ ...(match.catalogId ? { catalogId: match.catalogId } : {}),
120
+ ...(match.candidateCatalogIds ? { candidateCatalogIds: [...match.candidateCatalogIds] } : {}),
121
+ };
122
+ return diagnostic;
123
+ }
124
+ function formatDiagnostic(diagnostic) {
125
+ const label = diagnostic.scope;
126
+ if (diagnostic.code === "ambiguous-name") {
127
+ return `${label} name is ambiguous across catalog IDs ${diagnostic.candidateCatalogIds?.join(", ") ?? "<none>"}`;
128
+ }
129
+ if (diagnostic.code === "stable-id-mismatch") {
130
+ return `${label} stable ID ${diagnostic.liveId ?? "<unavailable>"} did not match catalog ID ${diagnostic.catalogId ?? "<none>"}; name-only evidence is not canonical`;
131
+ }
132
+ return `${label} stable identity is unavailable for reconciliation`;
133
+ }
89
134
  export function validateProjectCatalog(catalog) {
90
135
  if (!Array.isArray(catalog.projects))
91
136
  throw new Error("PROJECT_CATALOG_INVALID: projects must be an array");
@@ -6,6 +6,8 @@ export * from "./editing/intent.js";
6
6
  export * from "./editing/duration-policy.js";
7
7
  export * from "./capabilities.js";
8
8
  export * from "./timeline/snapshot-digest.js";
9
+ export * from "./timeline/editing-session.js";
10
+ export * from "./timeline/drift-reconciliation.js";
9
11
  export * from "./context/project-catalog.js";
10
12
  export * from "./speech/filler-removal.js";
11
13
  export * from "./audio/dialogue-normalization.js";
@@ -1,3 +1,4 @@
1
+ import { sameRevision } from "../context/revision.js";
1
2
  import { FillerDetector } from "../speech/filler-detector.js";
2
3
  import { SafeCutResolver } from "../speech/safe-cut-resolver.js";
3
4
  import { DIALOGUE_NORMALIZATION_DEFAULTS, planDialogueGain, } from "../audio/dialogue-normalization.js";
@@ -75,6 +76,7 @@ async function planFillerSkill(context, input) {
75
76
  const candidates = [];
76
77
  const decisions = [];
77
78
  const operations = [];
79
+ const analysisProvenance = [];
78
80
  for (const clip of context.project.timeline.clips.filter((candidate) => Boolean(candidate.mediaId)
79
81
  && candidate.start < selectedRange.end
80
82
  && candidate.start + candidate.duration > selectedRange.start)) {
@@ -91,6 +93,13 @@ async function planFillerSkill(context, input) {
91
93
  end: sourceStart + localRange.end,
92
94
  };
93
95
  const speech = await context.analyzeSpeech(mediaId, sourceRange);
96
+ analysisProvenance.push({
97
+ mediaId,
98
+ occurrenceId: clip.id,
99
+ sourceRange: structuredClone(sourceRange),
100
+ revision: structuredClone(speech.revision ?? context.baseRevision),
101
+ provider: structuredClone(speech.provider ?? { id: "framekit.speech", provider: "unknown" }),
102
+ });
94
103
  const occurrence = {
95
104
  occurrenceId: clip.id,
96
105
  mediaId,
@@ -139,6 +148,7 @@ async function planFillerSkill(context, input) {
139
148
  range: structuredClone(selectedRange),
140
149
  candidates: structuredClone(candidates),
141
150
  decisions: structuredClone(decisions),
151
+ analysisProvenance: structuredClone(analysisProvenance),
142
152
  selectedCandidateIds: [...selectedCandidateIds],
143
153
  candidateProvenance: operations.map((operation, operationIndex) => ({
144
154
  candidateId: operation.candidateId,
@@ -398,6 +408,7 @@ function dialogueNormalizationSkill() {
398
408
  handler: {
399
409
  normalize: (input) => ({ ...DIALOGUE_NORMALIZATION_DEFAULTS, ...input }),
400
410
  plan: async (context, input) => planDialogueSkill(context, input),
411
+ verify: (context) => verifyDialogueSkill(context),
401
412
  },
402
413
  };
403
414
  }
@@ -578,14 +589,6 @@ async function planDialogueSkill(context, input) {
578
589
  const targetGainDb = Number((existingGainDb + plan.clampedGainDb).toFixed(6));
579
590
  const verification = plan.decision === "APPLY" ? {
580
591
  requireExpectedChange: true,
581
- maxTruePeakDb: request.maxTruePeakDb,
582
- assertions: [{
583
- type: "audio-loudness",
584
- mediaId: request.mediaId,
585
- occurrenceId: request.occurrenceId,
586
- targetLufs: request.targetLufs,
587
- toleranceDb: request.toleranceDb,
588
- }],
589
592
  } : undefined;
590
593
  return {
591
594
  operations: plan.decision === "APPLY" ? [{
@@ -612,3 +615,91 @@ async function planDialogueSkill(context, input) {
612
615
  },
613
616
  };
614
617
  }
618
+ async function verifyDialogueSkill(context) {
619
+ const details = context.plan.details;
620
+ const mediaId = typeof details?.mediaId === "string" ? details.mediaId : undefined;
621
+ const occurrenceId = typeof details?.occurrenceId === "string" ? details.occurrenceId : undefined;
622
+ const input = context.plan.normalizedInput;
623
+ if (!mediaId || !occurrenceId || !context.measureAudio) {
624
+ return [{
625
+ name: "dialogue-measurement",
626
+ passed: false,
627
+ status: "unavailable",
628
+ reason: "AUDIO_MEASUREMENT_UNAVAILABLE",
629
+ detail: "selected dialogue occurrence cannot be measured after the write",
630
+ }];
631
+ }
632
+ let measurement;
633
+ try {
634
+ measurement = await context.measureAudio(mediaId, occurrenceId);
635
+ }
636
+ catch (error) {
637
+ return [{
638
+ name: "dialogue-measurement",
639
+ passed: false,
640
+ status: "failed",
641
+ reason: "POST_WRITE_MEASUREMENT_FAILED",
642
+ detail: String(error),
643
+ }];
644
+ }
645
+ const occurrence = context.transaction.attemptedAfter.timeline.clips.find((clip) => clip.id === occurrenceId);
646
+ const expectedRange = occurrence
647
+ ? { start: occurrence.sourceStart ?? 0, end: (occurrence.sourceStart ?? 0) + occurrence.duration }
648
+ : undefined;
649
+ const targetBound = measurement.mediaId === mediaId
650
+ && measurement.occurrenceId === occurrenceId
651
+ && sameRevision(measurement.revision, context.transaction.attemptedAfter.revision)
652
+ && Boolean(expectedRange
653
+ && sameRange(measurement.requestedRange, expectedRange)
654
+ && sameRange(measurement.measuredRange, expectedRange))
655
+ && Boolean(measurement.provider?.id && measurement.provider.provider);
656
+ const measurementPassed = measurement.valid && targetBound;
657
+ const measurementCheck = {
658
+ name: "dialogue-measurement",
659
+ passed: measurementPassed,
660
+ status: measurementPassed ? "passed" : "failed",
661
+ expected: {
662
+ mediaId,
663
+ occurrenceId,
664
+ revision: context.transaction.attemptedAfter.revision,
665
+ requestedRange: expectedRange,
666
+ },
667
+ observed: measurement,
668
+ ...(measurementPassed ? {} : { reason: measurement.valid ? "MEASUREMENT_TARGET_MISMATCH" : "MEASUREMENT_INVALID" }),
669
+ detail: measurementPassed
670
+ ? "post-write dialogue measurement is valid and bound to the selected occurrence"
671
+ : "post-write dialogue measurement is invalid or not bound to the selected occurrence",
672
+ };
673
+ const loudnessPassed = measurementPassed
674
+ && Math.abs(measurement.integratedLufs - input.targetLufs) <= input.toleranceDb;
675
+ const peakPassed = measurementPassed && measurement.truePeakDb <= input.maxTruePeakDb;
676
+ return [
677
+ measurementCheck,
678
+ {
679
+ name: "dialogue-loudness",
680
+ passed: loudnessPassed,
681
+ status: loudnessPassed ? "passed" : "failed",
682
+ expected: { targetLufs: input.targetLufs, toleranceDb: input.toleranceDb },
683
+ observed: { integratedLufs: measurement.integratedLufs },
684
+ ...(loudnessPassed ? {} : { reason: "AUDIO_LOUDNESS_OUT_OF_RANGE" }),
685
+ detail: loudnessPassed
686
+ ? "post-write loudness is inside the configured tolerance"
687
+ : "post-write loudness is outside the configured tolerance",
688
+ },
689
+ {
690
+ name: "dialogue-true-peak",
691
+ passed: peakPassed,
692
+ status: peakPassed ? "passed" : "failed",
693
+ expected: { maxTruePeakDb: input.maxTruePeakDb },
694
+ observed: { truePeakDb: measurement.truePeakDb },
695
+ ...(peakPassed ? {} : { reason: "AUDIO_TRUE_PEAK_OUT_OF_RANGE" }),
696
+ detail: peakPassed
697
+ ? "post-write true peak is within the configured limit"
698
+ : "post-write true peak exceeds the configured limit",
699
+ },
700
+ ];
701
+ }
702
+ function sameRange(left, right) {
703
+ return Math.abs(left.start - right.start) <= 0.000001
704
+ && Math.abs(left.end - right.end) <= 0.000001;
705
+ }
@@ -139,6 +139,7 @@ export class SkillRuntime {
139
139
  plan: session.preview.plan,
140
140
  ...(session.preview.expectedDiff ? { expectedDiff: session.preview.expectedDiff } : {}),
141
141
  transaction,
142
+ measureAudio: (mediaId, occurrenceId) => this.analysis.measureAudio(mediaId, occurrenceId),
142
143
  });
143
144
  verification = {
144
145
  passed: Boolean(verification?.passed) && checks.every((check) => check.passed),
@@ -0,0 +1,295 @@
1
+ import { createHash } from "node:crypto";
2
+ import { validateTimelineIr } from "./editing-session.js";
3
+ /**
4
+ * Three-way merge for the provider-neutral timeline. BASE is never written;
5
+ * OURS is the agent's desired state and THEIRS is the latest provider state.
6
+ */
7
+ export function reconcileTimelineIr(input) {
8
+ const { base, ours, theirs } = input;
9
+ const providerRevisionChanged = !sameRevision(base.revision, theirs.revision);
10
+ const common = {
11
+ providerRevisionChanged,
12
+ baseRevision: structuredClone(base.revision),
13
+ oursRevision: structuredClone(ours.revision),
14
+ theirsRevision: structuredClone(theirs.revision),
15
+ };
16
+ for (const [source, timeline] of [["base", base], ["ours", ours], ["theirs", theirs]]) {
17
+ try {
18
+ validateTimelineIr(timeline);
19
+ }
20
+ catch (error) {
21
+ return { status: "conflicted", ...common, conflicts: [validationConflict(source, timeline, error)] };
22
+ }
23
+ }
24
+ const conflicts = [];
25
+ if (base.project.id !== ours.project.id || base.project.id !== theirs.project.id
26
+ || base.sequence.id !== ours.sequence.id || base.sequence.id !== theirs.sequence.id) {
27
+ conflicts.push({
28
+ kind: "ambiguous-identity",
29
+ entity: "sequence",
30
+ id: base.sequence.id,
31
+ path: "project/sequence",
32
+ baseValue: `${base.project.id}/${base.sequence.id}`,
33
+ oursValue: `${ours.project.id}/${ours.sequence.id}`,
34
+ theirsValue: `${theirs.project.id}/${theirs.sequence.id}`,
35
+ message: "BASE, OURS, and THEIRS do not address the same project and sequence",
36
+ });
37
+ return { status: "conflicted", ...common, conflicts };
38
+ }
39
+ const project = mergeRecord("project", "project", "project", base.project, ours.project, theirs.project, conflicts);
40
+ const baseSequence = sequenceMetadata(base);
41
+ const oursSequence = sequenceMetadata(ours);
42
+ const theirsSequence = sequenceMetadata(theirs);
43
+ const sequence = mergeRecord("sequence", base.sequence.id, "sequence", baseSequence, oursSequence, theirsSequence, conflicts);
44
+ const resources = mergeCollection("resource", "resources", base.resources, ours.resources, theirs.resources, conflicts);
45
+ const occurrences = mergeCollection("occurrence", "sequence.occurrences", base.sequence.occurrences, ours.sequence.occurrences, theirs.sequence.occurrences, conflicts);
46
+ const storyElements = mergeCollection("story-element", "sequence.storyElements", base.sequence.storyElements, ours.sequence.storyElements, theirs.sequence.storyElements, conflicts);
47
+ const markers = mergeCollection("marker", "sequence.markers", base.sequence.markers, ours.sequence.markers, theirs.sequence.markers, conflicts);
48
+ const captions = mergeCollection("caption", "sequence.captions", base.sequence.captions, ours.sequence.captions, theirs.sequence.captions, conflicts);
49
+ if (conflicts.length > 0 || !project || !sequence)
50
+ return { status: "conflicted", ...common, conflicts };
51
+ const merged = {
52
+ schemaVersion: 1,
53
+ project: project,
54
+ sequence: {
55
+ ...sequence,
56
+ occurrences: occurrences,
57
+ storyElements: storyElements,
58
+ markers: markers,
59
+ captions: captions,
60
+ },
61
+ resources: resources,
62
+ revision: structuredClone(theirs.revision),
63
+ };
64
+ try {
65
+ validateTimelineIr(merged);
66
+ }
67
+ catch (error) {
68
+ return { status: "conflicted", ...common, conflicts: [validationConflict("merged", merged, error)] };
69
+ }
70
+ return { status: "rebased", ...common, merged, conflicts: [] };
71
+ }
72
+ function sequenceMetadata(timeline) {
73
+ const { occurrences: _occurrences, storyElements: _storyElements, markers: _markers, captions: _captions, ...metadata } = timeline.sequence;
74
+ return metadata;
75
+ }
76
+ function mergeCollection(entity, path, base, ours, theirs, conflicts) {
77
+ const baseMap = uniqueEntityMap(entity, base, conflicts);
78
+ const oursMap = uniqueEntityMap(entity, ours, conflicts);
79
+ const theirsMap = uniqueEntityMap(entity, theirs, conflicts);
80
+ if (!baseMap || !oursMap || !theirsMap)
81
+ return undefined;
82
+ const ids = [...new Set([
83
+ ...base.map(({ id }) => id),
84
+ ...[...oursMap.keys()].filter((id) => !baseMap.has(id)),
85
+ ...[...theirsMap.keys()].filter((id) => !baseMap.has(id)),
86
+ ])];
87
+ const additions = ids.filter((id) => !baseMap.has(id)).sort((left, right) => left.localeCompare(right));
88
+ const orderedIds = [...base.map(({ id }) => id), ...additions];
89
+ const merged = [];
90
+ for (const id of orderedIds) {
91
+ const value = mergeEntity(entity, `${path}[${id}]`, id, baseMap.get(id), oursMap.get(id), theirsMap.get(id), conflicts);
92
+ if (value)
93
+ merged.push(value);
94
+ }
95
+ return merged;
96
+ }
97
+ function mergeEntity(entity, path, id, base, ours, theirs, conflicts) {
98
+ if (!base) {
99
+ if (!ours)
100
+ return structuredClone(theirs);
101
+ if (!theirs)
102
+ return structuredClone(ours);
103
+ if (deepEqual(ours, theirs))
104
+ return structuredClone(ours);
105
+ conflicts.push({ kind: "insert-conflict", entity, id, path, oursValue: ours, theirsValue: theirs, message: `both sides inserted different values for ${entity} ${id}` });
106
+ return undefined;
107
+ }
108
+ if (!ours && !theirs)
109
+ return undefined;
110
+ if (!ours) {
111
+ if (deepEqual(theirs, base))
112
+ return undefined;
113
+ conflicts.push({ kind: "delete-modify-conflict", entity, id, path, baseValue: base, theirsValue: theirs, message: `agent deleted ${entity} ${id} while provider modified it` });
114
+ return undefined;
115
+ }
116
+ if (!theirs) {
117
+ if (deepEqual(ours, base))
118
+ return undefined;
119
+ conflicts.push({ kind: "delete-modify-conflict", entity, id, path, baseValue: base, oursValue: ours, message: `provider deleted ${entity} ${id} while agent modified it` });
120
+ return undefined;
121
+ }
122
+ return mergeRecord(entity, id, path, base, ours, theirs, conflicts);
123
+ }
124
+ function mergeRecord(entity, id, path, base, ours, theirs, conflicts) {
125
+ const merged = {};
126
+ for (const key of [...new Set([...Object.keys(base), ...Object.keys(ours), ...Object.keys(theirs)])].sort()) {
127
+ const value = mergeValue(entity, id, `${path}.${key}`, base[key], ours[key], theirs[key], conflicts);
128
+ if (value !== undefined)
129
+ merged[key] = value;
130
+ }
131
+ return conflicts.some((conflict) => conflict.id === id && conflict.path.startsWith(path)) ? undefined : merged;
132
+ }
133
+ function mergeValue(entity, id, path, base, ours, theirs, conflicts) {
134
+ if (deepEqual(ours, base))
135
+ return structuredClone(theirs);
136
+ if (deepEqual(theirs, base))
137
+ return structuredClone(ours);
138
+ if (deepEqual(ours, theirs))
139
+ return structuredClone(ours);
140
+ if (isRecord(base) && isRecord(ours) && isRecord(theirs))
141
+ return mergeRecord(entity, id, path, base, ours, theirs, conflicts);
142
+ conflicts.push({ kind: "property-conflict", entity, id, path, baseValue: base, oursValue: ours, theirsValue: theirs, message: `both sides changed ${path}` });
143
+ return undefined;
144
+ }
145
+ function uniqueEntityMap(entity, values, conflicts) {
146
+ const result = new Map();
147
+ for (const value of values) {
148
+ if (result.has(value.id)) {
149
+ conflicts.push({ kind: "ambiguous-identity", entity, id: value.id, path: entity, message: `duplicate ${entity} identity ${value.id}` });
150
+ return undefined;
151
+ }
152
+ result.set(value.id, value);
153
+ }
154
+ return result;
155
+ }
156
+ function sameRevision(left, right) {
157
+ return left.id === right.id && left.sequence === right.sequence;
158
+ }
159
+ function validationConflict(source, timeline, error) {
160
+ const message = error instanceof Error ? error.message : String(error);
161
+ const detail = message.replace(/^TIMELINE_IR_INVALID:\s*/, "");
162
+ const duplicate = detail.match(/^duplicate (resource|occurrence|story element|marker|caption) id (.+)$/i);
163
+ if (duplicate) {
164
+ const entity = entityForLabel(duplicate[1]);
165
+ return {
166
+ kind: "ambiguous-identity",
167
+ entity,
168
+ id: duplicate[2],
169
+ path: collectionPath(entity),
170
+ message: `${source} timeline validation failed: ${detail}`,
171
+ };
172
+ }
173
+ const location = validationLocation(detail, timeline);
174
+ return {
175
+ kind: "invalid-state",
176
+ ...location,
177
+ message: `${source} timeline validation failed: ${detail}`,
178
+ };
179
+ }
180
+ function validationLocation(detail, timeline) {
181
+ const topLevelField = detail.match(/^(project|sequence)\.(.+)$/);
182
+ if (topLevelField) {
183
+ const entity = entityForLabel(topLevelField[1]);
184
+ return { entity, id: timelineEntityId(timeline, entity), path: topLevelField[0] };
185
+ }
186
+ if (detail === "project is required")
187
+ return { entity: "project", id: "unknown", path: "project" };
188
+ if (detail === "sequence is required")
189
+ return { entity: "sequence", id: "unknown", path: "sequence" };
190
+ const entityField = parseEntityField(detail);
191
+ if (entityField) {
192
+ const entity = entityForLabel(entityField.label);
193
+ return { entity, id: entityField.id, path: `${collectionPath(entity)}[${entityField.id}].${entityField.field}` };
194
+ }
195
+ const unsupportedMediaKind = detail.match(/^resource (.+) has unsupported mediaKind$/);
196
+ if (unsupportedMediaKind)
197
+ return { entity: "resource", id: unsupportedMediaKind[1], path: `resources[${unsupportedMediaKind[1]}].mediaKind` };
198
+ const occurrenceReference = parseOccurrenceReference(detail);
199
+ if (occurrenceReference) {
200
+ const field = occurrenceReference.kind === "resource" ? "mediaId" : "attachedTo";
201
+ return { entity: "occurrence", id: occurrenceReference.id, path: `sequence.occurrences[${occurrenceReference.id}].${field}` };
202
+ }
203
+ const storyReference = detail.match(/^story element (.+) references unknown occurrence$/);
204
+ if (storyReference)
205
+ return { entity: "story-element", id: storyReference[1], path: `sequence.storyElements[${storyReference[1]}].occurrenceId` };
206
+ const collection = detail.match(/^(resources|occurrences|storyElements|markers|captions) must be an array$/);
207
+ if (collection) {
208
+ const entity = entityForCollection(collection[1]);
209
+ return { entity, id: "unknown", path: collection[1] };
210
+ }
211
+ if (detail.startsWith("revision."))
212
+ return { entity: "sequence", id: timelineEntityId(timeline, "sequence"), path: detail };
213
+ return { entity: "sequence", id: timelineEntityId(timeline, "sequence"), path: "timeline" };
214
+ }
215
+ function parseEntityField(detail) {
216
+ for (const label of ["resource", "occurrence", "story element", "marker", "caption"]) {
217
+ const prefix = `${label} `;
218
+ if (!detail.startsWith(prefix))
219
+ continue;
220
+ const remainder = detail.slice(prefix.length);
221
+ const separator = remainder.lastIndexOf(".");
222
+ if (separator <= 0 || separator === remainder.length - 1)
223
+ continue;
224
+ const fieldEnd = remainder.indexOf(" ", separator + 1);
225
+ const field = remainder.slice(separator + 1, fieldEnd === -1 ? remainder.length : fieldEnd);
226
+ if (!field)
227
+ continue;
228
+ return { label, id: remainder.slice(0, separator), field };
229
+ }
230
+ return undefined;
231
+ }
232
+ function parseOccurrenceReference(detail) {
233
+ const prefix = "occurrence ";
234
+ const marker = " references unknown ";
235
+ if (!detail.startsWith(prefix))
236
+ return undefined;
237
+ const remainder = detail.slice(prefix.length);
238
+ const separator = remainder.lastIndexOf(marker);
239
+ if (separator <= 0)
240
+ return undefined;
241
+ const target = remainder.slice(separator + marker.length);
242
+ const targetEnd = target.indexOf(" ");
243
+ const kind = target.slice(0, targetEnd === -1 ? target.length : targetEnd);
244
+ if (kind !== "resource" && kind !== "attachment")
245
+ return undefined;
246
+ return { id: remainder.slice(0, separator), kind };
247
+ }
248
+ function entityForLabel(label) {
249
+ return label === "story element" ? "story-element" : label;
250
+ }
251
+ function entityForCollection(collection) {
252
+ switch (collection) {
253
+ case "resources": return "resource";
254
+ case "occurrences": return "occurrence";
255
+ case "storyElements": return "story-element";
256
+ case "markers": return "marker";
257
+ case "captions": return "caption";
258
+ default: return "sequence";
259
+ }
260
+ }
261
+ function collectionPath(entity) {
262
+ switch (entity) {
263
+ case "resource": return "resources";
264
+ case "occurrence": return "sequence.occurrences";
265
+ case "story-element": return "sequence.storyElements";
266
+ case "marker": return "sequence.markers";
267
+ case "caption": return "sequence.captions";
268
+ case "project": return "project";
269
+ case "sequence": return "sequence";
270
+ }
271
+ }
272
+ function timelineEntityId(timeline, entity) {
273
+ if (entity === "project")
274
+ return typeof timeline?.project?.id === "string" ? timeline.project.id : "unknown";
275
+ return typeof timeline?.sequence?.id === "string" ? timeline.sequence.id : "unknown";
276
+ }
277
+ function deepEqual(left, right) {
278
+ return stableJson(left) === stableJson(right);
279
+ }
280
+ function stableJson(value) {
281
+ if (value === null || typeof value !== "object")
282
+ return JSON.stringify(value);
283
+ if (Array.isArray(value))
284
+ return `[${value.map(stableJson).join(",")}]`;
285
+ const entries = Object.entries(value).filter(([, child]) => child !== undefined).sort(([left], [right]) => left.localeCompare(right));
286
+ return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
287
+ }
288
+ export function timelineIrContentDigest(timeline) {
289
+ const content = structuredClone(timeline);
290
+ delete content.revision;
291
+ return createHash("sha256").update(stableJson(content)).digest("hex");
292
+ }
293
+ function isRecord(value) {
294
+ return value !== null && typeof value === "object" && !Array.isArray(value);
295
+ }