hikoutei 0.2.0

package/dist/infrastructure/storage/sqlite/sqlScript.js

@@ -0,0 +1,122 @@
+import { STORAGE_ERROR_CODES, StorageError } from "../errors.js";
+/** Executes a SQLite SQL script statement-by-statement through the active executor. */
+export async function executeSqlScript(executor, script) {
+    for (const statement of splitSqlStatements(script)) {
+        await executor.run(statement);
+    }
+}
+/**
+ * Splits a SQLite script without treating semicolons inside quoted values or
+ * comments as statement boundaries.
+ */
+export function splitSqlStatements(script) {
+    const statements = [];
+    let statementStart = 0;
+    let state = "code";
+    for (let index = 0; index < script.length; index += 1) {
+        const character = script[index];
+        const nextCharacter = script[index + 1];
+        if (state === "single_quote") {
+            if (character === "'" && nextCharacter === "'") {
+                index += 1;
+            }
+            else if (character === "'") {
+                state = "code";
+            }
+            continue;
+        }
+        if (state === "double_quote") {
+            if (character === '"' && nextCharacter === '"') {
+                index += 1;
+            }
+            else if (character === '"') {
+                state = "code";
+            }
+            continue;
+        }
+        if (state === "backtick") {
+            if (character === "`" && nextCharacter === "`") {
+                index += 1;
+            }
+            else if (character === "`") {
+                state = "code";
+            }
+            continue;
+        }
+        if (state === "bracket_identifier") {
+            if (character === "]") {
+                state = "code";
+            }
+            continue;
+        }
+        if (state === "line_comment") {
+            if (character === "\n") {
+                state = "code";
+            }
+            continue;
+        }
+        if (state === "block_comment") {
+            if (character === "*" && nextCharacter === "/") {
+                state = "code";
+                index += 1;
+            }
+            continue;
+        }
+        if (character === "'") {
+            state = "single_quote";
+            continue;
+        }
+        if (character === '"') {
+            state = "double_quote";
+            continue;
+        }
+        if (character === "`") {
+            state = "backtick";
+            continue;
+        }
+        if (character === "[") {
+            state = "bracket_identifier";
+            continue;
+        }
+        if (character === "-" && nextCharacter === "-") {
+            state = "line_comment";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            state = "block_comment";
+            index += 1;
+            continue;
+        }
+        if (character === ";") {
+            appendStatement(statements, script.slice(statementStart, index));
+            statementStart = index + 1;
+        }
+    }
+    if (state !== "code" && state !== "line_comment") {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SQL_SCRIPT, `SQLite SQL script ended inside ${describeUnterminatedState(state)}.`);
+    }
+    appendStatement(statements, script.slice(statementStart));
+    return statements;
+}
+function appendStatement(statements, value) {
+    const statement = value.trim();
+    if (statement.length > 0) {
+        statements.push(statement);
+    }
+}
+function describeUnterminatedState(state) {
+    switch (state) {
+        case "single_quote":
+            return "a single-quoted value";
+        case "double_quote":
+            return "a double-quoted identifier";
+        case "backtick":
+            return "a backtick-quoted identifier";
+        case "bracket_identifier":
+            return "a bracket-quoted identifier";
+        case "block_comment":
+            return "a block comment";
+    }
+}
+//# sourceMappingURL=sqlScript.js.map

package/dist/infrastructure/storage/sqlite/sqlScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlScript.js","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlScript.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/storage/sqlite/sqlState.d.ts

@@ -0,0 +1,6 @@
+import type { Applicability, Presence } from "../../../shared/state/types.js";
+/** Converts an internal state value to SQLite's nullable column representation. */
+export declare function toSqlNullable<T>(value: Presence<T> | Applicability<T>): T | null;
+/** Converts a nullable SQLite column back into an explicit internal presence state. */
+export declare function fromSqlNullable<T>(value: T | null): Presence<T>;
+//# sourceMappingURL=sqlState.d.ts.map

package/dist/infrastructure/storage/sqlite/sqlState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlState.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlState.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE9E,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAIhF;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAI/D"}

package/dist/infrastructure/storage/sqlite/sqlState.js

