@morshoto/framekit 0.1.17 → 0.1.18

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 (26) hide show
  1. package/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -3
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +128 -29
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +200 -48
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +17 -7
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +255 -16
  20. package/dist-package/apps/mcp-server/src/main.js +27 -3
  21. package/dist-package/apps/mcp-server/src/server.js +270 -49
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  24. package/dist-package/packages/runtime/src/runtime.js +6 -0
  25. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  26. package/package.json +9 -9
@@ -1,13 +1,15 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
3
  import { resolve as resolvePath } from "node:path";
4
- import { z } from "zod";
4
+ import { z } from "zod/v3";
5
5
  import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
6
6
  import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
7
  import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
+ import { assessBuildAlignment } from "./build-alignment.js";
8
9
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
9
10
  import { EditingSessionRepository } from "./headless-sessions.js";
10
11
  import { SessionMaterializationJobs, } from "./materialization-jobs.js";
12
+ import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
11
13
  import { chooseTimelineReadback } from "./readback-policy.js";
12
14
  const revisionValueSchema = z.object({
13
15
  id: z.string(),
@@ -56,6 +58,7 @@ const timelineSemanticContextQuerySchema = z.object({
56
58
  }).strict();
57
59
  const roughCutPlanSchema = mediaIndexQuerySchema.extend({
58
60
  maxShots: z.number().int().positive().optional(),
61
+ projectId: z.string().min(1).optional(),
59
62
  });
60
63
  const durationRangeSchema = z.object({
61
64
  startSeconds: z.number().finite().nonnegative(),
@@ -319,6 +322,7 @@ function installMcpSchemaCompatibility(server) {
319
322
  }
320
323
  const artifactPublishInputSchema = z.object({
321
324
  artifactPath: z.string().trim().min(1),
325
+ targetLibraryPath: z.string().trim().min(1),
322
326
  transactionId: z.string().min(1),
323
327
  confirm: z.boolean(),
324
328
  }).strict();
@@ -836,6 +840,29 @@ function frameResult(value) {
836
840
  }
837
841
  export function createMcpServer(runtime, options = {}) {
838
842
  runtime.registerBuiltinSkills();
843
+ if (options.requireBuildAlignment) {
844
+ const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
845
+ options = {
846
+ ...options,
847
+ ...(options.nativeEditor
848
+ ? { nativeEditor: withBuildAlignmentGuard(options.nativeEditor, assertAlignment, ["capabilities"]) }
849
+ : {}),
850
+ ...(options.disposableNative
851
+ ? { disposableNative: withBuildAlignmentGuard(options.disposableNative, assertAlignment) }
852
+ : {}),
853
+ ...(options.nativeOperationSession
854
+ ? { nativeOperationSession: withBuildAlignmentGuard(options.nativeOperationSession, assertAlignment) }
855
+ : {}),
856
+ ...(options.projectPublisher
857
+ ? {
858
+ projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob"]),
859
+ }
860
+ : {}),
861
+ ...(options.videoExporter
862
+ ? { videoExporter: withBuildAlignmentGuard(options.videoExporter, assertAlignment, ["isAvailable"]) }
863
+ : {}),
864
+ };
865
+ }
839
866
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
840
867
  const nativeTransitionAssets = new Map();
841
868
  const sessions = options.sessionDirectory
@@ -972,6 +999,10 @@ export function createMcpServer(runtime, options = {}) {
972
999
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
973
1000
  inputSchema: {},
974
1001
  }, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
1002
+ server.registerTool("editor.native.handoff.readiness", {
1003
+ description: "Read native Final Cut handoff readiness without launching, activating, importing, or mutating Final Cut.",
1004
+ inputSchema: { publishJobId: z.string().trim().min(1).optional() },
1005
+ }, async ({ publishJobId }) => jsonResult(await inspectNativeHandoffReadiness(runtime, options, publishJobId)));
975
1006
  server.registerTool("skill.list", {
976
1007
  description: "List registered versioned Framekit Skills with current capability availability.",
977
1008
  inputSchema: {},
@@ -1287,7 +1318,11 @@ export function createMcpServer(runtime, options = {}) {
1287
1318
  editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
1288
1319
  },
1289
1320
  }, async ({ operation, fallback, path, editType }) => {
1290
- const context = await editingRouteContext(runtime, options);
1321
+ const headlessOnly = fallback === "none"
1322
+ && (path === "headless" || (Boolean(options.headlessProjects) && operation === "timeline.edit" && path !== "headed"));
1323
+ const context = headlessOnly
1324
+ ? { connection: { state: "disconnected" }, ...headlessRoutingContext(options) }
1325
+ : await editingRouteContext(runtime, options);
1291
1326
  return jsonResult(resolveEditingRoute({
1292
1327
  operation,
1293
1328
  fallback,
@@ -1387,7 +1422,7 @@ export function createMcpServer(runtime, options = {}) {
1387
1422
  }, async ({ jobId }) => {
1388
1423
  if (!options.nativeOperationSession)
1389
1424
  throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1390
- return jsonResult(options.nativeOperationSession.status(jobId));
1425
+ return jsonResult(await options.nativeOperationSession.status(jobId));
1391
1426
  });
1392
1427
  server.registerTool("editor.native.operation.retry", {
1393
1428
  description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
@@ -1628,32 +1663,51 @@ export function createMcpServer(runtime, options = {}) {
1628
1663
  return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1629
1664
  });
1630
1665
  server.registerTool("artifact.publish.preview", {
1631
- description: "Prepare a verified FCPXML publish handoff without opening Final Cut; the configured native route may use non-activating document delivery or an explicit headed fallback.",
1666
+ description: "Prepare an experimental, opt-in native handoff from a verified artifact without opening Final Cut.",
1632
1667
  inputSchema: {
1633
1668
  artifactPath: z.string().trim().min(1),
1634
- transactionId: z.string().min(1),
1669
+ targetLibraryPath: z.string().trim().min(1),
1670
+ transactionId: z.string().min(1).optional(),
1671
+ headlessExecutionId: z.string().min(1).optional(),
1635
1672
  },
1636
- }, async ({ artifactPath, transactionId }) => {
1673
+ }, async ({ artifactPath, targetLibraryPath, transactionId, headlessExecutionId }) => {
1637
1674
  if (!options.projectPublisher)
1638
1675
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1639
- const transaction = runtime.getTransaction(transactionId);
1640
- if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1641
- throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1676
+ if (Boolean(transactionId) === Boolean(headlessExecutionId)) {
1677
+ throw new Error("PUBLISH_SOURCE_REQUIRED: provide exactly one of transactionId or headlessExecutionId");
1642
1678
  }
1643
- if (!transaction.artifactDigest) {
1644
- throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1679
+ let sourceTransactionId;
1680
+ let artifactDigest;
1681
+ let sourceProof;
1682
+ if (headlessExecutionId) {
1683
+ sourceProof = await requireHeadlessProjects().verifyPublishableRoughCut(headlessExecutionId, artifactPath);
1684
+ sourceTransactionId = sourceProof.sourceTransactionId;
1685
+ artifactDigest = sourceProof.artifactDigest;
1645
1686
  }
1646
- const verification = await runtime.verifyTransaction(transactionId);
1647
- if (!verification.passed)
1648
- throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1649
- return jsonResult(await options.projectPublisher.preparePublish({
1650
- sourceTransactionId: transactionId,
1687
+ else {
1688
+ const transaction = runtime.getTransaction(transactionId);
1689
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1690
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1691
+ }
1692
+ if (!transaction.artifactDigest) {
1693
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1694
+ }
1695
+ const verification = await runtime.verifyTransaction(transactionId);
1696
+ if (!verification.passed)
1697
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1698
+ sourceTransactionId = transactionId;
1699
+ artifactDigest = transaction.artifactDigest;
1700
+ }
1701
+ const job = await options.projectPublisher.preparePublish({
1702
+ sourceTransactionId,
1651
1703
  artifactPath,
1652
- artifactDigest: transaction.artifactDigest,
1653
- }));
1704
+ artifactDigest,
1705
+ targetLibraryPath,
1706
+ });
1707
+ return jsonResult({ ...job, ...(sourceProof ? { sourceProof } : {}) });
1654
1708
  });
1655
1709
  server.registerTool("artifact.publish.execute", {
1656
- description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
1710
+ description: "Execute an experimental native handoff after explicit confirmation; dispatch alone is not project-creation proof, and success requires target readback.",
1657
1711
  inputSchema: {
1658
1712
  jobId: z.string().trim().min(1),
1659
1713
  confirm: z.literal(true),
@@ -1661,6 +1715,9 @@ export function createMcpServer(runtime, options = {}) {
1661
1715
  }, async ({ jobId, confirm }) => {
1662
1716
  if (!options.projectPublisher)
1663
1717
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1718
+ if (options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
1719
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1720
+ }
1664
1721
  return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
1665
1722
  });
1666
1723
  server.registerTool("artifact.publish.status", {
@@ -1672,11 +1729,14 @@ export function createMcpServer(runtime, options = {}) {
1672
1729
  return jsonResult(options.projectPublisher.getPublishJob(jobId));
1673
1730
  });
1674
1731
  server.registerTool("artifact.publish", {
1675
- description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
1732
+ description: "Experimental, opt-in native import of validated FCPXML. Dispatch alone does not prove project creation; success requires matching created-target readback and explicit confirmation.",
1676
1733
  inputSchema: artifactPublishInputSchema,
1677
- }, async ({ artifactPath, transactionId, confirm }) => {
1678
- if (!options.projectPublisher)
1679
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1734
+ }, async ({ artifactPath, targetLibraryPath, transactionId, confirm }) => {
1735
+ if (!options.projectPublisher?.isAvailable())
1736
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1737
+ if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1738
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1739
+ }
1680
1740
  const transaction = runtime.getTransaction(transactionId);
1681
1741
  if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1682
1742
  throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
@@ -1691,15 +1751,23 @@ export function createMcpServer(runtime, options = {}) {
1691
1751
  sourceTransactionId: transactionId,
1692
1752
  artifactPath,
1693
1753
  artifactDigest: transaction.artifactDigest,
1754
+ targetLibraryPath,
1694
1755
  confirm,
1695
1756
  }));
1696
1757
  });
1697
1758
  server.registerTool("timeline.publish.new-project", {
1698
- description: "Legacy alias for publishing a verified artifact transaction as a new Final Cut project.",
1699
- inputSchema: { transactionId: z.string().min(1) },
1700
- }, async ({ transactionId }) => {
1759
+ description: "Experimental, opt-in native import of a verified artifact transaction; reports verified delivery only after matching created-target readback and explicit confirmation.",
1760
+ inputSchema: {
1761
+ transactionId: z.string().min(1),
1762
+ targetLibraryPath: z.string().trim().min(1),
1763
+ confirm: z.literal(true),
1764
+ },
1765
+ }, async ({ transactionId, targetLibraryPath, confirm }) => {
1701
1766
  if (!options.projectPublisher?.isAvailable())
1702
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1767
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1768
+ if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1769
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1770
+ }
1703
1771
  const transaction = runtime.getTransaction(transactionId);
1704
1772
  if (transaction.target?.kind !== "artifact") {
1705
1773
  throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for a managed artifact`);
@@ -1714,7 +1782,8 @@ export function createMcpServer(runtime, options = {}) {
1714
1782
  sourceTransactionId: transactionId,
1715
1783
  artifactPath: transaction.target.artifactPath,
1716
1784
  artifactDigest: transaction.artifactDigest,
1717
- confirm: true,
1785
+ targetLibraryPath,
1786
+ confirm,
1718
1787
  }));
1719
1788
  });
1720
1789
  server.registerTool("timeline.export", {
@@ -1916,13 +1985,28 @@ export function createMcpServer(runtime, options = {}) {
1916
1985
  },
1917
1986
  }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeVisual(mediaId, range)));
1918
1987
  server.registerTool("media.understand", {
1919
- description: "Return combined speech, audio, and visual understanding for one media item.",
1920
- inputSchema: { mediaId: z.string().min(1) },
1921
- }, async ({ mediaId }) => jsonResult(await runtime.understandMedia(mediaId)));
1988
+ description: "Return combined speech, audio, and visual understanding for one media item in the selected editor project or a named headless project.",
1989
+ inputSchema: { mediaId: z.string().min(1), projectId: z.string().min(1).optional() },
1990
+ }, async ({ mediaId, projectId }) => {
1991
+ if (!projectId)
1992
+ return jsonResult(await runtime.understandMedia(mediaId));
1993
+ return sessionResult(async () => {
1994
+ const project = await requireHeadlessProjects().open(projectId);
1995
+ return runtime.understandMediaInProject(mediaId, projectSnapshotFromTimelineIr(project.timeline));
1996
+ });
1997
+ });
1922
1998
  server.registerTool("rough-cut.plan", {
1923
- description: "Create a deterministic, explainable, read-only shot plan from analyzed media; does not mutate the timeline.",
1999
+ description: "Create a deterministic, explainable, read-only shot plan from analyzed editor or named headless project media; does not mutate the timeline.",
1924
2000
  inputSchema: roughCutPlanSchema.shape,
1925
- }, async (request) => jsonResult(await runtime.planRoughCut(request)));
2001
+ }, async (request) => {
2002
+ const { projectId, ...planRequest } = request;
2003
+ if (!projectId)
2004
+ return jsonResult(await runtime.planRoughCut(planRequest));
2005
+ return sessionResult(async () => {
2006
+ const project = await requireHeadlessProjects().open(projectId);
2007
+ return runtime.planRoughCutInProject(planRequest, projectSnapshotFromTimelineIr(project.timeline));
2008
+ });
2009
+ });
1926
2010
  server.registerTool("editor.assets", {
1927
2011
  description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
1928
2012
  inputSchema: {
@@ -2309,7 +2393,7 @@ async function effectiveConnectionStatus(runtime, options) {
2309
2393
  ...status,
2310
2394
  state: "unavailable",
2311
2395
  lastError: {
2312
- code: "CAPABILITY_UNAVAILABLE",
2396
+ code: message.match(/\bFRAMEKIT_[A-Z_]+\b/)?.[0] ?? "CAPABILITY_UNAVAILABLE",
2313
2397
  message: `effective runtime capability inspection failed: ${message}`,
2314
2398
  },
2315
2399
  identity: undefined,
@@ -2320,13 +2404,22 @@ async function effectiveConnectionStatus(runtime, options) {
2320
2404
  }
2321
2405
  async function inspectMcpEditor(runtime, options) {
2322
2406
  const inspected = await runtime.inspectEditor();
2407
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2408
+ const buildAlignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2409
+ if (options.requireBuildAlignment && buildAlignment.status !== "matched") {
2410
+ throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${buildAlignment.message}`);
2411
+ }
2323
2412
  const native = options.nativeEditor?.capabilities();
2324
- const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2325
- const publishingMode = publishingAvailable
2413
+ const processMode = options.processMode ?? (native ? "headed" : "headless");
2414
+ const configuredPublisher = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2415
+ const publisherExecutionMode = configuredPublisher
2326
2416
  ? (typeof options.projectPublisher?.executionMode === "function"
2327
2417
  ? options.projectPublisher.executionMode()
2328
2418
  : "headed-only")
2329
2419
  : "unavailable";
2420
+ const publishingAvailable = configuredPublisher && (publisherExecutionMode === "background-capable"
2421
+ || processMode === "headed");
2422
+ const publishingMode = publishingAvailable ? publisherExecutionMode : "unavailable";
2330
2423
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
2331
2424
  const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
2332
2425
  const capabilities = withCapabilityFamilies({
@@ -2399,14 +2492,138 @@ async function inspectMcpEditor(runtime, options) {
2399
2492
  },
2400
2493
  preflight: {
2401
2494
  ...createCapabilityPreflight(inspected.identity, capabilities, {
2402
- processMode: options.processMode ?? (native ? "headed" : "headless"),
2495
+ processMode,
2403
2496
  nativeWrite: Boolean(native?.selectionEdit),
2404
2497
  }),
2405
- fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
2498
+ fingerprint,
2499
+ buildAlignment,
2500
+ nativeHandoffReadiness: createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
2406
2501
  },
2407
2502
  ...(native ? { native } : {}),
2408
2503
  };
2409
2504
  }
2505
+ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
2506
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2507
+ let extensionFingerprint;
2508
+ try {
2509
+ extensionFingerprint = (await runtime.inspectEditor()).identity.buildFingerprint;
2510
+ }
2511
+ catch {
2512
+ const status = await connectionStatus(options).catch(() => undefined);
2513
+ extensionFingerprint = status?.identity?.buildFingerprint;
2514
+ }
2515
+ const buildAlignment = assessBuildAlignment(fingerprint, extensionFingerprint, options.validationCommit);
2516
+ return createNativeHandoffReadiness(options.projectPublisher, buildAlignment, publishJobId);
2517
+ }
2518
+ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2519
+ const publisherReadiness = inspectProjectPublisherReadiness(publisher);
2520
+ const reasons = [...publisherReadiness.reasons];
2521
+ if (buildAlignment.status !== "matched") {
2522
+ reasons.push({
2523
+ code: buildAlignment.status === "mismatched"
2524
+ ? "FRAMEKIT_BUILD_ALIGNMENT_MISMATCH"
2525
+ : "FRAMEKIT_BUILD_ALIGNMENT_MISSING",
2526
+ message: `Workflow Extension build alignment is ${buildAlignment.status}: ${buildAlignment.message}`,
2527
+ });
2528
+ }
2529
+ let publish;
2530
+ let verifiedTarget;
2531
+ if (publishJobId) {
2532
+ if (!publisher || typeof publisher.getPublishJob !== "function") {
2533
+ reasons.push({
2534
+ code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
2535
+ message: `Publish job ${publishJobId} cannot be inspected because the publisher is unavailable`,
2536
+ });
2537
+ }
2538
+ else {
2539
+ try {
2540
+ const job = publisher.getPublishJob(publishJobId);
2541
+ publish = { jobId: job.jobId, state: job.state };
2542
+ const resultTarget = job.result?.createdTarget;
2543
+ const targetMatches = job.createdTarget
2544
+ && resultTarget
2545
+ && job.createdTarget.projectId === resultTarget.projectId
2546
+ && job.createdTarget.sequenceId === resultTarget.sequenceId;
2547
+ if (job.state === "verified" && job.result?.verified === true && targetMatches) {
2548
+ verifiedTarget = resultTarget;
2549
+ }
2550
+ else {
2551
+ reasons.push({
2552
+ code: "FINAL_CUT_PUBLISH_TARGET_UNVERIFIED",
2553
+ message: job.error?.message
2554
+ ? `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs remain withheld: ${job.error.message}`
2555
+ : `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs are reported only after native readback verifies them`,
2556
+ });
2557
+ }
2558
+ }
2559
+ catch (error) {
2560
+ const message = error instanceof Error ? error.message : String(error);
2561
+ reasons.push({
2562
+ code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
2563
+ message: `Publish job ${publishJobId} could not be inspected: ${message}`,
2564
+ });
2565
+ }
2566
+ }
2567
+ }
2568
+ const ready = reasons.length === 0;
2569
+ return {
2570
+ status: ready ? (publishJobId ? "verified" : "ready") : "blocked",
2571
+ reasons,
2572
+ targetBinding: {
2573
+ available: publisherReadiness.targetBindingAvailable,
2574
+ guarantee: publisherReadiness.targetBindingAvailable ? "native-readback" : "none",
2575
+ },
2576
+ buildAlignment,
2577
+ ...(publish ? { publish } : {}),
2578
+ ...(ready && verifiedTarget ? { createdTarget: verifiedTarget } : {}),
2579
+ };
2580
+ }
2581
+ function inspectProjectPublisherReadiness(publisher) {
2582
+ if (!publisher) {
2583
+ return {
2584
+ available: false,
2585
+ targetBindingAvailable: false,
2586
+ reasons: [{
2587
+ code: "FINAL_CUT_PUBLISH_PROVIDER_UNAVAILABLE",
2588
+ message: "No Final Cut project publisher is configured",
2589
+ }],
2590
+ };
2591
+ }
2592
+ if (typeof publisher.inspectReadiness === "function")
2593
+ return publisher.inspectReadiness();
2594
+ // Keep older injected publisher implementations fail-closed but inspectable.
2595
+ const available = typeof publisher.isAvailable === "function" && publisher.isAvailable();
2596
+ return {
2597
+ available,
2598
+ targetBindingAvailable: available,
2599
+ reasons: available ? [] : [{
2600
+ code: "FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE",
2601
+ message: "Native publisher readiness or target-binding provider is unavailable",
2602
+ }],
2603
+ };
2604
+ }
2605
+ async function assertRequiredBuildAlignment(runtime, options) {
2606
+ const inspected = await runtime.inspectEditor();
2607
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2608
+ const alignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2609
+ if (alignment.status !== "matched") {
2610
+ throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${alignment.message}`);
2611
+ }
2612
+ }
2613
+ function withBuildAlignmentGuard(provider, assertAlignment, synchronousMethods = []) {
2614
+ const synchronous = new Set(synchronousMethods);
2615
+ return new Proxy(provider, {
2616
+ get(target, property) {
2617
+ const value = Reflect.get(target, property, target);
2618
+ if (typeof value !== "function" || synchronous.has(property))
2619
+ return value;
2620
+ return async (...args) => {
2621
+ await assertAlignment();
2622
+ return Reflect.apply(value, target, args);
2623
+ };
2624
+ },
2625
+ });
2626
+ }
2410
2627
  function requireArtifactTransaction(runtime, transactionId, artifactPath) {
2411
2628
  const transaction = runtime.getTransaction(transactionId);
2412
2629
  const target = transaction.target;
@@ -2428,6 +2645,9 @@ async function requireEditingRoute(runtime, options, operation, path, editType)
2428
2645
  throw new Error(`${route.reason.code}: ${route.reason.message}`);
2429
2646
  }
2430
2647
  }
2648
+ function requiresHeadedPublishingRoute(publisher) {
2649
+ return publisher.executionMode() !== "background-capable";
2650
+ }
2431
2651
  async function editingRouteContext(runtime, options) {
2432
2652
  const connection = await effectiveConnectionStatus(runtime, options);
2433
2653
  let nativeReadiness;
@@ -2449,18 +2669,19 @@ async function editingRouteContext(runtime, options) {
2449
2669
  return {
2450
2670
  connection,
2451
2671
  ...(editor ? { editor } : {}),
2452
- ...(options.headlessProjects ? {
2453
- headless: {
2454
- available: true,
2455
- backend: "framekit-project-store",
2456
- guarantee: "canonical-write",
2457
- // Advertise only concrete Timeline IR edit capabilities. The legacy
2458
- // timeline.edit surface also accepts operations that the headless
2459
- // transaction layer does not implement.
2460
- supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
2461
- },
2462
- } : {}),
2672
+ ...headlessRoutingContext(options),
2463
2673
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2464
2674
  ...(nativeReadiness ? { nativeReadiness } : {}),
2465
2675
  };
2466
2676
  }
2677
+ function headlessRoutingContext(options) {
2678
+ return options.headlessProjects ? {
2679
+ headless: {
2680
+ available: true,
2681
+ backend: "framekit-project-store",
2682
+ guarantee: "canonical-write",
2683
+ // The legacy timeline.edit surface also includes unsupported operations.
2684
+ supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
2685
+ },
2686
+ } : {};
2687
+ }
@@ -1,6 +1,7 @@
1
1
  import { readFileSync } from "node:fs";
2
2
  import { dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
+ import { parsePackageBuildIdentity } from "./build-identity.js";
4
5
  const FRAMEKIT_PACKAGE_NAME = "@morshoto/framekit";
5
6
  export const FRAMEKIT_VERSION = readFramekitVersion();
6
7
  export const FRAMEKIT_BUILD_FINGERPRINT = Object.freeze({
@@ -38,8 +39,15 @@ function isMissingFile(error) {
38
39
  }
39
40
  function readFramekitCommit() {
40
41
  const configured = process.env.FRAMEKIT_BUILD_COMMIT?.trim();
41
- if (configured)
42
- return configured;
42
+ if (configured) {
43
+ if (!/^[0-9a-f]{40}$/i.test(configured)) {
44
+ throw new Error("FRAMEKIT_BUILD_COMMIT_INVALID: expected a full commit SHA");
45
+ }
46
+ return configured.toLowerCase();
47
+ }
48
+ const packaged = readPackageBuildIdentity();
49
+ if (packaged)
50
+ return packaged.commit;
43
51
  const repositoryRoot = findRepositoryRoot(dirname(fileURLToPath(import.meta.url)));
44
52
  if (!repositoryRoot)
45
53
  return "unknown";
@@ -85,6 +93,17 @@ function readFramekitCommit() {
85
93
  }
86
94
  return "unknown";
87
95
  }
96
+ function readPackageBuildIdentity() {
97
+ try {
98
+ const identityPath = join(dirname(fileURLToPath(import.meta.url)), "build-identity.json");
99
+ return parsePackageBuildIdentity(JSON.parse(readFileSync(identityPath, "utf8")), FRAMEKIT_VERSION);
100
+ }
101
+ catch (error) {
102
+ if (isMissingFile(error))
103
+ return undefined;
104
+ throw error;
105
+ }
106
+ }
88
107
  function findRepositoryRoot(start) {
89
108
  let directory = start;
90
109
  while (true) {
@@ -121,10 +121,14 @@ export class MediaAnalysisService {
121
121
  }
122
122
  async understandMedia(mediaId) {
123
123
  const project = await this.project.inspectProject();
124
+ return this.understandMediaInProject(mediaId, project, true);
125
+ }
126
+ async understandMediaInProject(mediaId, project, attachToLiveContext = false) {
124
127
  const media = findMedia(project, mediaId);
125
128
  const cached = await this.loadCachedUnderstanding(project, media);
126
129
  if (cached) {
127
- this.context.attachMediaUnderstanding(cached);
130
+ if (attachToLiveContext)
131
+ this.context.attachMediaUnderstanding(cached);
128
132
  return structuredClone(cached);
129
133
  }
130
134
  const input = { project, media };
@@ -160,7 +164,8 @@ export class MediaAnalysisService {
160
164
  ],
161
165
  analysisRevision: project.revision,
162
166
  };
163
- this.context.attachMediaUnderstanding(understanding);
167
+ if (attachToLiveContext)
168
+ this.context.attachMediaUnderstanding(understanding);
164
169
  await this.options.semanticMediaIndexStore?.save(understanding);
165
170
  return structuredClone(understanding);
166
171
  }
@@ -179,10 +184,15 @@ export class MediaAnalysisService {
179
184
  }
180
185
  async planRoughCut(request) {
181
186
  const project = await this.project.inspectProject();
187
+ return this.planRoughCutInProject(request, project);
188
+ }
189
+ async planRoughCutInProject(request, project) {
182
190
  const { maxShots: _maxShots, ...query } = request;
183
191
  const current = this.indexFromProject(project, query);
184
192
  const persisted = await this.persistedIndexEntries(query);
185
- return planRoughCut(mergeIndexEntries(persisted, current), project.revision, request);
193
+ const projectMedia = project.media.map(sourceIdentityOf);
194
+ const matchingPersisted = persisted.filter((entry) => projectMedia.some((source) => sameMediaSourceIdentity(source, entry.sourceIdentity)));
195
+ return planRoughCut(mergeIndexEntries(matchingPersisted, current), project.revision, request);
186
196
  }
187
197
  async inspectTimelineSemanticContext(query = {}) {
188
198
  const project = await this.project.inspectProject();
@@ -706,7 +716,7 @@ function emptySemanticDescription() {
706
716
  };
707
717
  }
708
718
  function matchesMediaIndexQuery(entry, query) {
709
- const text = query.query?.trim().toLowerCase();
719
+ const terms = query.query?.trim().toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
710
720
  const values = [
711
721
  entry.sourceIdentity.mediaId,
712
722
  entry.sourceIdentity.source,
@@ -717,7 +727,7 @@ function matchesMediaIndexQuery(entry, query) {
717
727
  ...entry.semantic.timeOfDay.map((tag) => tag.value),
718
728
  ...entry.semantic.moods.map((tag) => tag.value),
719
729
  ].map((value) => value.toLowerCase());
720
- if (text && !values.some((value) => value.includes(text)))
730
+ if (terms.length > 0 && !values.some((value) => terms.some((term) => value.includes(term))))
721
731
  return false;
722
732
  if (query.subject && !matchesTag(entry.semantic.subjects, query.subject))
723
733
  return false;
@@ -165,6 +165,9 @@ export class AgentVideoRuntime {
165
165
  async understandMedia(mediaId) {
166
166
  return this.media.understandMedia(mediaId);
167
167
  }
168
+ async understandMediaInProject(mediaId, project) {
169
+ return this.media.understandMediaInProject(mediaId, project);
170
+ }
168
171
  planDuration(request) {
169
172
  return this.durationPolicy.plan(request);
170
173
  }
@@ -180,6 +183,9 @@ export class AgentVideoRuntime {
180
183
  async planRoughCut(request) {
181
184
  return this.media.planRoughCut(request);
182
185
  }
186
+ async planRoughCutInProject(request, project) {
187
+ return this.media.planRoughCutInProject(request, project);
188
+ }
183
189
  async inspectTimelineSemanticContext(query = {}) {
184
190
  return this.media.inspectTimelineSemanticContext(query);
185
191
  }
@@ -386,8 +386,13 @@ function validateMediaMetadata(metadata, field) {
386
386
  if (stream.codec !== undefined)
387
387
  requireText(stream.codec, `${streamField}.codec`);
388
388
  if (stream.kind === "video") {
389
- requirePositiveInteger(stream.width, `${streamField}.width`);
390
- requirePositiveInteger(stream.height, `${streamField}.height`);
389
+ if ((stream.width === undefined) !== (stream.height === undefined)) {
390
+ throw new Error(`TIMELINE_IR_INVALID: ${streamField}.width and height must be provided together`);
391
+ }
392
+ if (stream.width !== undefined && stream.height !== undefined) {
393
+ requirePositiveInteger(stream.width, `${streamField}.width`);
394
+ requirePositiveInteger(stream.height, `${streamField}.height`);
395
+ }
391
396
  if (!stream.frameRate)
392
397
  throw new Error(`TIMELINE_IR_INVALID: ${streamField}.frameRate is required`);
393
398
  validateRational(stream.frameRate, `${streamField}.frameRate`, true);