@morshoto/framekit 0.1.14 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +75 -3
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +443 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +139 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +22 -1
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +214 -31
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/index.js +6 -0
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +143 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
import { createFramekitRenderPlan, } from "./render-contract.js";
|
|
2
|
+
/**
|
|
3
|
+
* Owns the closed loop: immutable plan, provider render, then an independent
|
|
4
|
+
* artifact verification gate. Provider success alone never yields `passed`.
|
|
5
|
+
*/
|
|
6
|
+
export async function renderAndVerifyFramekitProject(request, provider, verifier, options = {}) {
|
|
7
|
+
let plan;
|
|
8
|
+
try {
|
|
9
|
+
const capabilities = options.capabilities ?? provider.capabilities(request);
|
|
10
|
+
plan = createFramekitRenderPlan(request, capabilities);
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
return failureResult(error, options.isUnavailable);
|
|
14
|
+
}
|
|
15
|
+
let render;
|
|
16
|
+
try {
|
|
17
|
+
render = await provider.render(plan);
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
return { ...failureResult(error, options.isUnavailable), plan };
|
|
21
|
+
}
|
|
22
|
+
const binding = checkRenderBinding(plan, render);
|
|
23
|
+
if (!binding.passed) {
|
|
24
|
+
return {
|
|
25
|
+
status: "failed",
|
|
26
|
+
plan,
|
|
27
|
+
render,
|
|
28
|
+
verification: { status: "failed", checks: [binding] },
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
let verification;
|
|
32
|
+
try {
|
|
33
|
+
verification = await verifier.verify(plan, render);
|
|
34
|
+
}
|
|
35
|
+
catch (error) {
|
|
36
|
+
return {
|
|
37
|
+
status: "failed",
|
|
38
|
+
plan,
|
|
39
|
+
render,
|
|
40
|
+
verification: {
|
|
41
|
+
status: "failed",
|
|
42
|
+
checks: [],
|
|
43
|
+
error: errorDetails(error),
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
if (verification.status !== "passed" || !verification.artifact) {
|
|
48
|
+
if (verification.status === "passed" && !verification.artifact) {
|
|
49
|
+
const invalidVerification = {
|
|
50
|
+
...verification,
|
|
51
|
+
status: "failed",
|
|
52
|
+
checks: [...verification.checks, {
|
|
53
|
+
name: "artifact",
|
|
54
|
+
passed: false,
|
|
55
|
+
detail: "a passed render verification must include artifact metadata",
|
|
56
|
+
}],
|
|
57
|
+
error: { code: "RENDER_VERIFICATION_CONTRACT_INVALID", message: "passed verification omitted artifact metadata" },
|
|
58
|
+
};
|
|
59
|
+
return { status: "failed", plan, render, verification: invalidVerification };
|
|
60
|
+
}
|
|
61
|
+
return { status: verification.status, plan, render, verification };
|
|
62
|
+
}
|
|
63
|
+
const semanticChecks = await Promise.all((options.semanticAssertions ?? []).map(async (assertion) => {
|
|
64
|
+
try {
|
|
65
|
+
const value = await assertion.verify({ plan, result: render, artifact: verification.artifact });
|
|
66
|
+
return typeof value === "boolean"
|
|
67
|
+
? { name: assertion.name, passed: value, detail: value ? "semantic assertion passed" : "semantic assertion failed" }
|
|
68
|
+
: { ...value, name: value.name || assertion.name };
|
|
69
|
+
}
|
|
70
|
+
catch (error) {
|
|
71
|
+
return { name: assertion.name, passed: false, detail: errorDetails(error).message };
|
|
72
|
+
}
|
|
73
|
+
}));
|
|
74
|
+
const checks = [...verification.checks, ...semanticChecks];
|
|
75
|
+
const passed = checks.every((check) => check.passed);
|
|
76
|
+
return {
|
|
77
|
+
status: passed ? "passed" : "failed",
|
|
78
|
+
plan,
|
|
79
|
+
render,
|
|
80
|
+
verification: { ...verification, status: passed ? "passed" : "failed", checks },
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
function checkRenderBinding(plan, result) {
|
|
84
|
+
const passed = result.contractVersion === plan.contractVersion
|
|
85
|
+
&& sameTarget(plan.target, result.target)
|
|
86
|
+
&& sameRevision(plan.projectRevision, result.projectRevision)
|
|
87
|
+
&& result.renderer.id === plan.renderer.id
|
|
88
|
+
&& result.renderer.version === plan.renderer.version
|
|
89
|
+
&& result.planDigest === plan.planDigest
|
|
90
|
+
&& result.output.path === plan.parameters.outputPath
|
|
91
|
+
&& result.output.format === plan.parameters.format
|
|
92
|
+
&& result.verificationRequired === true;
|
|
93
|
+
return {
|
|
94
|
+
name: "render-binding",
|
|
95
|
+
passed,
|
|
96
|
+
detail: passed
|
|
97
|
+
? "render output is bound to the requested target, revision, renderer, plan, and format"
|
|
98
|
+
: "render output provenance does not match the requested plan",
|
|
99
|
+
expected: {
|
|
100
|
+
target: plan.target,
|
|
101
|
+
projectRevision: plan.projectRevision,
|
|
102
|
+
renderer: plan.renderer,
|
|
103
|
+
planDigest: plan.planDigest,
|
|
104
|
+
output: plan.parameters,
|
|
105
|
+
},
|
|
106
|
+
observed: result,
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
function failureResult(error, isUnavailable) {
|
|
110
|
+
const details = errorDetails(error);
|
|
111
|
+
const unavailable = isUnavailable?.(error) ?? /UNAVAILABLE|CAPABILITY_UNAVAILABLE|unsupported/i.test(`${details.code} ${details.message}`);
|
|
112
|
+
return { status: unavailable ? "unavailable" : "failed", error: details };
|
|
113
|
+
}
|
|
114
|
+
function errorDetails(error) {
|
|
115
|
+
if (error instanceof Error) {
|
|
116
|
+
const match = /^([A-Z][A-Z0-9_]+):\s*(.*)$/.exec(error.message);
|
|
117
|
+
return { code: match?.[1] ?? error.name, message: match?.[2] ?? error.message };
|
|
118
|
+
}
|
|
119
|
+
return { code: "RENDER_ORCHESTRATION_FAILED", message: String(error) };
|
|
120
|
+
}
|
|
121
|
+
function sameTarget(left, right) {
|
|
122
|
+
return left.projectId === right.projectId && left.sequenceId === right.sequenceId;
|
|
123
|
+
}
|
|
124
|
+
function sameRevision(left, right) {
|
|
125
|
+
return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
|
|
126
|
+
}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { validateTimelineIr } from "../timeline/editing-session.js";
|
|
3
|
+
import { parseRational } from "../timeline/rational-time.js";
|
|
4
|
+
export const FRAMEKIT_RENDER_CONTRACT_VERSION = 1;
|
|
5
|
+
export class FramekitRenderContractError extends Error {
|
|
6
|
+
code;
|
|
7
|
+
constructor(code, message) {
|
|
8
|
+
super(`${code}: ${message}`);
|
|
9
|
+
this.code = code;
|
|
10
|
+
this.name = "FramekitRenderContractError";
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
export function createFramekitRenderRequest(input) {
|
|
14
|
+
validateTimelineIr(input.timeline);
|
|
15
|
+
if (!text(input.target?.projectId) || !text(input.target?.sequenceId)) {
|
|
16
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "target requires projectId and sequenceId");
|
|
17
|
+
}
|
|
18
|
+
if (input.target.projectId !== input.timeline.project.id || input.target.sequenceId !== input.timeline.sequence.id) {
|
|
19
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "target does not match the Timeline IR");
|
|
20
|
+
}
|
|
21
|
+
if (input.revision && !sameRevision(input.revision, input.timeline.revision)) {
|
|
22
|
+
throw new FramekitRenderContractError("RENDER_STALE_REVISION", "requested revision does not match the Timeline IR");
|
|
23
|
+
}
|
|
24
|
+
validateParameters(input.parameters);
|
|
25
|
+
const requiredFeatures = [...new Set([
|
|
26
|
+
...inferFramekitRenderFeatures(input.timeline),
|
|
27
|
+
...(input.requiredFeatures ?? []),
|
|
28
|
+
])];
|
|
29
|
+
for (const feature of requiredFeatures) {
|
|
30
|
+
if (!RENDER_FEATURES.includes(feature))
|
|
31
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", `unsupported required feature: ${feature}`);
|
|
32
|
+
}
|
|
33
|
+
return deepFreeze({
|
|
34
|
+
contractVersion: FRAMEKIT_RENDER_CONTRACT_VERSION,
|
|
35
|
+
target: structuredClone(input.target),
|
|
36
|
+
projectRevision: structuredClone(input.timeline.revision),
|
|
37
|
+
timeline: structuredClone(input.timeline),
|
|
38
|
+
parameters: structuredClone(input.parameters),
|
|
39
|
+
requiredFeatures,
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
export function inferFramekitRenderFeatures(timeline) {
|
|
43
|
+
const features = ["local-media", "structural-edits"];
|
|
44
|
+
if (timeline.sequence.occurrences.some(({ gainDb }) => gainDb !== undefined))
|
|
45
|
+
features.push("audio-gain");
|
|
46
|
+
if (timeline.sequence.occurrences.some(({ transform }) => transform !== undefined))
|
|
47
|
+
features.push("transform");
|
|
48
|
+
if ((timeline.sequence.titles ?? []).length > 0)
|
|
49
|
+
features.push("titles");
|
|
50
|
+
if ((timeline.sequence.transitions ?? []).some(({ kind }) => kind === "cross-dissolve"))
|
|
51
|
+
features.push("cross-dissolve");
|
|
52
|
+
return features;
|
|
53
|
+
}
|
|
54
|
+
export function createFramekitRenderPlan(request, capabilities) {
|
|
55
|
+
if (!text(capabilities.renderer?.id) || !text(capabilities.renderer?.version)) {
|
|
56
|
+
throw new FramekitRenderContractError("RENDER_INVALID_RESULT", "renderer identity and version are required");
|
|
57
|
+
}
|
|
58
|
+
const unavailable = request.requiredFeatures.filter((feature) => capabilities.features[feature] !== "supported");
|
|
59
|
+
if (unavailable.length > 0) {
|
|
60
|
+
throw new FramekitRenderContractError("RENDER_CAPABILITY_UNAVAILABLE", `required features are not fully supported: ${unavailable.join(", ")}`);
|
|
61
|
+
}
|
|
62
|
+
const planBase = {
|
|
63
|
+
contractVersion: FRAMEKIT_RENDER_CONTRACT_VERSION,
|
|
64
|
+
target: structuredClone(request.target),
|
|
65
|
+
projectRevision: structuredClone(request.projectRevision),
|
|
66
|
+
timeline: structuredClone(request.timeline),
|
|
67
|
+
parameters: structuredClone(request.parameters),
|
|
68
|
+
requiredFeatures: [...request.requiredFeatures],
|
|
69
|
+
renderer: structuredClone(capabilities.renderer),
|
|
70
|
+
capabilities: structuredClone(capabilities),
|
|
71
|
+
};
|
|
72
|
+
const plan = {
|
|
73
|
+
...planBase,
|
|
74
|
+
planDigest: createHash("sha256").update(stableJson(planBase)).digest("hex"),
|
|
75
|
+
};
|
|
76
|
+
return deepFreeze(plan);
|
|
77
|
+
}
|
|
78
|
+
export function createFramekitRenderResult(plan, output) {
|
|
79
|
+
assertPlanIntegrity(plan);
|
|
80
|
+
if (!text(output.path) || output.path !== plan.parameters.outputPath || output.format !== plan.parameters.format) {
|
|
81
|
+
throw new FramekitRenderContractError("RENDER_INVALID_RESULT", "render output must match the explicit request format and path");
|
|
82
|
+
}
|
|
83
|
+
return {
|
|
84
|
+
contractVersion: FRAMEKIT_RENDER_CONTRACT_VERSION,
|
|
85
|
+
status: "rendered",
|
|
86
|
+
target: structuredClone(plan.target),
|
|
87
|
+
projectRevision: structuredClone(plan.projectRevision),
|
|
88
|
+
renderer: structuredClone(plan.renderer),
|
|
89
|
+
planDigest: plan.planDigest,
|
|
90
|
+
output: structuredClone(output),
|
|
91
|
+
verificationRequired: true,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
const RENDER_FEATURES = [
|
|
95
|
+
"local-media",
|
|
96
|
+
"structural-edits",
|
|
97
|
+
"audio-gain",
|
|
98
|
+
"transform",
|
|
99
|
+
"titles",
|
|
100
|
+
"cross-dissolve",
|
|
101
|
+
];
|
|
102
|
+
function validateParameters(parameters) {
|
|
103
|
+
if (!parameters || typeof parameters !== "object" || !text(parameters.outputPath)) {
|
|
104
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "outputPath is required");
|
|
105
|
+
}
|
|
106
|
+
if (parameters.format !== "mp4" && parameters.format !== "mov") {
|
|
107
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "format must be mp4 or mov");
|
|
108
|
+
}
|
|
109
|
+
if (!Number.isSafeInteger(parameters.width) || parameters.width <= 0 || !Number.isSafeInteger(parameters.height) || parameters.height <= 0) {
|
|
110
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "width and height must be positive safe integers");
|
|
111
|
+
}
|
|
112
|
+
const frameRate = parseRational(parameters.frameRate, "RENDER_INVALID_REQUEST");
|
|
113
|
+
if (frameRate.value <= 0n)
|
|
114
|
+
throw new FramekitRenderContractError("RENDER_INVALID_REQUEST", "frameRate must be positive");
|
|
115
|
+
}
|
|
116
|
+
function sameRevision(left, right) {
|
|
117
|
+
return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
|
|
118
|
+
}
|
|
119
|
+
function text(value) {
|
|
120
|
+
return typeof value === "string" && value.trim().length > 0;
|
|
121
|
+
}
|
|
122
|
+
function stableJson(value) {
|
|
123
|
+
if (value === null || typeof value !== "object")
|
|
124
|
+
return JSON.stringify(value);
|
|
125
|
+
if (Array.isArray(value))
|
|
126
|
+
return `[${value.map(stableJson).join(",")}]`;
|
|
127
|
+
const entries = Object.entries(value).filter(([, child]) => child !== undefined).sort(([left], [right]) => left.localeCompare(right));
|
|
128
|
+
return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
|
|
129
|
+
}
|
|
130
|
+
function assertPlanIntegrity(plan) {
|
|
131
|
+
const { planDigest, ...planBase } = plan;
|
|
132
|
+
const actualDigest = createHash("sha256").update(stableJson(planBase)).digest("hex");
|
|
133
|
+
if (actualDigest !== planDigest) {
|
|
134
|
+
throw new FramekitRenderContractError("RENDER_INVALID_RESULT", "render plan was modified after it was created");
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
function deepFreeze(value) {
|
|
138
|
+
if (value === null || typeof value !== "object" || Object.isFrozen(value))
|
|
139
|
+
return value;
|
|
140
|
+
for (const child of Object.values(value))
|
|
141
|
+
deepFreeze(child);
|
|
142
|
+
return Object.freeze(value);
|
|
143
|
+
}
|