@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.
- package/README.md +1 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
- package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
- package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
- package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
- package/dist-package/apps/mcp-server/src/main.js +36 -2
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
- package/dist-package/apps/mcp-server/src/routing.js +17 -0
- package/dist-package/apps/mcp-server/src/server.js +146 -12
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
- package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
- package/dist-package/packages/runtime/src/index.js +2 -0
- package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
- package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
- 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
|
-
|
|
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 =
|
|
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
|
+
}
|