@morshoto/framekit 0.1.18 → 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 (51) hide show
  1. package/README.md +17 -12
  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 +538 -77
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  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 +22 -8
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +27 -2
  11. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  14. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +1 -0
  15. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  16. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +3 -1
  18. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  19. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +32 -14
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  21. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  22. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  23. package/dist-package/apps/cli/src/main.js +42 -0
  24. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  25. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  26. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  27. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  28. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  29. package/dist-package/apps/mcp-server/src/main.js +24 -19
  30. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  31. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  32. package/dist-package/apps/mcp-server/src/server.js +737 -152
  33. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  34. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  35. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  36. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +391 -58
  37. package/dist-package/packages/headless-application/src/index.js +1 -0
  38. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  39. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  40. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  41. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  42. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  43. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  44. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  45. package/dist-package/packages/runtime/src/index.js +1 -0
  46. package/dist-package/packages/runtime/src/runtime.js +16 -7
  47. package/dist-package/packages/runtime/src/timeline/editing-session.js +16 -0
  48. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  49. package/dist-package/packages/testkit/src/index.js +1 -0
  50. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  51. package/package.json +32 -10
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "0.1.18",
4
- "commit": "cc0fc08ebc4ecf62897918d93a54dd35a7c73bf3"
3
+ "version": "0.2.2",
4
+ "commit": "3af4f3f6cc6b31ddb309c9a32f62d9d4de6bc9fd"
5
5
  }
@@ -0,0 +1,18 @@
1
+ export function createCanonicalNativeSnapshotReader(readLiveState, readSnapshot) {
2
+ return async () => {
3
+ const live = await readLiveState();
4
+ const project = live.project;
5
+ const sequence = live.sequence;
6
+ if (!project?.id || project.id.startsWith("final-cut:")
7
+ || !project.name.trim() || !sequence?.id || sequence.id.startsWith("final-cut:")
8
+ || !sequence.name.trim()) {
9
+ throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
10
+ }
11
+ return readSnapshot({
12
+ projectId: project.id,
13
+ sequenceId: sequence.id,
14
+ projectName: project.name,
15
+ sequenceName: sequence.name,
16
+ });
17
+ };
18
+ }
@@ -0,0 +1,3 @@
1
+ export function shouldConfigureFinalCutProjectPublisher(input) {
2
+ return input.liveMode && (Boolean(input.fcpxmlPath) || input.canonicalNativeProviderEnabled);
3
+ }
@@ -2,13 +2,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
2
2
  import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
5
- import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, FinalCutSqliteInspectionProvider, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FileCanonicalRecoveryGuard, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
6
6
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
7
7
  import { AgentVideoRuntime, JsonSemanticMediaIndexStore } from "../../../packages/runtime/src/index.js";
8
+ import { HeadlessProjectService } from "../../../packages/headless-application/src/index.js";
8
9
  import { createMcpServer } from "./server.js";
9
10
  import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
10
- import { HeadlessProjectService } from "./headless-projects.js";
11
+ import { createCanonicalNativeSnapshotReader } from "./canonical-native-snapshot.js";
11
12
  import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
13
+ import { shouldConfigureFinalCutProjectPublisher } from "./final-cut-runtime-config.js";
12
14
  const fixture = new InMemoryEditorAdapter({
13
15
  projectId: "project-1",
14
16
  projectName: "Phase 2 Fixture",
@@ -53,6 +55,7 @@ const fixture = new InMemoryEditorAdapter({
53
55
  },
54
56
  }],
55
57
  });
58
+ const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
56
59
  const liveMode = process.env.FRAMEKIT_EDITOR === "final-cut-live";
57
60
  const headlessFinalCut = liveMode && process.env.FRAMEKIT_FINAL_CUT_HEADLESS === "1";
58
61
  const fcpxmlPath = liveMode ? process.env.FRAMEKIT_FCPXML_PATH : undefined;
@@ -68,7 +71,11 @@ const canonicalProviderRequired = liveMode
68
71
  && !canonicalNativeProviderEnabled;
69
72
  assertCanonicalProviderConfiguration({ required: canonicalProviderRequired || canonicalNativeProviderEnabled, fcpxmlPath });
70
73
  const connection = liveMode
71
- ? new FinalCutConnectionManager({ headless: headlessFinalCut, canonicalProviderRequired })
74
+ ? new FinalCutConnectionManager({
75
+ headless: headlessFinalCut,
76
+ canonicalProviderRequired,
77
+ existingSocketOnly: process.env.FRAMEKIT_FINAL_CUT_EXISTING_SOCKET_ONLY === "1",
78
+ })
72
79
  : undefined;
73
80
  const autoConnect = liveMode && process.env.FRAMEKIT_AUTO_CONNECT !== "0";
