@morshoto/framekit 0.1.6 → 0.1.10

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 (33) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +157 -35
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +3 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +4 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +26 -7
  17. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  18. package/dist-package/apps/mcp-server/src/server.js +532 -97
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  23. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  24. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  25. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  26. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  28. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  29. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  30. package/dist-package/packages/runtime/src/index.js +1 -0
  31. package/dist-package/packages/runtime/src/runtime.js +2 -2
  32. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  33. package/package.json +7 -2
@@ -1,8 +1,12 @@
1
1
  import { readFileSync } from "node:fs";
2
- import { dirname, join } from "node:path";
2
+ import { dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
4
  const FRAMEKIT_PACKAGE_NAME = "@morshoto/framekit";
5
5
  export const FRAMEKIT_VERSION = readFramekitVersion();
6
+ export const FRAMEKIT_BUILD_FINGERPRINT = Object.freeze({
7
+ version: FRAMEKIT_VERSION,
8
+ commit: readFramekitCommit(),
9
+ });
6
10
  function readFramekitVersion() {
7
11
  let directory = dirname(fileURLToPath(import.meta.url));
8
12
  while (true) {
@@ -32,3 +36,107 @@ function isMissingFile(error) {
32
36
  return false;
33
37
  return error.code === "ENOENT";
34
38
  }
39
+ function readFramekitCommit() {
40
+ const configured = process.env.FRAMEKIT_BUILD_COMMIT?.trim();
41
+ if (configured)
42
+ return configured;
43
+ const repositoryRoot = findRepositoryRoot(dirname(fileURLToPath(import.meta.url)));
44
+ if (!repositoryRoot)
45
+ return "unknown";
46
+ try {
47
+ const gitEntry = join(repositoryRoot, ".git");
48
+ const gitDirectory = readGitDirectory(gitEntry);
49
+ const head = readFileSync(join(gitDirectory, "HEAD"), "utf8").trim();
50
+ if (/^[0-9a-f]{7,64}$/i.test(head))
51
+ return head;
52
+ if (!head.startsWith("ref: "))
53
+ return "unknown";
54
+ const ref = head.slice("ref: ".length).trim();
55
+ if (!ref)
56
+ return "unknown";
57
+ const commonDirectory = readCommonDirectory(gitDirectory);
58
+ const refCandidates = [join(gitDirectory, ref)];
59
+ if (commonDirectory)
60
+ refCandidates.push(join(commonDirectory, ref));
61
+ for (const refPath of refCandidates) {
62
+ try {
63
+ const commit = readFileSync(refPath, "utf8").trim();
64
+ if (/^[0-9a-f]{7,64}$/i.test(commit))
65
+ return commit;
66
+ }
67
+ catch (error) {
68
+ if (!isMissingFile(error))
69
+ throw error;
70
+ }
71
+ }
72
+ if (commonDirectory) {
73
+ const packedRefs = readFileSync(join(commonDirectory, "packed-refs"), "utf8");
74
+ const packedRef = packedRefs
75
+ .split("\n")
76
+ .map((line) => line.trim().split(" "))
77
+ .find(([commit, name]) => name === ref && /^[0-9a-f]{7,64}$/i.test(commit ?? ""));
78
+ if (packedRef?.[0])
79
+ return packedRef[0];
80
+ }
81
+ }
82
+ catch (error) {
83
+ if (!isMissingFile(error))
84
+ return "unknown";
85
+ }
86
+ return "unknown";
87
+ }
88
+ function findRepositoryRoot(start) {
89
+ let directory = start;
90
+ while (true) {
91
+ if (isGitEntry(join(directory, ".git")))
92
+ return directory;
93
+ const parent = dirname(directory);
94
+ if (parent === directory)
95
+ return undefined;
96
+ directory = parent;
97
+ }
98
+ }
99
+ function isGitEntry(path) {
100
+ try {
101
+ readFileSync(path, "utf8");
102
+ return true;
103
+ }
104
+ catch (error) {
105
+ if (!isMissingFile(error))
106
+ return true;
107
+ return false;
108
+ }
109
+ }
110
+ function readGitDirectory(gitEntry) {
111
+ let content;
112
+ try {
113
+ content = readFileSync(gitEntry, "utf8").trim();
114
+ }
115
+ catch (error) {
116
+ if (isDirectoryError(error))
117
+ return gitEntry;
118
+ throw error;
119
+ }
120
+ if (!content.startsWith("gitdir: "))
121
+ return gitEntry;
122
+ const configured = content.slice("gitdir: ".length).trim();
123
+ return isAbsolute(configured) ? configured : resolve(dirname(gitEntry), configured);
124
+ }
125
+ function readCommonDirectory(gitDirectory) {
126
+ try {
127
+ const configured = readFileSync(join(gitDirectory, "commondir"), "utf8").trim();
128
+ if (!configured)
129
+ return undefined;
130
+ return isAbsolute(configured) ? configured : resolve(gitDirectory, configured);
131
+ }
132
+ catch (error) {
133
+ if (!isMissingFile(error))
134
+ throw error;
135
+ return undefined;
136
+ }
137
+ }
138
+ function isDirectoryError(error) {
139
+ if (!error || typeof error !== "object" || !("code" in error))
140
+ return false;
141
+ return error.code === "EISDIR";
142
+ }
@@ -161,9 +161,7 @@ export class MediaAnalysisService {
161
161
  return findMedia(project, mediaId);
162
162
  }
163
163
  async searchMedia(query) {
164
- const project = await this.project.inspectProject();
165
- const normalized = query.trim().toLowerCase();
166
- return project.media.filter((media) => media.mediaId.toLowerCase().includes(normalized) || media.source.toLowerCase().includes(normalized));
164
+ return this.project.searchMedia(query);
167
165
  }
168
166
  async indexMedia(query = {}) {
169
167
  const project = await this.project.inspectProject();
@@ -1,4 +1,5 @@
1
- import { withCapabilityFamilies } from "../capabilities.js";
1
+ import { CapabilityUnavailableError } from "../domain/capabilities.js";
2
+ import { withCanonicalTimelineMode, withCapabilityFamilies } from "../capabilities.js";
2
3
  import { isWithinClip, parseRational, rationalDifferenceSeconds } from "../timeline/rational-time.js";
3
4
  export class ProjectService {
4
5
  adapter;
@@ -10,6 +11,14 @@ export class ProjectService {
10
11
  this.options = options;
11
12
  }
12
13
  async inspectProject() {
14
+ const identity = await this.adapter.getIdentity();
15
+ const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(await this.adapter.getCapabilities(), {
16
+ backend: identity.backend,
17
+ }));
18
+ const projectRead = capabilities.families.canonicalDocument.read;
19
+ if (!projectRead.available) {
20
+ throw new CapabilityUnavailableError("project.inspect", "canonicalDocument.read", projectRead);
21
+ }
13
22
  return this.context.inspectProject();
14
23
  }
15
24
  async inspectTimeline() {
@@ -20,7 +29,9 @@ export class ProjectService {
20
29
  if (!this.adapter.getManagedArtifact) {
21
30
  throw new Error("CAPABILITY_UNAVAILABLE: managed FCPXML artifact");
22
31
  }
23
- return this.adapter.getManagedArtifact();
32
+ const artifact = await this.adapter.getManagedArtifact();
33
+ const digest = await this.adapter.getManagedArtifactDigest?.();
34
+ return digest ? { ...artifact, digest } : artifact;
24
35
  }
25
36
  async captureFrame(position, options = {}) {
26
37
  const exactPosition = parseRational(position, "INVALID_TIMELINE_POSITION");
@@ -67,16 +78,28 @@ export class ProjectService {
67
78
  };
68
79
  }
69
80
  async listProjects() {
70
- const capabilities = await this.adapter.getCapabilities();
81
+ const capabilities = await this.adapter.getCapabilities({ probeCanonicalSnapshot: false });
71
82
  if (!capabilities.editor.projectCatalogRead || !this.adapter.listProjects) {
72
- throw new Error("CAPABILITY_UNAVAILABLE: editor project catalog");
83
+ const identity = await this.adapter.getIdentity();
84
+ throw new CapabilityUnavailableError("project.list", "editor.projectCatalogRead", {
85
+ available: false,
86
+ backend: identity.backend,
87
+ guarantee: "none",
88
+ unavailableReason: "project catalog is unavailable",
89
+ });
73
90
  }
74
91
  return this.adapter.listProjects();
75
92
  }
76
93
  async selectProject(selection) {
77
94
  const capabilities = await this.adapter.getCapabilities();
78
95
  if (!capabilities.editor.projectSelection || !this.adapter.selectProject) {
79
- throw new Error("CAPABILITY_UNAVAILABLE: editor project selection");
96
+ const identity = await this.adapter.getIdentity();
97
+ throw new CapabilityUnavailableError("project.select", "editor.projectSelection", {
98
+ available: false,
99
+ backend: identity.backend,
100
+ guarantee: "none",
101
+ unavailableReason: "project selection is unavailable",
102
+ });
80
103
  }
81
104
  if (!selection.projectId.trim())
82
105
  throw new Error("INVALID_PROJECT_SELECTION: projectId is required");
@@ -85,9 +108,9 @@ export class ProjectService {
85
108
  }
86
109
  return this.adapter.selectProject(selection);
87
110
  }
88
- async inspectEditor() {
111
+ async inspectEditor(options = {}) {
89
112
  const identity = await this.adapter.getIdentity();
90
- const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(), { backend: identity.backend });
113
+ const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(options), { backend: identity.backend });
91
114
  const speechAnalyzer = this.options.speechAnalyzer;
92
115
  const speechTranscribe = capabilities.analyzers.speechTranscribe
93
116
  || (speechAnalyzer ? speechAnalyzer.capabilities?.transcription ?? true : false);
@@ -130,6 +153,22 @@ export class ProjectService {
130
153
  const assets = await this.context.listAssets(query);
131
154
  return assets.filter((asset) => matchesAssetQuery(asset, query));
132
155
  }
156
+ async searchMedia(query) {
157
+ const identity = await this.adapter.getIdentity();
158
+ const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(), {
159
+ backend: identity.backend,
160
+ });
161
+ const mediaObservation = capabilities.families.observation.media;
162
+ if (!mediaObservation.available) {
163
+ throw new CapabilityUnavailableError("media.search", "observation.media", mediaObservation);
164
+ }
165
+ if (capabilities.editor.backgroundMediaDiscovery && this.adapter.listMedia) {
166
+ return this.adapter.listMedia({ query });
167
+ }
168
+ const project = await this.inspectProject();
169
+ const normalized = query.trim().toLowerCase();
170
+ return project.media.filter((media) => media.mediaId.toLowerCase().includes(normalized) || media.source.toLowerCase().includes(normalized));
171
+ }
133
172
  }
134
173
  function matchesAssetQuery(asset, query) {
135
174
  if (!query)
@@ -1,25 +1,34 @@
1
1
  import { CAPABILITY_SCHEMA_VERSION } from "./domain/capabilities.js";
2
2
  export function canonicalTimelineMode(capabilities) {
3
3
  const editor = capabilities.editor;
4
- const hasExplicitTargeting = Boolean(editor.projectCatalogRead && editor.projectSelection);
5
- if (editor.projectRead
6
- && editor.timelineSnapshotRead
7
- && hasExplicitTargeting
4
+ const hasCanonicalProjectRead = canonicalProjectReadAvailable(editor);
5
+ if (hasCanonicalProjectRead
8
6
  && editor.timelineWrite
9
7
  && editor.readAfterWrite
10
8
  && editor.rollback) {
11
9
  return "canonical-write";
12
10
  }
13
- if (editor.projectRead && editor.timelineSnapshotRead && hasExplicitTargeting)
11
+ if (hasCanonicalProjectRead)
14
12
  return "canonical-read";
15
13
  return "metadata-only";
16
14
  }
15
+ export function projectSelectionMode(editor) {
16
+ return editor.projectSelectionMode
17
+ ?? (editor.projectSelection ? "background-capable" : "unavailable");
18
+ }
19
+ function canonicalProjectReadAvailable(editor) {
20
+ return Boolean(editor.projectRead
21
+ && editor.timelineSnapshotRead
22
+ && editor.projectCatalogRead);
23
+ }
17
24
  export function withCanonicalTimelineMode(capabilities) {
18
25
  const normalized = {
19
26
  ...capabilities,
20
27
  editor: {
21
28
  ...capabilities.editor,
29
+ projectRead: canonicalProjectReadAvailable(capabilities.editor),
22
30
  canonicalTimelineMode: canonicalTimelineMode(capabilities),
31
+ projectSelectionMode: projectSelectionMode(capabilities.editor),
23
32
  },
24
33
  };
25
34
  const previous = capabilities.families;
@@ -28,6 +37,8 @@ export function withCanonicalTimelineMode(capabilities) {
28
37
  const canonicalRead = normalized.editor.canonicalTimelineMode === "canonical-read"
29
38
  || normalized.editor.canonicalTimelineMode === "canonical-write";
30
39
  const canonicalWrite = normalized.editor.canonicalTimelineMode === "canonical-write";
40
+ const backgroundLibraryInspection = normalized.editor.backgroundLibraryInspection
41
+ ?? previous.observation.library.available;
31
42
  const compositeTransactions = Boolean(normalized.editor.compositeTransactions
32
43
  && normalized.editor.timelineSnapshotRead
33
44
  && normalized.editor.readAfterWrite
@@ -38,6 +49,8 @@ export function withCanonicalTimelineMode(capabilities) {
38
49
  nativeBackend: previous.native.selectionWrite.backend,
39
50
  publishingBackend: previous.publishing.projectCreation.backend,
40
51
  exportBackend: previous.export.timeline.backend,
52
+ backgroundExportBackend: previous.export.background.backend,
53
+ externalExportBackend: previous.export.external.backend,
41
54
  analyzerBackends: {
42
55
  speechTranscribe: previous.analyzers.speechTranscribe.backend,
43
56
  speechVad: previous.analyzers.speechVad.backend,
@@ -46,6 +59,14 @@ export function withCanonicalTimelineMode(capabilities) {
46
59
  visualTrack: previous.analyzers.visualTrack.backend,
47
60
  },
48
61
  connection: previous.connection.status,
62
+ observation: {
63
+ media: normalized.editor.timelineSnapshotRead && normalized.editor.projectRead
64
+ || normalized.editor.backgroundMediaDiscovery
65
+ ? previous.observation.media
66
+ : false,
67
+ assets: normalized.editor.assetDiscovery ? previous.observation.assets : false,
68
+ library: backgroundLibraryInspection ? previous.observation.library : false,
69
+ },
49
70
  canonicalDocument: {
50
71
  read: refreshDescriptor(canonicalRead, previous.canonicalDocument.read, "canonical-read", "canonical timeline reads are unavailable"),
51
72
  write: refreshDescriptor(canonicalWrite, previous.canonicalDocument.write, "canonical-write", "canonical timeline writes are unavailable"),
@@ -66,6 +87,8 @@ export function withCanonicalTimelineMode(capabilities) {
66
87
  function refreshDescriptor(available, previous, guarantee, unavailableReason) {
67
88
  if (available && previous.available)
68
89
  return previous;
90
+ if (!available && !previous.available)
91
+ return previous;
69
92
  return descriptorFrom(available, previous.backend, guarantee, unavailableReason);
70
93
  }
71
94
  /**
@@ -75,12 +98,20 @@ function refreshDescriptor(available, previous, guarantee, unavailableReason) {
75
98
  export function withCapabilityFamilies(capabilities, options = {}) {
76
99
  const previous = capabilities.families;
77
100
  const backend = options.backend ?? previous?.connection.status.backend ?? "unknown";
101
+ const configuredLibrary = options.observation?.library;
102
+ const backgroundLibraryInspection = capabilities.editor.backgroundLibraryInspection
103
+ ?? (typeof configuredLibrary === "boolean" ? configuredLibrary : configuredLibrary?.available)
104
+ ?? previous?.observation.library.available
105
+ ?? false;
78
106
  const normalized = {
79
107
  ...capabilities,
80
108
  schemaVersion: CAPABILITY_SCHEMA_VERSION,
81
109
  editor: {
82
110
  ...capabilities.editor,
111
+ projectRead: canonicalProjectReadAvailable(capabilities.editor),
83
112
  canonicalTimelineMode: canonicalTimelineMode(capabilities),
113
+ projectSelectionMode: projectSelectionMode(capabilities.editor),
114
+ backgroundLibraryInspection,
84
115
  },
85
116
  };
86
117
  const editor = normalized.editor;
@@ -106,7 +137,15 @@ export function withCapabilityFamilies(capabilities, options = {}) {
106
137
  },
107
138
  observation: {
108
139
  timeline: descriptorFrom(editor.timelineSnapshotRead || editor.liveStateRead, backend, editor.timelineSnapshotRead ? "canonical-read" : "observed", "timeline observation is unavailable"),
109
- media: descriptorFrom(editor.timelineSnapshotRead && editor.projectRead, backend, "canonical-read", "media observation is unavailable"),
140
+ media: descriptorFrom(options.observation?.media ?? (editor.timelineSnapshotRead && editor.projectRead
141
+ ? previous?.observation.media ?? true
142
+ : editor.backgroundMediaDiscovery
143
+ ? previous?.observation.media ?? { available: true, backend, guarantee: "observed" }
144
+ : false), backend, editor.timelineSnapshotRead && editor.projectRead ? "canonical-read" : "observed", "media observation is unavailable"),
145
+ assets: descriptorFrom(options.observation?.assets ?? (editor.assetDiscovery ? previous?.observation.assets ?? true : false), backend, "observed", "asset discovery is unavailable"),
146
+ library: descriptorFrom(options.observation?.library ?? (backgroundLibraryInspection
147
+ ? previous?.observation.library ?? true
148
+ : false), backend, "observed", "background library inspection is unavailable"),
110
149
  },
111
150
  canonicalDocument: {
112
151
  read: descriptorFrom(canonicalDocument.read ?? (editor.canonicalTimelineMode === "canonical-read"
@@ -120,7 +159,9 @@ export function withCapabilityFamilies(capabilities, options = {}) {
120
159
  projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, "verified", "new project publishing is unavailable"),
121
160
  },
122
161
  export: {
123
- timeline: descriptorFrom(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable"),
162
+ timeline: exportDescriptor(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable", "headed-native"),
163
+ background: exportDescriptor(options.backgroundExport ?? previous?.export.background ?? false, options.backgroundExportBackend ?? previous?.export.background?.backend ?? backend, "verified", "background rendering is unavailable", "background-native"),
164
+ external: exportDescriptor(options.externalExport ?? previous?.export.external ?? editor.externalRender ?? false, options.externalExportBackend ?? previous?.export.external?.backend ?? backend, "verified", "external rendering is unavailable", "external-rendered"),
124
165
  },
125
166
  analyzers: {
126
167
  speechTranscribe: analyzerDescriptor(capabilities.analyzers.speechTranscribe, analyzerBackend("speechTranscribe"), "speech transcription"),
@@ -172,6 +213,13 @@ function descriptorFrom(value, backend, guarantee, unavailableReason) {
172
213
  ? { available: true, backend, guarantee }
173
214
  : { available: false, backend, guarantee: "none", unavailableReason };
174
215
  }
216
+ function exportDescriptor(value, backend, guarantee, unavailableReason, evidenceTier) {
217
+ if (typeof value !== "boolean")
218
+ return value;
219
+ return value
220
+ ? { available: true, backend, guarantee, evidenceTier }
221
+ : { available: false, backend, guarantee: "none", unavailableReason };
222
+ }
175
223
  function analyzerDescriptor(available, backend, operation) {
176
224
  return descriptorFrom(available, backend, "verified", `${operation} is unavailable`);
177
225
  }
@@ -0,0 +1,159 @@
1
+ import { parseRational } from "../timeline/rational-time.js";
2
+ export function reconcileProjectCatalog(catalog, options) {
3
+ validateProjectCatalog(catalog);
4
+ if (options.before)
5
+ validateLiveState(options.before);
6
+ if (options.after)
7
+ validateLiveState(options.after);
8
+ const state = options.after ?? options.before;
9
+ const beforeRevision = options.before?.revision;
10
+ const afterRevision = options.after?.revision;
11
+ const project = state?.project
12
+ ? matchIdentity(catalog.projects, state.project.id, state.project.name, (candidate) => candidate.id, (candidate) => candidate.name)
13
+ : unresolvedIdentity();
14
+ const projectDescriptor = project.catalogId
15
+ ? catalog.projects.find((candidate) => candidate.id === project.catalogId)
16
+ : undefined;
17
+ const sequence = state?.sequence && projectDescriptor
18
+ ? matchIdentity(projectDescriptor.sequences, state.sequence.id, state.sequence.name, (candidate) => candidate.id, (candidate) => candidate.name)
19
+ : unresolvedIdentity(state?.sequence?.id);
20
+ let status = project.method === "stable-id"
21
+ && sequence.method === "stable-id"
22
+ ? "matched"
23
+ : "unresolved";
24
+ let reason = status === "unresolved" ? "stable project and sequence IDs could not be reconciled" : undefined;
25
+ if (status === "matched"
26
+ && ((catalog.activeProjectId !== undefined && catalog.activeProjectId !== project.catalogId)
27
+ || (catalog.activeSequenceId !== undefined && catalog.activeSequenceId !== sequence.catalogId))) {
28
+ status = "stale";
29
+ reason = "background active target differs from live target";
30
+ }
31
+ if (options.before && options.after) {
32
+ if (options.after.revision.sequence < options.before.revision.sequence) {
33
+ throw new Error("PROJECT_CATALOG_INVALID: live revision sequence regressed");
34
+ }
35
+ if (!sameTarget(options.before, options.after)) {
36
+ status = "stale";
37
+ reason = "live target changed during project catalog reconciliation";
38
+ }
39
+ else if (!sameRevision(options.before.revision, options.after.revision)) {
40
+ status = "stale";
41
+ reason = "live revision changed during project catalog reconciliation";
42
+ }
43
+ }
44
+ const result = structuredClone(catalog);
45
+ if (status === "matched" && state?.project && state.sequence) {
46
+ result.activeProjectId = project.catalogId;
47
+ result.activeSequenceId = sequence.catalogId;
48
+ }
49
+ else {
50
+ delete result.activeProjectId;
51
+ delete result.activeSequenceId;
52
+ }
53
+ result.provenance = {
54
+ catalog: { ...options.provenance.catalog },
55
+ ...(state && options.provenance.live
56
+ ? { live: { ...options.provenance.live, state: structuredClone(state) } }
57
+ : {}),
58
+ reconciliation: {
59
+ status,
60
+ project,
61
+ sequence,
62
+ ...(beforeRevision ? { beforeRevision: { ...beforeRevision } } : {}),
63
+ ...(afterRevision ? { afterRevision: { ...afterRevision } } : {}),
64
+ ...(reason ? { reason } : {}),
65
+ },
66
+ selection: { ...options.provenance.selection },
67
+ };
68
+ return result;
69
+ }
70
+ function matchIdentity(values, liveId, liveName, id, name) {
71
+ const stable = values.find((value) => id(value) === liveId);
72
+ if (stable)
73
+ return { method: "stable-id", catalogId: id(stable), liveId };
74
+ const named = values.filter((value) => name(value) === liveName);
75
+ if (named.length === 1)
76
+ return { method: "name-only", catalogId: id(named[0]), liveId };
77
+ return unresolvedIdentity(liveId);
78
+ }
79
+ function unresolvedIdentity(liveId) {
80
+ return { method: "unresolved", ...(liveId ? { liveId } : {}) };
81
+ }
82
+ function sameTarget(left, right) {
83
+ return left.project?.id === right.project?.id
84
+ && left.sequence?.id === right.sequence?.id;
85
+ }
86
+ function sameRevision(left, right) {
87
+ return left.id === right.id && left.sequence === right.sequence;
88
+ }
89
+ export function validateProjectCatalog(catalog) {
90
+ if (!Array.isArray(catalog.projects))
91
+ throw new Error("PROJECT_CATALOG_INVALID: projects must be an array");
92
+ const projectIds = new Set();
93
+ for (const project of catalog.projects) {
94
+ if (!project || typeof project !== "object")
95
+ throw new Error("PROJECT_CATALOG_INVALID: project must be an object");
96
+ if (!project.id.trim())
97
+ throw new Error("PROJECT_CATALOG_INVALID: project id must be non-empty");
98
+ if (projectIds.has(project.id))
99
+ throw new Error(`PROJECT_CATALOG_INVALID: duplicate project id ${project.id}`);
100
+ projectIds.add(project.id);
101
+ if (!project.name.trim())
102
+ throw new Error(`PROJECT_CATALOG_INVALID: project ${project.id} name must be non-empty`);
103
+ if (!Array.isArray(project.sequences))
104
+ throw new Error(`PROJECT_CATALOG_INVALID: project ${project.id} sequences must be an array`);
105
+ const sequenceIds = new Set();
106
+ for (const sequence of project.sequences) {
107
+ if (!sequence || typeof sequence !== "object") {
108
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence in project ${project.id} must be an object`);
109
+ }
110
+ if (!sequence.id.trim())
111
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence in project ${project.id} id must be non-empty`);
112
+ if (sequenceIds.has(sequence.id))
113
+ throw new Error(`PROJECT_CATALOG_INVALID: duplicate sequence id ${sequence.id} in project ${project.id}`);
114
+ sequenceIds.add(sequence.id);
115
+ if (!sequence.name.trim())
116
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence ${sequence.id} name must be non-empty`);
117
+ }
118
+ }
119
+ if (catalog.activeProjectId !== undefined && !projectIds.has(catalog.activeProjectId)) {
120
+ throw new Error(`PROJECT_CATALOG_INVALID: active project ${catalog.activeProjectId} is absent from the catalog`);
121
+ }
122
+ if (catalog.activeSequenceId !== undefined) {
123
+ const activeProject = catalog.projects.find(({ id }) => id === catalog.activeProjectId);
124
+ if (!activeProject?.sequences.some(({ id }) => id === catalog.activeSequenceId)) {
125
+ throw new Error(`PROJECT_CATALOG_INVALID: active sequence ${catalog.activeSequenceId} is absent from the active project`);
126
+ }
127
+ }
128
+ }
129
+ function validateLiveState(state) {
130
+ validateRevision(state.revision);
131
+ if (state.sequence) {
132
+ validateRational(state.sequence.startTime, "live sequence start time");
133
+ validateRational(state.sequence.duration, "live sequence duration");
134
+ validateRational(state.sequence.frameDuration, "live sequence frame duration");
135
+ }
136
+ if (state.playheadTime)
137
+ validateRational(state.playheadTime, "live playhead time");
138
+ if (state.sequenceTimeRange) {
139
+ validateRational(state.sequenceTimeRange.start, "live sequence range start");
140
+ validateRational(state.sequenceTimeRange.duration, "live sequence range duration");
141
+ }
142
+ }
143
+ function validateRevision(revision) {
144
+ if (!revision.id.trim())
145
+ throw new Error("PROJECT_CATALOG_INVALID: live revision id must be non-empty");
146
+ if (!Number.isInteger(revision.sequence) || revision.sequence < 0) {
147
+ throw new Error("PROJECT_CATALOG_INVALID: live revision sequence must be a non-negative integer");
148
+ }
149
+ if (!revision.timestamp.trim())
150
+ throw new Error("PROJECT_CATALOG_INVALID: live revision timestamp must be non-empty");
151
+ }
152
+ function validateRational(value, field) {
153
+ try {
154
+ parseRational(value, "PROJECT_CATALOG_INVALID");
155
+ }
156
+ catch {
157
+ throw new Error(`PROJECT_CATALOG_INVALID: ${field} must use an integer value and positive timescale`);
158
+ }
159
+ }
@@ -1 +1,34 @@
1
1
  export const CAPABILITY_SCHEMA_VERSION = 1;
2
+ export class CapabilityUnavailableError extends Error {
3
+ operation;
4
+ capability;
5
+ code = "CAPABILITY_UNAVAILABLE";
6
+ available = false;
7
+ backend;
8
+ guarantee = "none";
9
+ unavailableReason;
10
+ constructor(operation, capability, descriptor) {
11
+ const unavailableReason = descriptor.unavailableReason ?? `${capability} is unavailable`;
12
+ super(`CAPABILITY_UNAVAILABLE: ${operation} requires ${capability}: ${unavailableReason}`);
13
+ this.operation = operation;
14
+ this.capability = capability;
15
+ this.name = "CapabilityUnavailableError";
16
+ this.backend = descriptor.backend;
17
+ this.unavailableReason = unavailableReason;
18
+ }
19
+ toJSON() {
20
+ return {
21
+ code: this.code,
22
+ message: `${this.operation} requires ${this.capability}`,
23
+ operation: this.operation,
24
+ capability: this.capability,
25
+ available: this.available,
26
+ backend: this.backend,
27
+ guarantee: this.guarantee,
28
+ unavailableReason: this.unavailableReason,
29
+ };
30
+ }
31
+ }
32
+ export function serializeCapabilityUnavailableError(error) {
33
+ return error instanceof CapabilityUnavailableError ? error.toJSON() : undefined;
34
+ }
@@ -1 +1,14 @@
1
- export {};
1
+ export function createProjectSelectionResult(catalog, requestedTarget, observedRevision) {
2
+ if (!catalog.activeProjectId || !catalog.activeSequenceId) {
3
+ throw new Error("TARGET_MISMATCH: project selection did not produce an active target");
4
+ }
5
+ return {
6
+ ...catalog,
7
+ requestedTarget: { ...requestedTarget },
8
+ observedActiveTarget: {
9
+ projectId: catalog.activeProjectId,
10
+ sequenceId: catalog.activeSequenceId,
11
+ },
12
+ observedRevision: { ...observedRevision },
13
+ };
14
+ }
@@ -7,6 +7,7 @@ export * from "./diff.js";
7
7
  export * from "./capabilities.js";
8
8
  export * from "./ports.js";
9
9
  export * from "./verification.js";
10
+ export * from "./timeline-target.js";
10
11
  export * from "./rough-cut.js";
11
12
  export * from "./duration.js";
12
13
  export * from "./skills.js";