@@ -0,0 +1,14 @@
+import { APPLICABILITY_KINDS, PRESENCE_KINDS, } from "../../../shared/state/constants.js";
+/** Converts an internal state value to SQLite's nullable column representation. */
+export function toSqlNullable(value) {
+    return value.kind === PRESENCE_KINDS.PRESENT || value.kind === APPLICABILITY_KINDS.APPLICABLE
+        ? value.value
+        : null;
+}
+/** Converts a nullable SQLite column back into an explicit internal presence state. */
+export function fromSqlNullable(value) {
+    return value === null
+        ? { kind: PRESENCE_KINDS.ABSENT }
+        : { kind: PRESENCE_KINDS.PRESENT, value };
+}
+//# sourceMappingURL=sqlState.js.map

package/dist/infrastructure/storage/sqlite/sqlState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlState.js","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlState.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,cAAc,GACf,MAAM,oCAAoC,CAAC;AAG5C,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAI,KAAqC;IACpE,OAAO,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC,UAAU;QAC3F,CAAC,CAAC,KAAK,CAAC,KAAK;QACb,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAI,KAAe;IAChD,OAAO,KAAK,KAAK,IAAI;QACnB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE;QACjC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}

package/dist/infrastructure/storage/sqlite/sqlTransaction.d.ts

@@ -0,0 +1,6 @@
+import type { SqlExecutor } from "../../../adapter/persistence/contracts/sql.js";
+/** Runs a nested storage unit atomically inside the current async SQL transaction. */
+export declare function withSqlSavepoint<T>(sql: SqlExecutor, name: string, operation: () => Promise<T>): Promise<T>;
+/** Rolls a named savepoint back and releases it from the current async SQL transaction. */
+export declare function rollbackSqlSavepoint(sql: SqlExecutor, name: string): Promise<void>;
+//# sourceMappingURL=sqlTransaction.d.ts.map

package/dist/infrastructure/storage/sqlite/sqlTransaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlTransaction.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlTransaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAC;AAEjF,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED,2FAA2F;AAC3F,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxF"}

package/dist/infrastructure/storage/sqlite/sqlTransaction.js

@@ -0,0 +1,24 @@
+/** Runs a nested storage unit atomically inside the current async SQL transaction. */
+export async function withSqlSavepoint(sql, name, operation) {
+    await sql.run(`SAVEPOINT ${name}`);
+    try {
+        const value = await operation();
+        await sql.run(`RELEASE ${name}`);
+        return value;
+    }
+    catch (error) {
+        try {
+            await rollbackSqlSavepoint(sql, name);
+        }
+        catch {
+            // Preserve the original storage error when cleanup itself fails.
+        }
+        throw error;
+    }
+}
+/** Rolls a named savepoint back and releases it from the current async SQL transaction. */
+export async function rollbackSqlSavepoint(sql, name) {
+    await sql.run(`ROLLBACK TO ${name}`);
+    await sql.run(`RELEASE ${name}`);
+}
+//# sourceMappingURL=sqlTransaction.js.map

package/dist/infrastructure/storage/sqlite/sqlTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlTransaction.js","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlTransaction.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAgB,EAChB,IAAY,EACZ,SAA2B;IAE3B,MAAM,GAAG,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;QAChC,MAAM,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;QACnE,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAgB,EAAE,IAAY;IACvE,MAAM,GAAG,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACrC,MAAM,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/infrastructure/storage/sqlite/sqliteBridge.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SQLite driver bridge for `node:sqlite` that vitest/vite-node can resolve.
+ *
+ * vite-node does not yet recognize `node:sqlite` as a built-in module. Loading
+ * it through Node's `createRequire` leaves the specifier to the runtime while
+ * keeping the storage type boundary independent from its declaration files.
+ */
+interface DatabaseSyncOpenOptions {
+    readonly readOnly?: boolean;
+}
+type DatabaseSyncConstructor = new (path: string, options?: DatabaseSyncOpenOptions) => DatabaseSyncLike;
+export declare function openDatabase(path: string): Promise<DatabaseSyncLike>;
+/** Opens an existing SQLite backup without granting this process write access. */
+export declare function openReadOnlyDatabase(path: string): Promise<DatabaseSyncLike>;
+/**
+ * Runs one outer writer transaction with SQLite's immediate write reservation.
+ *
+ * Call this only at a writer-RPC boundary, never from code that is already in a
+ * transaction. Nested storage helpers use savepoints so a failed substep rolls
+ * back without exposing a partial canonical or outbox mutation.
+ */
+export declare function withImmediateTransaction<T>(db: DatabaseSyncLike, operation: () => T): T;
+/** Lazy-loaded DatabaseSync constructor. */
+export declare function getDatabaseSync(): Promise<DatabaseSyncConstructor>;
+/**
+ * Minimal type description of DatabaseSync that the storage layer and tests
+ * use. This avoids importing the real type from `node:sqlite` at the type
+ * level, which would also trigger vite-node resolution.
+ */
+export interface DatabaseSyncLike {
+    exec(sql: string): void;
+    prepare(sql: string): StatementLike;
+    close(): void;
+}
+export interface StatementLike {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get<T = unknown>(...params: unknown[]): T | undefined;
+    all<T = unknown>(...params: unknown[]): T[];
+}
+export {};
+//# sourceMappingURL=sqliteBridge.d.ts.map