74
81
  if (autoConnect)
@@ -95,8 +102,12 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
95
102
  const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
96
103
  ? createFinalCutNativeTargetResolver(nativeEditor)
97
104
  : undefined;
105
+ const canonicalRecovery = liveMode
106
+ ? new FileCanonicalRecoveryGuard(join(framekitStateDirectory, "canonical-recovery", "pending.json"))
107
+ : undefined;
98
108
  const canonicalNativeProvider = canonicalNativeProviderEnabled
99
109
  ? new FinalCutCanonicalNativeProvider({
110
+ recoveryGuard: canonicalRecovery,
100
111
  live: liveAdapter,
101
112
  native: {
102
113
  renameSelectedClip: async (name) => {
@@ -125,17 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
125
136
  return { undone: result.undone, verification: result.verification };
126
137
  },
127
138
  },
128
- readSnapshot: async () => {
129
- const live = await liveAdapter.readLiveState();
130
- const projectId = live.project?.id;
131
- const sequenceId = live.sequence?.id;
132
- if (!projectId || projectId.startsWith("final-cut:") || !sequenceId || sequenceId.startsWith("final-cut:")) {
133
- throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
134
- }
135
- return new FinalCutCanonicalSnapshotSource({
136
- target: { projectId, projectUid: projectId, sequenceId },
137
- }).readSnapshot();
138
- },
139
+ readSnapshot: createCanonicalNativeSnapshotReader(() => liveAdapter.readLiveState(), (target) => new FinalCutCanonicalSnapshotSource({ readbackTarget: target }).readSnapshot()),
139
140
  resolveTarget: canonicalNativeTargetResolver,
140
141
  backgroundCatalog: backgroundLibraryProvider,
141
142
  })
@@ -164,7 +165,6 @@ const editor = liveMode
164
165
  : {}),
165
166
  })
166
167
  : fixture;
167
- const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
168
168
  const analyzers = liveMode
169
169
  ? createCommandAnalyzers({
170
170
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
@@ -187,11 +187,11 @@ const runtime = new AgentVideoRuntime(editor, {
187
187
  });
188
188
  const headlessProjects = new HeadlessProjectService({
189
189
  directory: join(framekitStateDirectory, "projects"),
190
+ protectedStateDirectory: framekitStateDirectory,
190
191
  mediaProbe: new FfmpegMediaMetadataProbe(),
191
192
  renderer: new FfmpegTimelineRenderer(),
192
193
  verifier: new FfmpegRenderVerifier(),
193
194
  });
194
- const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
195
195
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
196
196
  ? new DisposableNativeEditWorkflow({
197
197
  native: nativeEditor,
@@ -206,12 +206,17 @@ const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeE
206
206
  })
207
207
  : undefined;
208
208
  const nativeOperationSession = disposableNative && nativeEditor
209
- ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor })
209
+ ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor, recoveryGuard: canonicalRecovery })
210
210
  : undefined;
211
- const projectPublisher = liveMode && fcpxmlPath
211
+ const projectPublisher = shouldConfigureFinalCutProjectPublisher({
212
+ liveMode,
213
+ fcpxmlPath,
214
+ canonicalNativeProviderEnabled,
215
+ })
212
216
  ? new FinalCutProjectPublisher({
213
217
  enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
214
218
  sourcePath: fcpxmlPath,
219
+ publishJobDirectory: join(framekitStateDirectory, "publish-jobs"),
215
220
  publishJobsDirectory: join(framekitStateDirectory, "publish-jobs"),
216
221
  documentDelivery: liveAdapter,
217
222
  publishRoute: parseFinalCutProjectPublishRoute(process.env.FRAMEKIT_FINAL_CUT_PUBLISH_ROUTE, Boolean(liveAdapter)),
@@ -262,6 +267,7 @@ const server = createMcpServer(runtime, {
262
267
  disposableNative,
263
268
  nativeOperationSession,
264
269
  projectPublisher,
270
+ canonicalRecovery,
265
271
  ...(sessionMaterializationPublisher?.isAvailable() ? { sessionMaterializationPublisher } : {}),
266
272
  videoExporter,
267
273
  requireBuildAlignment: process.env.FRAMEKIT_REQUIRE_BUILD_ALIGNMENT === "1",
@@ -271,7 +277,6 @@ const server = createMcpServer(runtime, {
271
277
  sessionDirectory: join(framekitStateDirectory, "sessions"),
272
278
  sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
273
279
  materializationDirectory: join(framekitStateDirectory, "materializations"),
274
- sqliteObservationProvider,
275
280
  headlessProjects,
276
281
  });
277
282
  const transport = new StdioServerTransport();
@@ -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
  }