@morshoto/framekit 0.1.10 → 0.1.12

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 (31) hide show
  1. package/README.md +1 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
  3. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
  7. package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
  11. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  12. package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
  13. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
  14. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  15. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  16. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  18. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  19. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  20. package/dist-package/apps/mcp-server/src/main.js +36 -2
  21. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  23. package/dist-package/apps/mcp-server/src/server.js +146 -12
  24. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  25. package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
  26. package/dist-package/packages/runtime/src/index.js +2 -0
  27. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  28. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  29. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  30. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  31. package/package.json +10 -6
@@ -0,0 +1,174 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { execFile as execFileCallback } from "node:child_process";
3
+ import { copyFile, cp, mkdir, readdir, realpath, stat } from "node:fs/promises";
4
+ import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
5
+ import { promisify } from "node:util";
6
+ import { assertFinalCutSchemaFingerprint, buildFinalCutSchemaFingerprint, } from "./sqlite-experiment.js";
7
+ const execFile = promisify(execFileCallback);
8
+ /**
9
+ * Experimental writer for disposable shadow copies only. It intentionally has
10
+ * no API for timeline payloads, metadata BLOBs, or arbitrary SQL.
11
+ */
12
+ export class FinalCutShadowBundleMutator {
13
+ options;
14
+ sqliteCommand;
15
+ constructor(options) {
16
+ this.options = options;
17
+ this.sqliteCommand = options.sqliteCommand ?? "sqlite3";
18
+ }
19
+ async createShadow(sourceBundlePath) {
20
+ if (!sourceBundlePath.endsWith(".fcpbundle")) {
21
+ throw new Error("FINAL_CUT_SHADOW_SOURCE_INVALID: source must be a .fcpbundle directory");
22
+ }
23
+ const sourceBundle = await realpath(sourceBundlePath);
24
+ await mkdir(this.options.shadowRoot, { recursive: true });
25
+ const shadowRoot = await realpath(this.options.shadowRoot);
26
+ const shadowBundle = join(shadowRoot, `${basename(sourceBundle, ".fcpbundle")}-framekit-shadow-${randomUUID()}.fcpbundle`);
27
+ await cp(sourceBundle, shadowBundle, { recursive: true, force: false, errorOnExist: true, dereference: false });
28
+ const resolvedShadowBundle = await realpath(shadowBundle);
29
+ if (!isWithin(shadowRoot, resolvedShadowBundle)) {
30
+ throw new Error("FINAL_CUT_SHADOW_BUNDLE_PATH_INVALID: shadow bundle escaped the configured shadow root");
31
+ }
32
+ return {
33
+ sourceBundlePath: sourceBundle,
34
+ shadowBundlePath: resolvedShadowBundle,
35
+ sourceDigest: await digestPath(sourceBundle),
36
+ };
37
+ }
38
+ async renameCollection(request) {
39
+ if (!Number.isSafeInteger(request.collectionPrimaryKey) || request.collectionPrimaryKey < 1) {
40
+ throw new Error("FINAL_CUT_SHADOW_COLLECTION_INVALID: collectionPrimaryKey must be a positive integer");
41
+ }
42
+ if (!Number.isSafeInteger(request.expectedOptimisticVersion) || request.expectedOptimisticVersion < 1) {
43
+ throw new Error("FINAL_CUT_SHADOW_COLLECTION_INVALID: expectedOptimisticVersion must be a positive integer");
44
+ }
45
+ if (request.name.length === 0 || request.name.includes("\0")) {
46
+ throw new Error("FINAL_CUT_SHADOW_COLLECTION_INVALID: name must be non-empty text");
47
+ }
48
+ const databasePath = await this.resolveShadowDatabase(request.shadow, request.databaseRelativePath);
49
+ await this.assertRenameSchema(databasePath);
50
+ const beforeDigest = await digestPath(databasePath);
51
+ const backupPath = `${databasePath}.framekit-backup-${randomUUID()}`;
52
+ await copyFile(databasePath, backupPath);
53
+ try {
54
+ const name = request.name.replaceAll("'", "''");
55
+ const sql = [
56
+ "BEGIN IMMEDIATE;",
57
+ `UPDATE ZCOLLECTION SET ZNAME = '${name}', Z_OPT = Z_OPT + 1 WHERE Z_PK = ${request.collectionPrimaryKey} AND Z_OPT = ${request.expectedOptimisticVersion};`,
58
+ "SELECT changes();",
59
+ "COMMIT;",
60
+ ].join(" ");
61
+ const { stdout } = await this.run(databasePath, sql);
62
+ if (stdout.trim().split(/\s+/).at(-1) !== "1") {
63
+ throw new Error("FINAL_CUT_SHADOW_COLLECTION_NOT_FOUND: collection was not updated");
64
+ }
65
+ const integrity = (await this.run(databasePath, "PRAGMA integrity_check;")).stdout.trim();
66
+ if (integrity !== "ok") {
67
+ throw new Error("FINAL_CUT_SHADOW_INTEGRITY_FAILED: SQLite integrity check failed after mutation");
68
+ }
69
+ return { databasePath, backupPath, beforeDigest, afterDigest: await digestPath(databasePath), integrity: "ok" };
70
+ }
71
+ catch (error) {
72
+ // A committed but unverifiable shadow must never be left as a candidate.
73
+ await copyFile(backupPath, databasePath);
74
+ throw error;
75
+ }
76
+ }
77
+ /**
78
+ * Executes the sole compiler-produced recipe after proving the exact Core
79
+ * Data schema/model cache. This is deliberately not an arbitrary-SQL API.
80
+ */
81
+ async executeRecipe(request) {
82
+ const actualFingerprint = await this.fingerprintSchema(request.shadow, request.databaseRelativePath);
83
+ assertFinalCutSchemaFingerprint(request.expectedFingerprint, actualFingerprint);
84
+ return this.renameCollection({
85
+ shadow: request.shadow,
86
+ databaseRelativePath: request.databaseRelativePath,
87
+ collectionPrimaryKey: request.recipe.collectionPrimaryKey,
88
+ expectedOptimisticVersion: request.recipe.expectedOptimisticVersion,
89
+ name: request.recipe.name,
90
+ });
91
+ }
92
+ /** Read-only exact schema/model fingerprint for a recipe/corpus compatibility gate. */
93
+ async fingerprintSchema(shadow, databaseRelativePath) {
94
+ const databasePath = await this.resolveShadowDatabase(shadow, databaseRelativePath);
95
+ const { stdout } = await this.run(databasePath, "PRAGMA query_only=ON; SELECT json_object('schemaVersion', (SELECT schema_version FROM pragma_schema_version), 'tables', (SELECT json_group_array(json_object('name', name, 'sql', sql)) FROM (SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name)), 'modelCacheHex', (SELECT hex(Z_CONTENT) FROM Z_MODELCACHE LIMIT 1));");
96
+ let parsed;
97
+ try {
98
+ parsed = JSON.parse(stdout.trim());
99
+ }
100
+ catch {
101
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: could not read schema fingerprint");
102
+ }
103
+ if (!parsed || typeof parsed !== "object")
104
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: invalid schema fingerprint");
105
+ const record = parsed;
106
+ const schemaVersion = record.schemaVersion;
107
+ if (typeof schemaVersion !== "number" || !Number.isSafeInteger(schemaVersion) || !Array.isArray(record.tables) || typeof record.modelCacheHex !== "string") {
108
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: incomplete schema fingerprint");
109
+ }
110
+ const tables = record.tables.map((table) => {
111
+ if (!table || typeof table !== "object")
112
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: invalid schema table");
113
+ const value = table;
114
+ if (typeof value.name !== "string" || typeof value.sql !== "string")
115
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: invalid schema table");
116
+ return { name: value.name, sql: value.sql };
117
+ });
118
+ return buildFinalCutSchemaFingerprint({ schemaVersion, tables, modelCache: Buffer.from(record.modelCacheHex, "hex") });
119
+ }
120
+ async resolveShadowDatabase(shadow, databaseRelativePath) {
121
+ if (isAbsolute(databaseRelativePath)) {
122
+ throw new Error("FINAL_CUT_SHADOW_DATABASE_PATH_INVALID: database path must be relative to the shadow bundle");
123
+ }
124
+ const bundle = await realpath(shadow.shadowBundlePath);
125
+ const candidate = resolve(bundle, databaseRelativePath);
126
+ if (!isWithin(bundle, candidate)) {
127
+ throw new Error("FINAL_CUT_SHADOW_DATABASE_PATH_INVALID: database path escapes the shadow bundle");
128
+ }
129
+ const database = await realpath(candidate);
130
+ if (!isWithin(bundle, database) || !database.endsWith(".fcpevent")) {
131
+ throw new Error("FINAL_CUT_SHADOW_DATABASE_PATH_INVALID: target must be a CurrentVersion.fcpevent database in the shadow bundle");
132
+ }
133
+ return database;
134
+ }
135
+ async assertRenameSchema(databasePath) {
136
+ try {
137
+ const { stdout } = await this.run(databasePath, "PRAGMA query_only=ON; PRAGMA table_info('ZCOLLECTION');");
138
+ const columns = new Set(stdout.split("\n").map((line) => line.split("|")[1]).filter(Boolean));
139
+ for (const required of ["Z_PK", "Z_OPT", "ZNAME"]) {
140
+ if (!columns.has(required))
141
+ throw new Error(`missing ${required}`);
142
+ }
143
+ }
144
+ catch {
145
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_UNSUPPORTED: expected ZCOLLECTION rename schema is unavailable");
146
+ }
147
+ }
148
+ async run(databasePath, sql) {
149
+ return execFile(this.sqliteCommand, [databasePath, sql], { timeout: 30_000, maxBuffer: 1_000_000 });
150
+ }
151
+ }
152
+ function isWithin(root, path) {
153
+ const pathRelative = relative(root, path);
154
+ return pathRelative !== "" && !pathRelative.startsWith(`..${sep}`) && pathRelative !== ".." && !isAbsolute(pathRelative);
155
+ }
156
+ async function digestPath(path) {
157
+ const pathStat = await stat(path);
158
+ const digest = createHash("sha256");
159
+ if (pathStat.isDirectory()) {
160
+ for (const entry of (await readdir(path)).sort()) {
161
+ digest.update(entry);
162
+ digest.update(await digestPath(join(path, entry)));
163
+ }
164
+ return digest.digest("hex");
165
+ }
166
+ const { createReadStream } = await import("node:fs");
167
+ await new Promise((resolvePromise, reject) => {
168
+ const stream = createReadStream(path);
169
+ stream.on("data", (chunk) => { digest.update(chunk); });
170
+ stream.on("error", reject);
171
+ stream.on("end", resolvePromise);
172
+ });
173
+ return digest.digest("hex");
174
+ }
@@ -0,0 +1,472 @@
1
+ import { createHash } from "node:crypto";
2
+ import { execFile as execFileCallback, spawn } from "node:child_process";
3
+ import { readFile, writeFile } from "node:fs/promises";
4
+ import { promisify } from "node:util";
5
+ const execFile = promisify(execFileCallback);
6
+ export function buildFinalCutSchemaFingerprint(input) {
7
+ if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 0) {
8
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_FINGERPRINT_INVALID: schemaVersion must be a non-negative integer");
9
+ }
10
+ const tables = [...input.tables].sort((left, right) => left.name.localeCompare(right.name));
11
+ if (tables.some((table) => !table.name || !table.sql)) {
12
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_FINGERPRINT_INVALID: every table requires a name and SQL definition");
13
+ }
14
+ return {
15
+ schemaVersion: input.schemaVersion,
16
+ sqliteMasterDigest: digestText(tables.map((table) => `${table.name}\n${table.sql}\n`).join("")),
17
+ modelCacheDigest: digestBytes(input.modelCache),
18
+ };
19
+ }
20
+ export function assertFinalCutSchemaFingerprint(expected, actual) {
21
+ if (expected.schemaVersion !== actual.schemaVersion
22
+ || expected.sqliteMasterDigest !== actual.sqliteMasterDigest
23
+ || expected.modelCacheDigest !== actual.modelCacheDigest) {
24
+ throw new Error("FINAL_CUT_SHADOW_SCHEMA_FINGERPRINT_MISMATCH: Final Cut schema or model cache differs from the proven corpus");
25
+ }
26
+ }
27
+ /**
28
+ * Decodes a `bplist00` metadata BLOB through macOS `plutil`. The resulting
29
+ * archive remains evidence only: callers must not re-encode it for mutation.
30
+ */
31
+ export async function decodeFinalCutKeyedArchive(payload, decoder = decodeKeyedArchiveWithPlutil) {
32
+ if (!Buffer.from(payload).subarray(0, 8).equals(Buffer.from("bplist00", "ascii"))) {
33
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_UNSUPPORTED: metadata BLOB is not a binary plist");
34
+ }
35
+ return parseFinalCutKeyedArchive(await decoder(payload));
36
+ }
37
+ /** Parse JSON emitted by `plutil -convert json` for an NSKeyedArchiver blob. */
38
+ export function parseFinalCutKeyedArchive(value) {
39
+ const record = object(value, "archive");
40
+ if (record.$archiver !== "NSKeyedArchiver") {
41
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_UNSUPPORTED: archive is not NSKeyedArchiver");
42
+ }
43
+ const version = record.$version;
44
+ if (typeof version !== "number" || !Number.isSafeInteger(version)) {
45
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_INVALID: $version must be an integer");
46
+ }
47
+ if (!Array.isArray(record.$objects)) {
48
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_INVALID: $objects must be an array");
49
+ }
50
+ const top = object(record.$top, "$top");
51
+ const references = [];
52
+ for (const [index, item] of record.$objects.entries())
53
+ collectReferences(item, index, "$", references);
54
+ for (const reference of references) {
55
+ if (reference.toObject < 0 || reference.toObject >= record.$objects.length) {
56
+ throw new Error("FINAL_CUT_SHADOW_ARCHIVE_INVALID: archive reference points outside $objects");
57
+ }
58
+ }
59
+ return { archiver: "NSKeyedArchiver", version, top, objects: record.$objects, references };
60
+ }
61
+ /**
62
+ * Candidate archive encoder for the Phase 5 proof gate. It preserves the
63
+ * decoded `$top`/`$objects` UID graph, but callers must still prove exact bytes
64
+ * against a Final Cut-authored archive before using it for mutation.
65
+ */
66
+ export async function encodeFinalCutKeyedArchiveWithPythonPlistlib(archive) {
67
+ const script = [
68
+ "import base64,json,plistlib,sys",
69
+ "def n(v):",
70
+ " if isinstance(v,dict) and set(v)=={'CF$UID'}: return plistlib.UID(v['CF$UID'])",
71
+ " if isinstance(v,dict) and set(v)=={'CF$bytes'}: return base64.b64decode(v['CF$bytes'])",
72
+ " if isinstance(v,dict): return {str(k): n(x) for k,x in v.items()}",
73
+ " if isinstance(v,list): return [n(x) for x in v]",
74
+ " return v",
75
+ "v=json.load(sys.stdin)",
76
+ "archive={'$archiver':'NSKeyedArchiver','$version':v['version'],'$top':n(v['top']),'$objects':n(v['objects'])}",
77
+ "sys.stdout.buffer.write(plistlib.dumps(archive,fmt=plistlib.FMT_BINARY,sort_keys=False))",
78
+ ].join("\n");
79
+ return new Promise((resolve, reject) => {
80
+ const process = spawn("python3", ["-c", script], { stdio: ["pipe", "pipe", "pipe"] });
81
+ const stdout = [];
82
+ const stderr = [];
83
+ process.stdout.on("data", (chunk) => stdout.push(chunk));
84
+ process.stderr.on("data", (chunk) => stderr.push(chunk));
85
+ process.on("error", () => reject(new Error("FINAL_CUT_SHADOW_ARCHIVE_ENCODER_UNAVAILABLE: python3 is unavailable")));
86
+ process.on("close", (code) => {
87
+ if (code !== 0) {
88
+ reject(new Error(`FINAL_CUT_SHADOW_ARCHIVE_ENCODER_FAILED: ${Buffer.concat(stderr).toString("utf8").trim()}`));
89
+ return;
90
+ }
91
+ resolve(Buffer.concat(stdout));
92
+ });
93
+ process.stdin.end(JSON.stringify({ version: archive.version, top: archive.top, objects: archive.objects }));
94
+ });
95
+ }
96
+ /**
97
+ * Reads a UI-produced before/after event database without changing it. The
98
+ * query deliberately assumes the observed Final Cut Core Data tables; a
99
+ * missing column/table is an unsupported schema, not a partial capture.
100
+ */
101
+ export class FinalCutGroundTruthCollector {
102
+ executor;
103
+ archiveDecoder;
104
+ constructor(options = {}) {
105
+ const sqliteCommand = options.sqliteCommand ?? "sqlite3";
106
+ this.executor = options.executor ?? ((databasePath, query) => execFile(sqliteCommand, ["-readonly", "-batch", "-noheader", databasePath, query], { timeout: 30_000, maxBuffer: 32_000_000 }).then(({ stdout }) => stdout));
107
+ this.archiveDecoder = options.archiveDecoder ?? decodeKeyedArchiveWithPlutil;
108
+ }
109
+ async collect(databasePath) {
110
+ const response = await this.executor(databasePath, buildFinalCutGroundTruthSnapshotQuery());
111
+ return parseFinalCutGroundTruthSnapshotResponse(response, this.archiveDecoder);
112
+ }
113
+ async collectPair(options) {
114
+ const before = await this.collect(options.beforeDatabasePath);
115
+ const after = await this.collect(options.afterDatabasePath);
116
+ return createFinalCutGroundTruthCapture(options.id, options.operation, before, after, options.nativeEvidence);
117
+ }
118
+ }
119
+ /** The only collector SQL: it starts query_only and emits no arbitrary BLOB text. */
120
+ export function buildFinalCutGroundTruthSnapshotQuery() {
121
+ return `
122
+ PRAGMA query_only=ON;
123
+ SELECT json_object(
124
+ 'schemaVersion', (SELECT schema_version FROM pragma_schema_version LIMIT 1),
125
+ 'tables', COALESCE((SELECT json_group_array(json_object('name', name, 'sql', sql))
126
+ FROM (SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name)), json('[]')),
127
+ 'modelCacheHex', (SELECT hex(Z_CONTENT) FROM Z_MODELCACHE LIMIT 1),
128
+ 'collections', COALESCE((SELECT json_group_array(json_object(
129
+ 'primaryKey', Z_PK, 'type', ZTYPE, 'optimisticVersion', Z_OPT,
130
+ 'name', ZNAME, 'identifier', ZIDENTIFIER, 'metadataId', ZMETADATA
131
+ )) FROM (SELECT Z_PK, ZTYPE, Z_OPT, ZNAME, ZIDENTIFIER, ZMETADATA FROM ZCOLLECTION ORDER BY Z_PK)), json('[]')),
132
+ 'metadata', COALESCE((SELECT json_group_array(json_object(
133
+ 'primaryKey', Z_PK, 'collectionPrimaryKey', ZCOLLECTION,
134
+ 'optimisticVersion', Z_OPT, 'archiveHex', hex(ZDICTIONARYDATA)
135
+ )) FROM (SELECT Z_PK, ZCOLLECTION, Z_OPT, ZDICTIONARYDATA FROM ZCOLLECTIONMD ORDER BY Z_PK)), json('[]')),
136
+ 'relationships', COALESCE((SELECT json_group_array(json_object(
137
+ 'parentPrimaryKey', Z_3PARENTCOLLECTIONS, 'childPrimaryKey', Z_3CHILDCOLLECTIONS
138
+ )) FROM (SELECT Z_3PARENTCOLLECTIONS, Z_3CHILDCOLLECTIONS FROM Z_3CHILDCOLLECTIONS
139
+ ORDER BY Z_3PARENTCOLLECTIONS, Z_3CHILDCOLLECTIONS)), json('[]'))
140
+ ) AS snapshot;`;
141
+ }
142
+ /** Converts the collector's JSON into a fully decoded, evidence-only snapshot. */
143
+ export async function parseFinalCutGroundTruthSnapshotResponse(input, decoder = decodeKeyedArchiveWithPlutil) {
144
+ let parsed;
145
+ try {
146
+ parsed = typeof input === "string" ? JSON.parse(input) : input;
147
+ }
148
+ catch {
149
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: collector response is not valid JSON");
150
+ }
151
+ const record = object(parsed, "collector response");
152
+ const schemaVersion = integer(record.schemaVersion, "schemaVersion");
153
+ const modelCacheHex = text(record.modelCacheHex, "modelCacheHex");
154
+ const tables = array(record.tables, "tables").map((value) => {
155
+ const table = object(value, "table");
156
+ return { name: text(table.name, "table.name"), sql: text(table.sql, "table.sql") };
157
+ });
158
+ const collections = array(record.collections, "collections").map((value) => parseCollection(value));
159
+ const metadata = await Promise.all(array(record.metadata, "metadata").map(async (value) => {
160
+ const row = object(value, "metadata");
161
+ const archiveHex = text(row.archiveHex, "metadata.archiveHex");
162
+ if (!/^(?:[\da-fA-F]{2})+$/.test(archiveHex)) {
163
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: metadata.archiveHex must be complete hexadecimal bytes");
164
+ }
165
+ return {
166
+ primaryKey: integer(row.primaryKey, "metadata.primaryKey"),
167
+ collectionPrimaryKey: optionalInteger(row.collectionPrimaryKey, "metadata.collectionPrimaryKey"),
168
+ optimisticVersion: integer(row.optimisticVersion, "metadata.optimisticVersion"),
169
+ archive: await decodeFinalCutKeyedArchive(Buffer.from(archiveHex, "hex"), decoder),
170
+ archiveDigest: digestBytes(Buffer.from(archiveHex, "hex")),
171
+ };
172
+ }));
173
+ const relationships = array(record.relationships, "relationships").map((value) => {
174
+ const row = object(value, "relationship");
175
+ return {
176
+ parentPrimaryKey: integer(row.parentPrimaryKey, "relationship.parentPrimaryKey"),
177
+ childPrimaryKey: integer(row.childPrimaryKey, "relationship.childPrimaryKey"),
178
+ };
179
+ });
180
+ return {
181
+ fingerprint: buildFinalCutSchemaFingerprint({ schemaVersion, tables, modelCache: Buffer.from(modelCacheHex, "hex") }),
182
+ collections,
183
+ metadata,
184
+ relationships,
185
+ };
186
+ }
187
+ /** Packages one externally performed UI operation for persistence in a corpus. */
188
+ export function createFinalCutGroundTruthCapture(id, operation, before, after, nativeEvidence = "unverified") {
189
+ if (!id)
190
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: capture ID must be non-empty");
191
+ const diff = diffFinalCutGroundTruthSnapshots(before, after);
192
+ if (diff.collectionChanges.length === 0 && diff.relationshipChanges.added.length === 0
193
+ && diff.relationshipChanges.removed.length === 0 && diff.archiveChanges.length === 0) {
194
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: a capture requires an observed change set");
195
+ }
196
+ return { id, operation, before, after, nativeEvidence };
197
+ }
198
+ /** Persist corpus evidence without overwriting a prior capture set. */
199
+ export async function writeFinalCutGroundTruthCorpus(path, corpus) {
200
+ validateFinalCutGroundTruthCorpus(corpus, corpus.fingerprint);
201
+ await writeFile(path, `${JSON.stringify(corpus, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
202
+ }
203
+ /** Load and validate a corpus against the fixed schema fingerprint. */
204
+ export async function readFinalCutGroundTruthCorpus(path, fingerprint) {
205
+ let value;
206
+ try {
207
+ value = JSON.parse(await readFile(path, "utf8"));
208
+ }
209
+ catch (error) {
210
+ throw new Error(`FINAL_CUT_SHADOW_CORPUS_INVALID: could not read corpus: ${error instanceof Error ? error.message : String(error)}`);
211
+ }
212
+ const corpus = object(value, "corpus");
213
+ validateFinalCutGroundTruthCorpus(corpus, fingerprint);
214
+ return corpus;
215
+ }
216
+ export function diffFinalCutGroundTruthSnapshots(before, after) {
217
+ assertFinalCutSchemaFingerprint(before.fingerprint, after.fingerprint);
218
+ const beforeCollections = new Map(before.collections.map((row) => [row.primaryKey, row]));
219
+ const afterCollections = new Map(after.collections.map((row) => [row.primaryKey, row]));
220
+ const collectionChanges = [...new Set([...beforeCollections.keys(), ...afterCollections.keys()])]
221
+ .sort((left, right) => left - right)
222
+ .flatMap((primaryKey) => {
223
+ const left = beforeCollections.get(primaryKey);
224
+ const right = afterCollections.get(primaryKey);
225
+ if (!left || !right)
226
+ return [{ primaryKey, type: left?.type ?? right.type, changed: [left ? "removed" : "added"] }];
227
+ const changed = changedFields(left, right);
228
+ return changed.length === 0 ? [] : [{ primaryKey, type: right.type, changed }];
229
+ });
230
+ const beforeRelationships = new Map(before.relationships.map((edge) => [relationshipKey(edge), edge]));
231
+ const afterRelationships = new Map(after.relationships.map((edge) => [relationshipKey(edge), edge]));
232
+ const added = [...afterRelationships].filter(([key]) => !beforeRelationships.has(key)).map(([, edge]) => edge);
233
+ const removed = [...beforeRelationships].filter(([key]) => !afterRelationships.has(key)).map(([, edge]) => edge);
234
+ const beforeMetadata = new Map(before.metadata.map((row) => [row.primaryKey, row]));
235
+ const archiveChanges = after.metadata.flatMap((row) => {
236
+ const previous = beforeMetadata.get(row.primaryKey);
237
+ if (!previous)
238
+ return [{ metadataPrimaryKey: row.primaryKey, changed: ["added"] }];
239
+ const changed = changedJson(previous.archive, row.archive, "$");
240
+ if (previous.archiveDigest !== row.archiveDigest)
241
+ changed.push("archiveDigest");
242
+ return changed.length === 0 ? [] : [{ metadataPrimaryKey: row.primaryKey, changed }];
243
+ });
244
+ for (const row of before.metadata) {
245
+ if (!after.metadata.some((candidate) => candidate.primaryKey === row.primaryKey)) {
246
+ archiveChanges.push({ metadataPrimaryKey: row.primaryKey, changed: ["removed"] });
247
+ }
248
+ }
249
+ return { collectionChanges, relationshipChanges: { added, removed }, archiveChanges };
250
+ }
251
+ export function validateFinalCutGroundTruthCorpus(corpus, fingerprint) {
252
+ if (corpus.schemaVersion !== 1 || corpus.captures.length === 0) {
253
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: corpus must contain captures with schemaVersion 1");
254
+ }
255
+ assertFinalCutSchemaFingerprint(fingerprint, corpus.fingerprint);
256
+ const ids = new Set();
257
+ for (const capture of corpus.captures) {
258
+ if (!capture.id || ids.has(capture.id))
259
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: capture IDs must be non-empty and unique");
260
+ ids.add(capture.id);
261
+ assertFinalCutSchemaFingerprint(fingerprint, capture.before.fingerprint);
262
+ assertFinalCutSchemaFingerprint(fingerprint, capture.after.fingerprint);
263
+ validateGroundTruthSnapshot(capture.before);
264
+ validateGroundTruthSnapshot(capture.after);
265
+ const diff = diffFinalCutGroundTruthSnapshots(capture.before, capture.after);
266
+ if (diff.collectionChanges.length === 0 && diff.relationshipChanges.added.length === 0
267
+ && diff.relationshipChanges.removed.length === 0 && diff.archiveChanges.length === 0) {
268
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: every capture must contain one observed change set");
269
+ }
270
+ }
271
+ }
272
+ function validateGroundTruthSnapshot(snapshot) {
273
+ const collectionIds = new Set();
274
+ for (const row of snapshot.collections) {
275
+ if (collectionIds.has(row.primaryKey))
276
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: duplicate collection primary key");
277
+ collectionIds.add(row.primaryKey);
278
+ }
279
+ const metadataIds = new Set();
280
+ for (const row of snapshot.metadata) {
281
+ if (metadataIds.has(row.primaryKey))
282
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: duplicate metadata primary key");
283
+ metadataIds.add(row.primaryKey);
284
+ if (row.archiveDigest !== undefined && !/^[a-f0-9]{64}$/.test(row.archiveDigest)) {
285
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: archiveDigest must be a SHA-256 hex digest");
286
+ }
287
+ }
288
+ const relationshipIds = new Set(snapshot.relationships.map(relationshipKey));
289
+ if (relationshipIds.size !== snapshot.relationships.length) {
290
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: duplicate relationship edge");
291
+ }
292
+ }
293
+ /**
294
+ * Produces only an allowlisted, observed control recipe. A versioned project
295
+ * requires a reopen-proven archive encoder and is deliberately rejected.
296
+ */
297
+ export function compileFinalCutShadowRecipe(corpus, fingerprint, request) {
298
+ validateFinalCutGroundTruthCorpus(corpus, fingerprint);
299
+ const capture = corpus.captures.find((candidate) => candidate.id === request.captureId);
300
+ if (!capture)
301
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_UNPROVEN: referenced ground-truth capture is unavailable");
302
+ if (request.kind === "versioned-project-materialization") {
303
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_UNPROVEN: versioned project materialization requires a reopen-proven archive encoder and graph recipe");
304
+ }
305
+ if (capture.operation !== "project-rename" || !Number.isSafeInteger(request.collectionPrimaryKey)
306
+ || request.collectionPrimaryKey < 1 || !Number.isSafeInteger(request.expectedOptimisticVersion)
307
+ || request.expectedOptimisticVersion < 1 || !request.name || request.name.includes("\0")) {
308
+ throw new Error("FINAL_CUT_SHADOW_RECIPE_INVALID: rename control request is invalid or does not match its proof operation");
309
+ }
310
+ return {
311
+ kind: request.kind,
312
+ collectionPrimaryKey: request.collectionPrimaryKey,
313
+ expectedOptimisticVersion: request.expectedOptimisticVersion,
314
+ name: request.name,
315
+ };
316
+ }
317
+ function collectReferences(value, fromObject, path, result) {
318
+ if (Array.isArray(value)) {
319
+ value.forEach((item, index) => collectReferences(item, fromObject, `${path}[${index}]`, result));
320
+ return;
321
+ }
322
+ if (!value || typeof value !== "object")
323
+ return;
324
+ const record = value;
325
+ if (Object.keys(record).length === 1 && Number.isSafeInteger(record["CF$UID"])) {
326
+ result.push({ fromObject, path, toObject: record["CF$UID"] });
327
+ return;
328
+ }
329
+ for (const [key, child] of Object.entries(record))
330
+ collectReferences(child, fromObject, `${path}.${key}`, result);
331
+ }
332
+ function changedFields(left, right) {
333
+ return [...new Set([...Object.keys(left), ...Object.keys(right)])].sort().filter((key) => !equal(left[key], right[key]));
334
+ }
335
+ function changedJson(left, right, path) {
336
+ if (equal(left, right))
337
+ return [];
338
+ if (Array.isArray(left) && Array.isArray(right)) {
339
+ const changed = [];
340
+ for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
341
+ changed.push(...changedJson(left[index], right[index], `${path}[${index}]`));
342
+ }
343
+ return changed;
344
+ }
345
+ if (isObject(left) && isObject(right)) {
346
+ const changed = [];
347
+ for (const key of [...new Set([...Object.keys(left), ...Object.keys(right)])].sort()) {
348
+ changed.push(...changedJson(left[key], right[key], `${path}.${key}`));
349
+ }
350
+ return changed;
351
+ }
352
+ return [path];
353
+ }
354
+ function equal(left, right) {
355
+ return JSON.stringify(left) === JSON.stringify(right);
356
+ }
357
+ function relationshipKey(edge) {
358
+ return `${edge.parentPrimaryKey}:${edge.childPrimaryKey}`;
359
+ }
360
+ function object(value, label) {
361
+ if (!isObject(value))
362
+ throw new Error(`FINAL_CUT_SHADOW_ARCHIVE_INVALID: ${label} must be an object`);
363
+ return value;
364
+ }
365
+ function array(value, label) {
366
+ if (!Array.isArray(value))
367
+ throw new Error(`FINAL_CUT_SHADOW_CORPUS_INVALID: ${label} must be an array`);
368
+ return value;
369
+ }
370
+ function text(value, label) {
371
+ if (typeof value !== "string")
372
+ throw new Error(`FINAL_CUT_SHADOW_CORPUS_INVALID: ${label} must be text`);
373
+ return value;
374
+ }
375
+ function integer(value, label) {
376
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
377
+ throw new Error(`FINAL_CUT_SHADOW_CORPUS_INVALID: ${label} must be a non-negative integer`);
378
+ }
379
+ return value;
380
+ }
381
+ function optionalInteger(value, label) {
382
+ return value === null || value === undefined ? undefined : integer(value, label);
383
+ }
384
+ function parseCollection(value) {
385
+ const row = object(value, "collection");
386
+ const name = row.name;
387
+ const identifier = row.identifier;
388
+ const metadataId = row.metadataId;
389
+ if (name !== null && name !== undefined && typeof name !== "string") {
390
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: collection.name must be text or null");
391
+ }
392
+ if (identifier !== null && identifier !== undefined && typeof identifier !== "string") {
393
+ throw new Error("FINAL_CUT_SHADOW_CORPUS_INVALID: collection.identifier must be text or null");
394
+ }
395
+ return {
396
+ primaryKey: integer(row.primaryKey, "collection.primaryKey"),
397
+ type: text(row.type, "collection.type"),
398
+ optimisticVersion: integer(row.optimisticVersion, "collection.optimisticVersion"),
399
+ ...(typeof name === "string" ? { name } : {}),
400
+ ...(typeof identifier === "string" ? { identifier } : {}),
401
+ ...(metadataId === null || metadataId === undefined ? {} : { metadataId: integer(metadataId, "collection.metadataId") }),
402
+ };
403
+ }
404
+ function isObject(value) {
405
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
406
+ }
407
+ function digestText(value) {
408
+ return createHash("sha256").update(value, "utf8").digest("hex");
409
+ }
410
+ function digestBytes(value) {
411
+ return createHash("sha256").update(value).digest("hex");
412
+ }
413
+ async function decodeKeyedArchiveWithPlutil(payload) {
414
+ return new Promise((resolve, reject) => {
415
+ const process = spawn("plutil", ["-convert", "json", "-o", "-", "-"], { stdio: ["pipe", "pipe", "pipe"] });
416
+ const stdout = [];
417
+ const stderr = [];
418
+ process.stdout.on("data", (chunk) => stdout.push(chunk));
419
+ process.stderr.on("data", (chunk) => stderr.push(chunk));
420
+ process.on("error", () => reject(new Error("FINAL_CUT_SHADOW_ARCHIVE_UNAVAILABLE: plutil is unavailable")));
421
+ process.on("close", (code) => {
422
+ if (code !== 0) {
423
+ decodeKeyedArchiveWithPythonPlistlib(payload).then(resolve, (fallbackError) => {
424
+ reject(new Error(`FINAL_CUT_SHADOW_ARCHIVE_INVALID: plutil failed: ${Buffer.concat(stderr).toString("utf8").trim()}; plistlib fallback failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`));
425
+ });
426
+ return;
427
+ }
428
+ try {
429
+ resolve(JSON.parse(Buffer.concat(stdout).toString("utf8")));
430
+ }
431
+ catch {
432
+ reject(new Error("FINAL_CUT_SHADOW_ARCHIVE_INVALID: plutil did not return JSON"));
433
+ }
434
+ });
435
+ process.stdin.end(payload);
436
+ });
437
+ }
438
+ /** `plutil -convert json` rejects Apple's UID objects; plistlib preserves them. */
439
+ async function decodeKeyedArchiveWithPythonPlistlib(payload) {
440
+ const script = [
441
+ "import base64,json,plistlib,sys,datetime",
442
+ "def n(v):",
443
+ " if isinstance(v, plistlib.UID): return {'CF$UID': v.data}",
444
+ " if isinstance(v,bytes): return {'CF$bytes': base64.b64encode(v).decode('ascii')}",
445
+ " if isinstance(v,dict): return {str(k): n(x) for k,x in v.items()}",
446
+ " if isinstance(v,list): return [n(x) for x in v]",
447
+ " if isinstance(v,(datetime.datetime,datetime.date)): return v.isoformat()",
448
+ " return v",
449
+ "print(json.dumps(n(plistlib.loads(sys.stdin.buffer.read())), separators=(',',':')))",
450
+ ].join("\n");
451
+ return new Promise((resolve, reject) => {
452
+ const process = spawn("python3", ["-c", script], { stdio: ["pipe", "pipe", "pipe"] });
453
+ const stdout = [];
454
+ const stderr = [];
455
+ process.stdout.on("data", (chunk) => stdout.push(chunk));
456
+ process.stderr.on("data", (chunk) => stderr.push(chunk));
457
+ process.on("error", () => reject(new Error("python3 is unavailable for binary plist decoding")));
458
+ process.on("close", (code) => {
459
+ if (code !== 0) {
460
+ reject(new Error(Buffer.concat(stderr).toString("utf8").trim() || "plistlib failed"));
461
+ return;
462
+ }
463
+ try {
464
+ resolve(JSON.parse(Buffer.concat(stdout).toString("utf8")));
465
+ }
466
+ catch {
467
+ reject(new Error("plistlib did not return JSON"));
468
+ }
469
+ });
470
+ process.stdin.end(payload);
471
+ });
472
+ }