videobook-engine 2.0.1 → 4.2.0

package/dist/store.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync, type DoltDiffRow, type DoltStatusEntry } from "@dolthub/doltlite";
-import type { CatalogBackupConfig, EngineError, OperationInput } from "./engine-types.js";
+import type { CatalogBackupConfig, EngineError, OperationInput, SemanticCommitBoundary } from "./engine-types.js";
 import { type SemanticTable } from "./schema.js";
 export declare class EngineFault extends Error {
     readonly error: EngineError;
@@ -17,6 +17,9 @@ export declare class DoltStore {
     readonly objectsDir: string;
     readonly workspaceDir: string;
     private writeChain;
+    private readonly author;
+    private readonly workingDiffProbes;
+    private readonly semanticCommitBoundary;
     constructor(input: {
         dataDir: string;
         workspaceDir: string;
@@ -25,21 +28,66 @@ export declare class DoltStore {
             slug: string;
         };
         catalogBackup?: CatalogBackupConfig;
+        author?: string;
+        semanticCommitBoundary?: (boundary: SemanticCommitBoundary, operationId: string) => void;
     });
     get head(): string;
     get status(): DoltStatusEntry[];
     close(): void;
-    semantic<T>(input: OperationInput, tables: readonly SemanticTable[], mutate: (operationId: string, now: number) => T): Promise<SemanticMutation<T>>;
+    semantic<T>(input: OperationInput, mutate: (operationId: string, now: number) => T): Promise<SemanticMutation<T>>;
     runtime<T>(mutate: (now: number) => T): T;
     diff(from: string, to: string, table: SemanticTable): DoltDiffRow[];
     push(remoteName: string): void;
+    /**
+     * Physically reclaims unreferenced chunks in the Dolt storage layer.
+     * doltlite exposes `dolt_gc()` as a SQL function and returns a human
+     * readable summary such as "3 chunks removed, 42 chunks kept".
+     */
+    doltGc(): string;
     private configureConnection;
     private initialize;
+    private ensureIgnorePatterns;
     private configureRemote;
+    private initializePrimarySequence;
     private recoverOutbox;
     private commitOutbox;
+    private clearOutboxRow;
     private sqlCommit;
     private stageTables;
+    /**
+     * Full-catalog integrity sweep, run once per open (after outbox
+     * recovery). Semantic writes only probe and stage the tables their
+     * operation declared, so rows written to an undeclared table would sit
+     * in the working set indefinitely; this sweep turns that engine bug into
+     * a loud fault at the next open instead of silent attribution drift.
+     *
+     * doltStatus over-reports (doltlite flags index-bearing tables as
+     * modified while any untracked table exists), so every candidate is
+     * confirmed against the row-level diff probe before faulting.
+     */
+    private verifyCleanSemanticWorktree;
+    /**
+     * True when `table` still has uncommitted working-set rows.
+     *
+     * This is the hot path of every semantic write: each declared table is
+     * probed once before staging and once after the commit. Staged-but-
+     * uncommitted rows also report `to_commit = 'WORKING'`, which is what
+     * makes the same probe correct during outbox recovery.
+     *
+     * The direct check, `doltDiff("HEAD","WORKING",t).length > 0`, materialises
+     * every changed row just to test emptiness. Asking the `dolt_diff_<table>`
+     * system table for a single row answers the identical question about 4x
+     * faster and allocates nothing. The statement is cached per table because
+     * preparing it each time cost more than running it, and repeated probes of
+     * the same table hit a doltlite-internal cache (~0.01ms) while probing
+     * many distinct tables in sequence thrashes it (~0.6ms each) — another
+     * reason writes probe only their declared tables.
+     *
+     * `table` is a SemanticTable, i.e. a member of the SEMANTIC_TABLES
+     * allowlist, so interpolating it into the statement cannot inject SQL.
+     */
+    private hasWorkingDiff;
+    private assertCommittedTablesClean;
     private assertOnlyVersionedStaged;
     private assertRuntimeUnstaged;
     private userTables;
@@ -51,5 +99,18 @@ export declare class DoltStore {
 }
 export declare function canonicalJson(value: unknown): string;
 export declare function parseJson<T>(text: string, fallback: T): T;
+export interface CommitOperation {
+    operation: string;
+    operationId: string;
+    artifactId?: string;
+    baseRevision?: string;
+    actor?: string;
+    writeSet: string[];
+    details: Record<string, unknown>;
+}
+export declare function commitDateMs(date: string): number;
+/** doltlite commit date normalized to an ISO-8601 UTC timestamp. */
+export declare function commitDateIso(date: string): string;
+export declare function parseCommitMessage(message: string): CommitOperation | null;
 export {};
 //# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EACV,mBAAmB,EACnB,WAAW,EACX,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAqBrB,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;gBAEhB,KAAK,EAAE,WAAW;CAK/B;AAED,UAAU,gBAAgB,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,OAAO,CAAC,UAAU,CAAoC;gBAE1C,KAAK,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,aAAa,CAAC,EAAE,mBAAmB,CAAC;KACrC;IAgBD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,eAAe,EAAE,CAE9B;IAED,KAAK,IAAI,IAAI;IAIP,QAAQ,CAAC,CAAC,EACd,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAkD/B,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC;IAazC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,EAAE;IAInE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAO9B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,UAAU;IA8GlB,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,yBAAyB;IAejC,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM;CAQf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAMzD"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EACV,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AA2BrB,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;gBAEhB,KAAK,EAAE,WAAW;CAK/B;AAED,UAAU,gBAAgB,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2C;IAC7E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAEzB;gBAEF,KAAK,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,aAAa,CAAC,EAAE,mBAAmB,CAAC;QACpC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,sBAAsB,CAAC,EAAE,CACvB,QAAQ,EAAE,sBAAsB,EAChC,WAAW,EAAE,MAAM,KAChB,IAAI,CAAC;KACX;IAkBD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,eAAe,EAAE,CAE9B;IAED,KAAK,IAAI,IAAI;IAIP,QAAQ,CAAC,CAAC,EACd,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAsC/B,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC;IAazC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,EAAE;IAInE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;OAIG;IACH,MAAM,IAAI,MAAM;IAQhB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,UAAU;IA8GlB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,yBAAyB;IAiEjC,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IA2CpB,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,SAAS;IAiBjB,OAAO,CAAC,WAAW;IAWnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,2BAA2B;IAqBnC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,yBAAyB;IAiBjC,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM;CAQf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAMzD;AAYD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA0FD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAkC1E"}

package/dist/store.js

@@ -2,7 +2,11 @@ import { mkdirSync, existsSync } from "node:fs";
 import * as path from "node:path";
 import { DatabaseSync, } from "@dolthub/doltlite";
 import { v7 as uuidv7 } from "uuid";
+import { initialOrderKeys } from "./order-keys.js";
 import { RUNTIME_SCHEMA_SQL, RUNTIME_TABLES, SCHEMA_VERSION, SEMANTIC_SCHEMA_SQL, SEMANTIC_TABLES, } from "./schema.js";
+const OUTBOX_ALLOW_EMPTY_FLAG = "allow-empty";
+const DEFAULT_COMMIT_AUTHOR = "Videobook <videobook@localhost>";
+const IGNORE_PATTERNS = ["runtime_%", "sqlite_sequence", "job_runs"];
 export class EngineFault extends Error {
     error;
     constructor(error) {
@@ -18,10 +22,16 @@ export class DoltStore {
     objectsDir;
     workspaceDir;
     writeChain = Promise.resolve();
+    author;
+    // Cached `dolt_diff_<table>` existence probes; see hasWorkingDiff.
+    workingDiffProbes = new Map();
+    semanticCommitBoundary;
     constructor(input) {
         this.dataDir = path.resolve(input.dataDir);
         this.workspaceDir = path.resolve(input.workspaceDir);
         this.databasePath = path.join(this.dataDir, "videobook.db");
+        this.author = input.author ?? DEFAULT_COMMIT_AUTHOR;
+        this.semanticCommitBoundary = input.semanticCommitBoundary;
         this.objectsDir = path.join(this.dataDir, "objects", "sha256");
         mkdirSync(this.dataDir, { recursive: true });
         mkdirSync(this.objectsDir, { recursive: true });
@@ -42,33 +52,33 @@ export class DoltStore {
     close() {
         this.db.close();
     }
-    async semantic(input, tables, mutate) {
+    async semantic(input, mutate) {
         return this.serial(async () => {
             const operationId = uuidv7();
             const now = Date.now();
-            const touched = uniqueSemanticTables([...tables, "operations"]);
-            this.assertRuntimeUnstaged();
             this.begin();
             let value;
             try {
                 value = mutate(operationId, now);
-                this.db
-                    .prepare(`INSERT INTO operations(
-              operation_id, operation, artifact_id, details_json,
-              write_set_json, base_revision, created_at, author
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(operationId, input.operation, input.artifactId ?? null, canonicalJson(input.details ?? {}), canonicalJson(input.writeSet ?? []), input.baseRevision ?? null, now, input.author ?? "videobook");
                 this.db
                     .prepare(`INSERT INTO runtime_commit_outbox(
               operation_id, tables_json, message, created_at
             ) VALUES (?, ?, ?, ?)`)
-                    .run(operationId, canonicalJson(touched), commitMessage(input, operationId), now);
+                    .run(operationId, 
+                // The declared write set commits atomically with the mutation,
+                // so recovery after a crash stages exactly the same tables.
+                canonicalJson({
+                    tables: uniqueSemanticTables(input.tables),
+                    ...(input.allowEmpty ? { allowEmpty: true } : {}),
+                }), commitMessage(input, operationId), now);
+                this.semanticCommitBoundary?.("before-sql-commit", operationId);
                 this.commitSql();
             }
             catch (error) {
                 this.rollback();
                 throw error;
             }
+            this.semanticCommitBoundary?.("after-sql-commit", operationId);
             const revision = this.commitOutbox(operationId);
             return { value, revision, operationId };
         });
@@ -91,9 +101,19 @@ export class DoltStore {
     }
     push(remoteName) {
         this.assertRuntimeUnstaged();
-        this.db
-            .prepare("SELECT dolt_push(?, 'main') AS result")
-            .get(remoteName);
+        this.db.prepare("SELECT dolt_push(?, 'main') AS result").get(remoteName);
+    }
+    /**
+     * Physically reclaims unreferenced chunks in the Dolt storage layer.
+     * doltlite exposes `dolt_gc()` as a SQL function and returns a human
+     * readable summary such as "3 chunks removed, 42 chunks kept".
+     */
+    doltGc() {
+        this.assertRuntimeUnstaged();
+        const row = this.db
+            .prepare("SELECT dolt_gc() AS result")
+            .get();
+        return row?.result ?? "";
     }
     configureConnection() {
         this.db.exec("PRAGMA foreign_keys = ON");
@@ -133,11 +153,11 @@ export class DoltStore {
           ignored TINYINT NOT NULL,
           PRIMARY KEY(pattern)
         )`);
-            this.db
-                .prepare(`INSERT INTO dolt_ignore(pattern, ignored)
-           VALUES ('runtime_%', 1), ('sqlite_sequence', 1)
-           ON CONFLICT(pattern) DO UPDATE SET ignored=excluded.ignored`)
-                .run();
+            const insertIgnorePattern = this.db.prepare(`INSERT INTO dolt_ignore(pattern, ignored)
+         VALUES (?, 1)
+         ON CONFLICT(pattern) DO UPDATE SET ignored=excluded.ignored`);
+            for (const pattern of IGNORE_PATTERNS)
+                insertIgnorePattern.run(pattern);
             const now = Date.now();
             this.db
                 .prepare("INSERT INTO engine_schema(singleton, version, created_at) VALUES (1, ?, ?)")
@@ -145,13 +165,9 @@ export class DoltStore {
             this.db
                 .prepare("INSERT INTO book(book_id, slug, created_at) VALUES (?, ?, ?)")
                 .run(initialBook.bookId, initialBook.slug, now);
-            this.db
-                .prepare("INSERT INTO timeline(book_id, render) VALUES (?, 'landscape')")
-                .run(initialBook.bookId);
+            this.initializePrimarySequence(initialBook.bookId, now);
             this.stageTables(SEMANTIC_TABLES);
-            this.db
-                .prepare("SELECT dolt_add('dolt_ignore') AS result")
-                .get();
+            this.db.prepare("SELECT dolt_add('dolt_ignore') AS result").get();
             this.assertOnlyVersionedStaged();
             this.sqlCommit("Initialize Videobook book");
         }
@@ -159,11 +175,19 @@ export class DoltStore {
             const row = this.db
                 .prepare("SELECT version FROM engine_schema WHERE singleton = 1")
                 .get();
-            if (!row || row.version !== SCHEMA_VERSION) {
+            if (!row) {
                 this.db.close();
                 throw new EngineFault({
                     code: "SCHEMA_INCOMPATIBLE",
-                    message: `Database schema ${row?.version ?? "unknown"} is not supported by engine schema ${SCHEMA_VERSION}`,
+                    message: "Database schema unknown is not supported by engine schema " +
+                        `${SCHEMA_VERSION}`,
+                });
+            }
+            if (row.version !== SCHEMA_VERSION) {
+                this.db.close();
+                throw new EngineFault({
+                    code: "SCHEMA_INCOMPATIBLE",
+                    message: `Database schema ${row.version} is not supported by engine schema ${SCHEMA_VERSION}`,
                 });
             }
             const books = this.db
@@ -183,6 +207,7 @@ export class DoltStore {
                     message: "Videobook only supports the main branch",
                 });
             }
+            this.ensureIgnorePatterns();
         }
         this.db.exec(RUNTIME_SCHEMA_SQL);
         this.db
@@ -194,6 +219,16 @@ export class DoltStore {
             .run(String(SCHEMA_VERSION), Date.now());
         this.assertRuntimeUnstaged();
         this.recoverOutbox();
+        this.verifyCleanSemanticWorktree();
+    }
+    ensureIgnorePatterns() {
+        const insert = this.db.prepare(`INSERT INTO dolt_ignore(pattern, ignored)
+       SELECT ?, 1
+       WHERE NOT EXISTS(
+         SELECT 1 FROM dolt_ignore WHERE pattern = ?
+       )`);
+        for (const pattern of IGNORE_PATTERNS)
+            insert.run(pattern, pattern);
     }
     configureRemote(remote) {
         const rows = this.db
@@ -213,6 +248,30 @@ export class DoltStore {
             .prepare("SELECT dolt_remote('add', ?, ?) AS result")
             .get(remote.name, remote.url);
     }
+    initializePrimarySequence(bookId, now) {
+        const sequenceId = uuidv7();
+        this.db
+            .prepare(`INSERT INTO sequences(
+          sequence_id, book_id, name, is_primary, width, height,
+          pixel_aspect_numerator, pixel_aspect_denominator,
+          frame_rate_numerator, frame_rate_denominator,
+          audio_sample_rate_hz, audio_channel_layout,
+          background_rgba_json, created_at
+        ) VALUES (?, ?, 'Main', 1, 1920, 1080, 1, 1, 30, 1, 48000, 'stereo', ?, ?)`)
+            .run(sequenceId, bookId, canonicalJson([0, 0, 0, 1]), now);
+        const insertTrack = this.db.prepare(`INSERT INTO sequence_tracks(
+        track_id, sequence_id, kind, order_key, name,
+        enabled, locked, muted, solo, blend_mode
+      ) VALUES (?, ?, ?, ?, ?, 1, 0, ?, ?, ?)`);
+        const videoKeys = initialOrderKeys(2);
+        insertTrack.run(uuidv7(), sequenceId, "video", videoKeys[0], "Video 1", null, null, "normal");
+        insertTrack.run(uuidv7(), sequenceId, "video", videoKeys[1], "Video 2", null, null, "normal");
+        const audioKeys = initialOrderKeys(4);
+        for (let ordinal = 0; ordinal < 4; ordinal += 1) {
+            insertTrack.run(uuidv7(), sequenceId, "audio", audioKeys[ordinal], `Audio ${ordinal + 1}`, 0, 0, null);
+        }
+        insertTrack.run(uuidv7(), sequenceId, "caption", initialOrderKeys(1)[0], "Captions", null, null, null);
+    }
     recoverOutbox() {
         const rows = this.db
             .prepare(`SELECT operation_id, tables_json, message
@@ -231,40 +290,58 @@ export class DoltStore {
             .get(operationId);
         if (!row)
             return this.head;
-        const tables = parseStringArray(row.tables_json);
-        const changedTables = [];
-        for (const table of tables) {
-            if (!isSemanticTable(table)) {
-                throw new EngineFault({
-                    code: "STORAGE_ERROR",
-                    message: `Commit outbox contains non-semantic table: ${table}`,
-                });
-            }
-            const changed = this.db
-                .doltStatus()
-                .some((entry) => entry.table_name === table &&
-                entry.staged === 0 &&
-                entry.status !== "ignored");
-            if (changed)
-                changedTables.push(table);
+        const declared = parseOutboxTables(row.tables_json);
+        const dirty = declared.tables.filter((table) => this.hasWorkingDiff(table));
+        if (dirty.length === 0 && !declared.allowEmpty) {
+            // Either the mutation only touched ignored runtime tables (bookkeeping
+            // mints no commit), or this is recovery after a crash that followed the
+            // dolt commit. Either way only the outbox row is left to clear.
+            this.clearOutboxRow(operationId);
+            return this.head;
         }
-        this.stageTables(changedTables);
-        this.assertOnlyVersionedStaged();
-        const hasStaged = this.db
-            .doltStatus()
-            .some((entry) => entry.staged === 1);
-        const revision = hasStaged ? this.sqlCommit(row.message) : this.head;
-        this.runtime(() => {
+        // One status scan guards the staging boundary: anything already staged
+        // must be on the allowlist (a runtime table here is corruption), and a
+        // dirty dolt_ignore rides along with the commit. Our own dolt_add calls
+        // below stage allowlisted tables only, so the pre-staging snapshot
+        // covers the post-staging assertion too.
+        const status = this.db.doltStatus();
+        this.assertOnlyVersionedStaged(status);
+        this.stageTables(dirty);
+        if (status.some((entry) => entry.table_name === "dolt_ignore" && entry.staged === 0)) {
+            this.db.prepare("SELECT dolt_add('dolt_ignore') AS result").get();
+        }
+        const revision = this.sqlCommit(row.message, dirty.length === 0);
+        this.semanticCommitBoundary?.("after-dolt-commit", operationId);
+        // The commit is durable at this point: clear the outbox row before
+        // asserting, so a failed assertion can neither strand the row nor
+        // re-attribute this operation's rows to a later commit at recovery.
+        this.clearOutboxRow(operationId);
+        this.assertCommittedTablesClean(dirty, revision);
+        return revision;
+    }
+    clearOutboxRow(operationId) {
+        // A single-statement delete on a runtime table; the full runtime()
+        // pre-flight would re-scan doltStatus on every semantic write for no
+        // added safety.
+        this.begin();
+        try {
             this.db
                 .prepare("DELETE FROM runtime_commit_outbox WHERE operation_id = ?")
                 .run(operationId);
-        });
-        return revision;
+            this.commitSql();
+        }
+        catch (error) {
+            this.rollback();
+            throw error;
+        }
     }
-    sqlCommit(message) {
+    sqlCommit(message, allowEmpty = false) {
+        const statement = allowEmpty
+            ? "SELECT dolt_commit('--allow-empty', '-m', ?, '--author', ?) AS hash"
+            : "SELECT dolt_commit('-m', ?, '--author', ?) AS hash";
         const row = this.db
-            .prepare("SELECT dolt_commit('-m', ?) AS hash")
-            .get(message);
+            .prepare(statement)
+            .get(message, this.author);
         const hash = row?.hash;
         if (!hash) {
             throw new EngineFault({
@@ -272,19 +349,91 @@ export class DoltStore {
                 message: "Dolt commit did not return a revision hash",
             });
         }
-        this.assertRuntimeUnstaged();
         return hash;
     }
     stageTables(tables) {
+        // One dolt_add per table: the multi-argument form silently falls back
+        // to staging every table doltStatus over-reports as modified, which
+        // would commit unrelated storage noise (and, worse, ride over the
+        // runtime-table fence).
         const unique = uniqueSemanticTables(tables);
         for (const table of unique) {
-            this.db
-                .prepare("SELECT dolt_add(?) AS result")
-                .get(table);
+            this.db.prepare("SELECT dolt_add(?) AS result").get(table);
         }
     }
-    assertOnlyVersionedStaged() {
+    /**
+     * Full-catalog integrity sweep, run once per open (after outbox
+     * recovery). Semantic writes only probe and stage the tables their
+     * operation declared, so rows written to an undeclared table would sit
+     * in the working set indefinitely; this sweep turns that engine bug into
+     * a loud fault at the next open instead of silent attribution drift.
+     *
+     * doltStatus over-reports (doltlite flags index-bearing tables as
+     * modified while any untracked table exists), so every candidate is
+     * confirmed against the row-level diff probe before faulting.
+     */
+    verifyCleanSemanticWorktree() {
+        const dirty = [];
         for (const entry of this.db.doltStatus()) {
+            if (entry.staged !== 0 || entry.status === "ignored")
+                continue;
+            if (!isSemanticTable(entry.table_name))
+                continue;
+            if (this.hasWorkingDiff(entry.table_name)) {
+                dirty.push(entry.table_name);
+            }
+        }
+        if (dirty.length > 0) {
+            this.db.close();
+            throw new EngineFault({
+                code: "STORAGE_ERROR",
+                message: "Semantic worktree has uncommitted changes not attributed to any operation: " +
+                    dirty.join(", "),
+                details: { dirtyTables: dirty },
+            });
+        }
+    }
+    /**
+     * True when `table` still has uncommitted working-set rows.
+     *
+     * This is the hot path of every semantic write: each declared table is
+     * probed once before staging and once after the commit. Staged-but-
+     * uncommitted rows also report `to_commit = 'WORKING'`, which is what
+     * makes the same probe correct during outbox recovery.
+     *
+     * The direct check, `doltDiff("HEAD","WORKING",t).length > 0`, materialises
+     * every changed row just to test emptiness. Asking the `dolt_diff_<table>`
+     * system table for a single row answers the identical question about 4x
+     * faster and allocates nothing. The statement is cached per table because
+     * preparing it each time cost more than running it, and repeated probes of
+     * the same table hit a doltlite-internal cache (~0.01ms) while probing
+     * many distinct tables in sequence thrashes it (~0.6ms each) — another
+     * reason writes probe only their declared tables.
+     *
+     * `table` is a SemanticTable, i.e. a member of the SEMANTIC_TABLES
+     * allowlist, so interpolating it into the statement cannot inject SQL.
+     */
+    hasWorkingDiff(table) {
+        let probe = this.workingDiffProbes.get(table);
+        if (!probe) {
+            probe = this.db.prepare(`SELECT 1 AS present FROM dolt_diff_${table}
+         WHERE to_commit = 'WORKING' LIMIT 1`);
+            this.workingDiffProbes.set(table, probe);
+        }
+        return Boolean(probe.get());
+    }
+    assertCommittedTablesClean(tables, committedRevision) {
+        const dirty = tables.filter((table) => this.hasWorkingDiff(table));
+        if (dirty.length > 0) {
+            throw new EngineFault({
+                code: "STORAGE_ERROR",
+                message: "Semantic worktree is dirty after commit: " + dirty.join(", "),
+                details: { committedRevision, dirtyTables: dirty },
+            });
+        }
+    }
+    assertOnlyVersionedStaged(status = this.db.doltStatus()) {
+        for (const entry of status) {
             if (entry.staged !== 1)
                 continue;
             if (!isSemanticTable(entry.table_name) &&
@@ -359,19 +508,156 @@ function sortJson(value) {
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([key, item]) => [key, sortJson(item)]));
 }
+// The commit is the provenance record: the subject names the operation (and
+// the artifact it targeted), and git-style trailers carry the operation ID,
+// base revision, actor, write set, and parameters as canonical JSON.
+//
+// doltlite rejects commit messages of 65536 bytes or more, so oversized
+// payloads degrade deterministically: the details trailer is dropped first
+// (a `details-omitted` trailer records its size), then the write-set trailer
+// (a `write-set-omitted` trailer records its size). History and conflict
+// projections treat omitted trailers as empty.
+const MAX_COMMIT_MESSAGE_BYTES = 65_024;
 function commitMessage(input, operationId) {
+    const message = buildCommitMessage(input, operationId, true, true);
+    if (byteLength(message) < MAX_COMMIT_MESSAGE_BYTES)
+        return message;
+    const withoutDetails = buildCommitMessage(input, operationId, false, true);
+    if (byteLength(withoutDetails) < MAX_COMMIT_MESSAGE_BYTES) {
+        return withoutDetails;
+    }
+    const minimal = buildCommitMessage(input, operationId, false, false);
+    if (byteLength(minimal) >= MAX_COMMIT_MESSAGE_BYTES) {
+        throw new EngineFault({
+            code: "STORAGE_ERROR",
+            message: `Commit message for ${input.operation} exceeds the Dolt size limit`,
+        });
+    }
+    return minimal;
+}
+// Trailer values are single-line by construction: canonicalJson escapes
+// newlines inside JSON, and every scalar value (operation, artifact ID,
+// base revision, actor) is rejected if it carries a control character —
+// otherwise a crafted actor could inject forged trailer lines.
+function assertSafeTrailerValue(value, label) {
+    if (/[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: `${label} must not contain control characters`,
+        });
+    }
+}
+function buildCommitMessage(input, operationId, includeDetails, includeWriteSet) {
+    assertSafeTrailerValue(input.operation, "Operation name");
+    if (input.artifactId)
+        assertSafeTrailerValue(input.artifactId, "Artifact ID");
+    if (input.baseRevision) {
+        assertSafeTrailerValue(input.baseRevision, "Base revision");
+    }
+    if (input.author)
+        assertSafeTrailerValue(input.author, "Actor");
     const target = input.artifactId ? ` artifact:${input.artifactId}` : "";
-    return `${input.operation}${target}\n\nop-id: ${operationId}`;
+    const trailers = [`op-id: ${operationId}`];
+    if (input.baseRevision)
+        trailers.push(`base-revision: ${input.baseRevision}`);
+    const writeSetJson = canonicalJson(input.writeSet ?? []);
+    if (includeWriteSet && input.writeSet && input.writeSet.length > 0) {
+        trailers.push(`write-set: ${writeSetJson}`);
+    }
+    else if (!includeWriteSet && input.writeSet && input.writeSet.length > 0) {
+        trailers.push(`write-set-omitted: ${byteLength(writeSetJson)}`);
+    }
+    const detailsJson = canonicalJson(input.details ?? {});
+    if (includeDetails &&
+        input.details &&
+        Object.keys(input.details).length > 0) {
+        trailers.push(`details: ${detailsJson}`);
+    }
+    else if (!includeDetails &&
+        input.details &&
+        Object.keys(input.details).length > 0) {
+        trailers.push(`details-omitted: ${byteLength(detailsJson)}`);
+    }
+    // The caller-influenced actor value is emitted last and the parser is
+    // first-occurrence-wins, so even a hostile value that slips past
+    // validation can never override an engine-emitted trailer.
+    if (input.author)
+        trailers.push(`actor: ${input.author}`);
+    return `${input.operation}${target}\n\n${trailers.join("\n")}`;
 }
-function parseStringArray(text) {
-    const parsed = parseJson(text, []);
-    return Array.isArray(parsed)
-        ? parsed.filter((item) => typeof item === "string")
-        : [];
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+// doltlite reports commit dates as "YYYY-MM-DD HH:MM:SS" in UTC.
+export function commitDateMs(date) {
+    const parsed = Date.parse(`${date.replace(" ", "T")}Z`);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/** doltlite commit date normalized to an ISO-8601 UTC timestamp. */
+export function commitDateIso(date) {
+    const parsed = Date.parse(`${date.replace(" ", "T")}Z`);
+    return Number.isNaN(parsed) ? date : new Date(parsed).toISOString();
+}
+export function parseCommitMessage(message) {
+    const lines = message.split("\n");
+    const subject = lines[0] ?? "";
+    const trailers = new Map();
+    for (const line of lines.slice(1)) {
+        const match = /^([a-z-]+): (.*)$/.exec(line);
+        // First occurrence wins: engine trailers precede the caller-influenced
+        // actor trailer, so injected duplicates can never shadow them.
+        if (match && !trailers.has(match[1]))
+            trailers.set(match[1], match[2]);
+    }
+    const operationId = trailers.get("op-id");
+    if (!operationId)
+        return null;
+    let operation = subject;
+    let artifactId;
+    const artifactMarker = subject.lastIndexOf(" artifact:");
+    if (artifactMarker > 0) {
+        operation = subject.slice(0, artifactMarker);
+        artifactId = subject.slice(artifactMarker + " artifact:".length);
+    }
+    if (!operation)
+        return null;
+    const baseRevision = trailers.get("base-revision");
+    const actor = trailers.get("actor");
+    return {
+        operation,
+        operationId,
+        ...(artifactId ? { artifactId } : {}),
+        ...(baseRevision ? { baseRevision } : {}),
+        ...(actor ? { actor } : {}),
+        writeSet: parseJson(trailers.get("write-set") ?? "[]", []),
+        details: parseJson(trailers.get("details") ?? "{}", {}),
+    };
 }
 function isSemanticTable(table) {
     return SEMANTIC_TABLES.includes(table);
 }
+/**
+ * Decodes the declared write set persisted with an outbox row. Rows written
+ * before write sets were declared carried a bare array (empty, or holding
+ * only the allow-empty flag); recovering one of those probes the full
+ * allowlist because the written tables are unknown.
+ */
+function parseOutboxTables(text) {
+    const parsed = parseJson(text, []);
+    if (Array.isArray(parsed)) {
+        return {
+            tables: [...SEMANTIC_TABLES],
+            allowEmpty: parsed.includes(OUTBOX_ALLOW_EMPTY_FLAG),
+        };
+    }
+    const record = parsed;
+    return {
+        tables: Array.isArray(record.tables)
+            ? record.tables.filter((table) => typeof table === "string" && isSemanticTable(table))
+            : [...SEMANTIC_TABLES],
+        allowEmpty: record.allowEmpty === true,
+    };
+}
 function uniqueSemanticTables(tables) {
     return [...new Set(tables)];
 }