@morshoto/framekit 0.1.17 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +25 -14
  2. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  7. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
  10. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  11. package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
  12. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  14. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  15. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
  18. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
  19. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
  21. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  22. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  23. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  24. package/dist-package/apps/cli/src/main.js +76 -19
  25. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  26. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  27. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  28. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  29. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  30. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  31. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  32. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  33. package/dist-package/apps/mcp-server/src/main.js +50 -21
  34. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  35. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  36. package/dist-package/apps/mcp-server/src/server.js +986 -180
  37. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  38. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  39. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  40. package/dist-package/apps/mcp-server/src/version.js +21 -2
  41. package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
  42. package/dist-package/packages/headless-application/src/index.js +1 -0
  43. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  44. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  45. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  46. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  47. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  48. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  49. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  50. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  51. package/dist-package/packages/runtime/src/index.js +1 -0
  52. package/dist-package/packages/runtime/src/runtime.js +22 -7
  53. package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
  54. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  55. package/dist-package/packages/testkit/src/index.js +1 -0
  56. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  57. package/package.json +36 -14
  58. package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
@@ -1,16 +1,19 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
3
3
  import { dirname, join } from "node:path";
4
+ import { types as utilTypes } from "node:util";
4
5
  import { timelineIrDigest, validateTimelineIr } from "../../../packages/runtime/src/index.js";