package/dist/infrastructure/storage/sqlite/sqliteBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteBridge.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqliteBridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,KAAK,uBAAuB,GAAG,KAAK,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,KAAK,gBAAgB,CAAC;AASzG,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG1E;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAGlF;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAcvF;AAED,4CAA4C;AAC5C,wBAAsB,eAAe,IAAI,OAAO,CAC9C,uBAAuB,CACxB,CAeA;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IACtD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;CAC7C"}

package/dist/infrastructure/storage/sqlite/sqliteBridge.js

@@ -0,0 +1,66 @@
+/**
+ * SQLite driver bridge for `node:sqlite` that vitest/vite-node can resolve.
+ *
+ * vite-node does not yet recognize `node:sqlite` as a built-in module. Loading
+ * it through Node's `createRequire` leaves the specifier to the runtime while
+ * keeping the storage type boundary independent from its declaration files.
+ */
+import { createRequire } from "node:module";
+import { STORAGE_ERROR_CODES, StorageError } from "../errors.js";
+let cached = null;
+// Keep the specifier outside a statically analyzable import so vite-node leaves
+// Node's experimental/built-in sqlite module untouched.
+const nodeSqliteSpecifier = "node:sqlite";
+const requireAtRuntime = createRequire(import.meta.url);
+export async function openDatabase(path) {
+    const DatabaseSync = await getDatabaseSync();
+    return new DatabaseSync(path);
+}
+/** Opens an existing SQLite backup without granting this process write access. */
+export async function openReadOnlyDatabase(path) {
+    const DatabaseSync = await getDatabaseSync();
+    return new DatabaseSync(path, { readOnly: true });
+}
+/**
+ * Runs one outer writer transaction with SQLite's immediate write reservation.
+ *
+ * Call this only at a writer-RPC boundary, never from code that is already in a
+ * transaction. Nested storage helpers use savepoints so a failed substep rolls
+ * back without exposing a partial canonical or outbox mutation.
+ */
+export function withImmediateTransaction(db, operation) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const value = operation();
+        db.exec("COMMIT");
+        return value;
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // Preserve the original error; a failed rollback only adds diagnostic noise.
+        }
+        throw error;
+    }
+}
+/** Lazy-loaded DatabaseSync constructor. */
+export async function getDatabaseSync() {
+    if (cached !== null) {
+        return cached;
+    }
+    const mod = requireAtRuntime(nodeSqliteSpecifier);
+    if (!hasDatabaseSyncConstructor(mod)) {
+        throw new StorageError(STORAGE_ERROR_CODES.SQLITE_RUNTIME_UNAVAILABLE, "SQLite-authoritative storage requires a Node.js runtime that provides node:sqlite.");
+    }
+    cached = mod.DatabaseSync;
+    return cached;
+}
+function hasDatabaseSyncConstructor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "DatabaseSync" in value &&
+        typeof value.DatabaseSync === "function");
+}
+//# sourceMappingURL=sqliteBridge.js.map

package/dist/infrastructure/storage/sqlite/sqliteBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteBridge.js","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqliteBridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQjE,IAAI,MAAM,GAAmC,IAAI,CAAC;AAElD,gFAAgF;AAChF,wDAAwD;AACxD,MAAM,mBAAmB,GAAW,aAAa,CAAC;AAClD,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;IAC7C,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAY;IACrD,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;IAC7C,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAI,EAAoB,EAAE,SAAkB;IAClF,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;QAC1B,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,6EAA6E;QAC/E,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,4CAA4C;AAC5C,MAAM,CAAC,KAAK,UAAU,eAAe;IAGnC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,GAAG,GAAY,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;IAC3D,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,YAAY,CACpB,mBAAmB,CAAC,0BAA0B,EAC9C,oFAAoF,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC;IAC1B,OAAO,MAAM,CAAC;AAChB,CAAC;AAmBD,SAAS,0BAA0B,CAAC,KAAc;IAGhD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,cAAc,IAAI,KAAK;QACvB,OAAQ,KAA4C,CAAC,YAAY,KAAK,UAAU,CACjF,CAAC;AACJ,CAAC"}

package/dist/infrastructure/storage/state/canonical/canonicalCommit.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Fenced canonical field commits for the SQLite-authoritative prototype.
+ *
+ * The writer applies every accepted field CAS and any resulting outbox rows in
+ * one SQLite savepoint. A stale field or lost fence rolls back the complete
+ * row-level commit, so a partially accepted event cannot leak a partial state.
+ */
+import { ROW_OPERATIONS } from "../../../../domain/model/constants.js";
+import type { Applicability, FieldOwnership, NormalizedCell, Presence } from "../../../../domain/index.js";
+import type { DatabaseSyncLike } from "../../sqlite/sqliteBridge.js";
+import type { FencingContext } from "../../sync/shared/writerLease.js";
+import { type NewEffect } from "../../sync/outbound/effectOutbox.js";
+import type { SqlExecutor, SqlStorageAdapter } from "../../../../adapter/persistence/contracts/sql.js";
+/** Runtime values returned by the canonical commit writer. */
+export declare const CANONICAL_COMMIT_RESULT_KINDS: {
+    readonly APPLIED: "applied";
+    readonly STALE: "stale";
+    readonly FENCED_OUT: "fenced_out";
+    readonly INVALID: "invalid";
+};
+/** Closed set of canonical commit result kinds. */
+export type CanonicalCommitResultKind = (typeof CANONICAL_COMMIT_RESULT_KINDS)[keyof typeof CANONICAL_COMMIT_RESULT_KINDS];
+/** Runtime values describing which canonical target became stale. */
+export declare const CANONICAL_COMMIT_STALE_TARGETS: {
+    readonly ENTITY: "entity";
+    readonly FIELD: "field";
+};
+/** Closed set of canonical stale-target kinds. */
+export type CanonicalCommitStaleTarget = (typeof CANONICAL_COMMIT_STALE_TARGETS)[keyof typeof CANONICAL_COMMIT_STALE_TARGETS];
+/** A field value the writer should insert or compare-and-set. */
+export interface CanonicalFieldWrite {
+    readonly fieldName: string;
+    readonly value: NormalizedCell;
+    /** Inserts have no prior revision; updates carry the revision used by CAS. */
+    readonly expectedFieldRevision: Applicability<number>;
+    readonly ownership: FieldOwnership;
+}
+/** Shared canonical commit fields used by every row operation. */
+interface CanonicalCommitBase {
+    readonly entityId: string;
+    /** Snapshot hash is absent when the caller has no accepted snapshot evidence. */
+    readonly acceptedSnapshotHash: Presence<string>;
+    /** Effects are inserted in this same savepoint as the canonical mutation. */
+    readonly effects: readonly NewEffect[];
+}
+/** An insert prepared from one core evaluation result. */
+export interface CanonicalInsertCommitInput extends CanonicalCommitBase {
+    readonly kind: typeof ROW_OPERATIONS.INSERT;
+    readonly fields: readonly CanonicalFieldWrite[];
+}
+/** A field-level update prepared from one core evaluation result. */
+export interface CanonicalUpdateCommitInput extends CanonicalCommitBase {
+    readonly kind: typeof ROW_OPERATIONS.UPDATE;
+    readonly fields: readonly CanonicalFieldWrite[];
+}
+/** An insert or field-level update prepared from one core evaluation result. */
+export type CanonicalFieldCommitInput = CanonicalInsertCommitInput | CanonicalUpdateCommitInput;
+/** A confirmed delete that turns an active canonical entity into a tombstone. */
+export interface CanonicalDeleteCommitInput extends CanonicalCommitBase {
+    readonly kind: typeof ROW_OPERATIONS.DELETE;
+    /** Entity revision observed with the explicit delete evidence. */
+    readonly expectedEntityRevision: number;
+}
+/** A row-level canonical mutation prepared from one core evaluation result. */
+export type CanonicalCommitInput = CanonicalFieldCommitInput | CanonicalDeleteCommitInput;
+/** Observable result of a fenced canonical commit attempt. */
+export type CanonicalCommitResult = {
+    readonly kind: typeof CANONICAL_COMMIT_RESULT_KINDS.APPLIED;
+    readonly entityRevision: number;
+    readonly fieldRevisions: ReadonlyMap<string, number>;
+} | {
+    readonly kind: typeof CANONICAL_COMMIT_RESULT_KINDS.STALE;
+    readonly target: CanonicalCommitStaleTarget;
+    readonly fieldName: Applicability<string>;
+} | {
+    readonly kind: typeof CANONICAL_COMMIT_RESULT_KINDS.FENCED_OUT;
+} | {
+    readonly kind: typeof CANONICAL_COMMIT_RESULT_KINDS.INVALID;
+    readonly reason: string;
+};
+/**
+ * Commits an insert, field-level update, or confirmed delete under a writer fence.
+ *
+ * Field revisions are independent: an update CASes each supplied field, then
+ * increments the entity revision once. An outbox uniqueness failure therefore
+ * rolls back the canonical state as well as the pending effect rows.
+ */
+export declare function commitCanonicalChanges(db: DatabaseSyncLike, fence: FencingContext, input: CanonicalCommitInput): CanonicalCommitResult;
+/**
+ * Commits canonical state and outbox effects inside an already-active async
+ * SQL transaction.
+ *
+ * This is the MikroORM-compatible counterpart of `commitCanonicalChanges()`.
+ * Call it from the same adapter transaction as the user entity mutation so a
+ * database error cannot persist one side without the other.
+ */
+export declare function commitCanonicalChangesWithSql(sql: SqlExecutor, fence: FencingContext, input: CanonicalCommitInput): Promise<CanonicalCommitResult>;
+/** Commits canonical state in one adapter-owned transaction. */
+export declare function commitCanonicalChangesWithAdapter(storage: SqlStorageAdapter, fence: FencingContext, input: CanonicalCommitInput): Promise<CanonicalCommitResult>;
+export {};
+//# sourceMappingURL=canonicalCommit.d.ts.map