5
- import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ import { compileTimelineIrToFcpxml, FinalCutBackgroundMaterializationPublisher, validateFinalCutBackgroundMaterializationRequest, } from "../../../adapters/final-cut/typescript/src/index.js";
6
7
  export class SessionMaterializationJobs {
7
8
  directory;
8
9
  sessions;
9
10
  publisher;
10
- constructor(directory, sessions, publisher) {
11
+ recoveryGuard;
12
+ constructor(directory, sessions, publisher, recoveryGuard) {
11
13
  this.directory = directory;
12
14
  this.sessions = sessions;
13
15
  this.publisher = publisher;
16
+ this.recoveryGuard = recoveryGuard;
14
17
  }
15
18
  async preview(sessionId, target) {
16
19
  const session = await this.sessions.loadForMaterialization(sessionId);
@@ -168,12 +171,20 @@ export class SessionMaterializationJobs {
168
171
  const claim = await this.claim(job);
169
172
  if (!claim.owned)
170
173
  return claim.job;
171
- const claimed = claim.job;
174
+ let claimed = claim.job;
175
+ let reservation;
176
+ let providerRequested = false;
177
+ // Do not evaluate provider properties before acquiring the reservation.
178
+ let dispatched = false;
172
179
  try {
173
180
  const finalFailure = await this.validateStagedJob(claimed);
174
181
  if (finalFailure)
175
182
  return this.fail(claimed, finalFailure);
176
- const result = await this.publisher.publish({
183
+ if (claimed.destination.mode !== "versioned")
184
+ return this.fail(claimed, {
185
+ code: "MATERIALIZATION_DESTINATION_INVALID", message: "Versioned destination required", retryable: false, providerRequested: false,
186
+ });
187
+ const request = {
177
188
  jobId: claimed.jobId,
178
189
  artifactPath: claimed.artifactPath,
179
190
  artifactDigest: claimed.artifactDigest,
@@ -186,12 +197,85 @@ export class SessionMaterializationJobs {
186
197
  baseRevision: structuredClone(claimed.baseRevision),
187
198
  coverage: structuredClone(claimed.coverage),
188
199
  provenance: structuredClone(claimed.provenance),
189
- });
200
+ };
201
+ try {
202
+ // The built-in adapter's pure request checks must run before the
203
+ // dispatch boundary, while the staged request is still inert data.
204
+ validateFinalCutBackgroundMaterializationRequest(request);
205
+ }
206
+ catch (error) {
207
+ return this.fail(claimed, materializationFailure(error, false));
208
+ }
209
+ // This check invokes no provider operation and is limited to the exact
210
+ // built-in implementation. Custom providers remain untrusted.
211
+ if (hasInertUnavailableMaterializationOptions(this.publisher)) {
212
+ const blocked = {
213
+ ...claimed, state: "blocked", nextAction: "retry", claim: undefined,
214
+ verification: { tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest,
215
+ desiredDigest: claimed.desiredDigest, reason: "No non-UI materialization capability is configured; the provider was not called" },
216
+ error: { code: "FINAL_CUT_BACKGROUND_MATERIALIZATION_UNAVAILABLE", message: "No explicit non-UI Final Cut materialization capability is configured", retryable: true },
217
+ };
218
+ await this.save(blocked);
219
+ return blocked;
220
+ }
221
+ if (this.recoveryGuard) {
222
+ try {
223
+ const id = createHash("sha256").update(claimed.jobId).digest("hex");
224
+ reservation = await this.recoveryGuard.beginNative(`native.materialize.${id}`, {
225
+ kind: "materialization", jobId: claimed.jobId, dispatchId: randomUUID(),
226
+ requestedTarget: { libraryUid: claimed.target.libraryUid, eventUid: claimed.target.eventUid,
227
+ projectUid: claimed.target.projectUid, sequenceUid: claimed.target.sequenceUid },
228
+ artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
229
+ destination: { ...structuredClone(claimed.destination), mode: "versioned" },
230
+ executorIdentity: null, nativeQuiescence: "unproven",
231
+ });
232
+ }
233
+ catch {
234
+ const blocked = {
235
+ ...claimed, state: "blocked", nextAction: "retry", claim: undefined,
236
+ verification: {
237
+ tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
238
+ reason: "An unresolved native reservation prevents materialization; the provider was not called",
239
+ },
240
+ error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "An unresolved native reservation prevents materialization; the provider was not called", retryable: true },
241
+ };
242
+ await this.save(blocked);
243
+ return blocked;
244
+ }
245
+ claimed = { ...claimed, recoveryReservation: { reservationId: reservation.reservationId, reason: "native-quiescence-unproven" } };
246
+ await this.save(claimed);
247
+ }
248
+ const invoke = async () => {
249
+ const intent = {
250
+ ...claimed, providerRequestPhase: "dispatch-intent",
251
+ evidence: { ...claimed.evidence, providerRequested: true },
252
+ };
253
+ await this.save(intent);
254
+ claimed = intent;
255
+ providerRequested = true;
256
+ return this.publisher.publish(request);
257
+ };
258
+ // A tracker is executable provider code. It may defer invoking the
259
+ // supplied operation even if it returns or throws first.
260
+ dispatched = true;
261
+ // Persist uncertainty before executing even the tracker: untrusted
262
+ // tracker code may invoke or defer the provider without acknowledgement.
263
+ if (reservation)
264
+ await reservation.markDispatchPossible();
265
+ const result = this.publisher.trackNativeDispatch
266
+ ? await this.publisher.trackNativeDispatch(invoke, () => { dispatched = true; })
267
+ : await invoke();
268
+ claimed = { ...claimed, providerRequestPhase: "returned" };
269
+ if (reservation && !providerRequested && !dispatched) {
270
+ await reservation.release();
271
+ reservation = undefined;
272
+ claimed = { ...claimed, recoveryReservation: undefined };
273
+ }
190
274
  if (result.state === "blocked") {
191
275
  const blocked = {
192
276
  ...claimed,
193
277
  state: "blocked",
194
- nextAction: "retry",
278
+ nextAction: claimed.recoveryReservation ? "none" : "retry",
195
279
  claim: undefined,
196
280
  evidence: { ...claimed.evidence, providerRequested: true },
197
281
  verification: {
@@ -202,7 +286,10 @@ export class SessionMaterializationJobs {
202
286
  reason: result.message,
203
287
  ...(result.delivery ? { delivery: result.delivery } : { delivery: deliveryEvidenceForBlockedCode(result.code) }),
204
288
  },
205
- error: { code: result.code, message: result.message, retryable: result.retryable },
289
+ ...(claimed.recoveryReservation ? { providerError: { code: result.code, message: result.message, retryable: result.retryable } } : {}),
290
+ error: claimed.recoveryReservation
291
+ ? { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Materialization may have been dispatched; native quiescence is unproven and it must not be retried", retryable: false }
292
+ : { code: result.code, message: result.message, retryable: result.retryable },
206
293
  };
207
294
  await this.save(blocked);
208
295
  return blocked;
@@ -260,11 +347,22 @@ export class SessionMaterializationJobs {
260
347
  reason: "Canonical readback verified this handoff once. Re-read the materialized target before later edits to detect subsequent manual Final Cut changes.",
261
348
  },
262
349
  };
263
- await this.save(completed);
264
- return completed;
350
+ const outcome = claimed.recoveryReservation
351
+ ? {
352
+ ...completed, state: "blocked", nextAction: "none",
353
+ error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Canonical readback was verified but native quiescence is unproven; do not retry publication", retryable: false },
354
+ continuation: { state: "canonical-resync-required", reason: "Recovery is required before a fresh canonical session can be created from this verified readback." },
355
+ }
356
+ : completed;
357
+ await this.save(outcome);
358
+ return outcome;
265
359
  }
266
360
  catch (error) {
267
- return this.fail(claimed, materializationFailure(error, true));
361
+ if (reservation && !providerRequested && !dispatched) {
362
+ await reservation.release();
363
+ claimed = { ...claimed, recoveryReservation: undefined };
364
+ }
365
+ return this.fail(claimed, materializationFailure(error, providerRequested || claimed.evidence.providerRequested));
268
366
  }
269
367
  finally {
270
368
  await this.release(claimed.jobId, claimed.claim.id);
@@ -538,6 +636,41 @@ function collectStructuralChanges(before, after, path, changes) {
538
636
  }
539
637
  changes.push({ path, ...(before !== undefined ? { before } : {}), ...(after !== undefined ? { after } : {}) });
540
638
  }
639
+ // Only inspect own data properties on ordinary, non-proxy objects. Calling
640
+ // isAvailable() here could execute a caller-supplied getter before a native
641
+ // reservation exists, so every unfamiliar shape must take the guarded path.
642
+ const builtinStringTrim = String.prototype.trim;
643
+ const builtinMaterializationMethods = new Map([
644
+ ["publish", FinalCutBackgroundMaterializationPublisher.prototype.publish],
645
+ ["trackNativeDispatch", FinalCutBackgroundMaterializationPublisher.prototype.trackNativeDispatch],
646
+ ["isAvailable", FinalCutBackgroundMaterializationPublisher.prototype.isAvailable],
647
+ ]);
648
+ function hasInertUnavailableMaterializationOptions(publisher) {
649
+ if (utilTypes.isProxy(publisher) || Object.getPrototypeOf(publisher) !== FinalCutBackgroundMaterializationPublisher.prototype)
650
+ return false;
651
+ for (const [name, method] of builtinMaterializationMethods) {
652
+ if (Object.getOwnPropertyDescriptor(publisher, name)
653
+ || Object.getOwnPropertyDescriptor(FinalCutBackgroundMaterializationPublisher.prototype, name)?.value !== method)
654
+ return false;
655
+ }
656
+ const optionsProperty = Object.getOwnPropertyDescriptor(publisher, "options");
657
+ if (!optionsProperty || !("value" in optionsProperty))
658
+ return false;
659
+ const options = optionsProperty.value;
660
+ if (!options || typeof options !== "object" || utilTypes.isProxy(options))
661
+ return false;
662
+ const prototype = Object.getPrototypeOf(options);
663
+ if (prototype !== null && prototype !== Object.prototype)
664
+ return false;
665
+ if (prototype && (Object.getOwnPropertyDescriptor(prototype, "executor") || Object.getOwnPropertyDescriptor(prototype, "command")))
666
+ return false;
667
+ const executor = Object.getOwnPropertyDescriptor(options, "executor");
668
+ const command = Object.getOwnPropertyDescriptor(options, "command");
669
+ if ((executor && (!("value" in executor) || executor.value !== undefined)) || (command && !("value" in command)))
670
+ return false;
671
+ const value = command?.value;
672
+ return value === undefined || value === null || (typeof value === "string" && builtinStringTrim.call(value) === "");
673
+ }
541
674
  function isRecord(value) {
542
675
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
543
676
  }
@@ -250,6 +250,8 @@ function routingReadiness(context) {
250
250
  nextAction: readiness.nextAction,
251
251
  retryable: readiness.retryable,
252
252
  ...(readiness.firstMissing ? { firstMissing: readiness.firstMissing } : {}),
253
+ ...(readiness.targetKind ? { targetKind: readiness.targetKind } : {}),
254
+ ...(readiness.targetBound !== undefined ? { targetBound: readiness.targetBound } : {}),
253
255
  guidance: readiness.guidance,
254
256
  };
255
257
  }