package/dist/infrastructure/storage/state/canonical/canonicalCommit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalCommit.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/state/canonical/canonicalCommit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,QAAQ,EACT,MAAM,6BAA6B,CAAC;AAYrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,EAEL,KAAK,SAAS,EACf,MAAM,qCAAqC,CAAC;AAK7C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AA0CvG,8DAA8D;AAC9D,eAAO,MAAM,6BAA6B;;;;;CAKhC,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,yBAAyB,GACnC,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,OAAO,6BAA6B,CAAC,CAAC;AAErF,qEAAqE;AACrE,eAAO,MAAM,8BAA8B;;;CAGjC,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,OAAO,8BAA8B,CAAC,CAAC;AAEvF,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;CACpC;AAED,kEAAkE;AAClE,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;CACxC;AAED,0DAA0D;AAC1D,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,QAAQ,CAAC,IAAI,EAAE,OAAO,cAAc,CAAC,MAAM,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACjD;AAED,qEAAqE;AACrE,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,QAAQ,CAAC,IAAI,EAAE,OAAO,cAAc,CAAC,MAAM,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACjD;AAED,gFAAgF;AAChF,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,GAAG,0BAA0B,CAAC;AAEhG,iFAAiF;AACjF,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,QAAQ,CAAC,IAAI,EAAE,OAAO,cAAc,CAAC,MAAM,CAAC;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,0BAA0B,CAAC;AAE1F,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,6BAA6B,CAAC,OAAO,CAAC;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,6BAA6B,CAAC,KAAK,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC3C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,6BAA6B,CAAC,UAAU,CAAA;CAAE,GAClE;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,6BAA6B,CAAC,OAAO,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,oBAAoB,GAC1B,qBAAqB,CAkCvB;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAsChC;AAED,gEAAgE;AAChE,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAEhC"}