hikoutei 0.2.0

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

@@ -0,0 +1,529 @@
+import { withImmediateTransaction } from "./sqliteBridge.js";
+import { STORAGE_ERROR_CODES, StorageError } from "../errors.js";
+/**
+ * SQLite schema and migration DDL for the SQLite-authoritative sync storage layer.
+ *
+ * Implements the logical schema from design/packages/core/contracts/storage-schema.md.
+ * All identity constraints, unique indexes, and foreign keys are fixed here.
+ *
+ * Table creation order is parent-first. Deletion order is child-first.
+ */
+/** Current durable schema version managed by migrateSchema(). */
+export const CURRENT_SCHEMA_VERSION = 3;
+/** Connection settings required by every typed-sheets SQLite store. */
+export const SQLITE_CONNECTION_PRAGMAS = `
+  PRAGMA foreign_keys = ON;
+  PRAGMA journal_mode = WAL;
+  PRAGMA busy_timeout = 5000;
+`;
+/** Columns that must exist before a version-two-or-later marker is trusted. */
+export const REQUIRED_V2_COLUMNS = {
+    sync_conflict: [
+        "conflict_id",
+        "conflict_group_id",
+        "event_id",
+        "logical_sheet_id",
+        "entity_id",
+        "row_binding_id",
+        "field_name",
+        "user_value",
+        "user_base_revision",
+        "canonical_value_at_detection",
+        "canonical_revision_at_detection",
+        "current_canonical_value",
+        "current_canonical_revision",
+        "candidate_epoch",
+        "status",
+        "last_rebased_commit_id",
+        "resolution_command_id",
+        "created_at",
+        "updated_at",
+    ],
+    resolution_command: [
+        "command_id",
+        "request_key",
+        "action",
+        "actor_id",
+        "role",
+        "target_conflict_id",
+        "expected_revision",
+        "active_candidate_hash",
+        "expected_candidate_epoch",
+        "payload_hash",
+        "status",
+        "issued_at",
+        "applied_commit_id",
+    ],
+};
+/** Columns that must exist before a version-three marker is trusted. */
+export const REQUIRED_V3_COLUMNS = {
+    sheet_effect_outbox: ["effect_id", "created_at"],
+};
+/**
+ * Returns full DDL for an empty database or isolated test fixture.
+ *
+ * Durable runtime startup must call migrateSchema() instead: executing this
+ * directly cannot safely evolve an already-populated database.
+ */
+export function schemaDdl() {
+    return `${SQLITE_CONNECTION_PRAGMAS}\n${syncSchemaTablesDdl()}\n${syncSchemaIndexesDdl()}`;
+}
+/**
+ * Upgrades a durable database under an immediate writer transaction.
+ *
+ * Version 1 represents the original one-shot schema. Version 2 persists the
+ * candidate epoch needed to prevent a stale resolution request from resolving
+ * an ABA candidate retry. Version 3 adds durable effect creation time so
+ * operations can measure pending-age backpressure. Unversioned legacy
+ * databases created by schemaDdl() are adopted only after verification.
+ */
+export function migrateSchema(db) {
+    db.exec(SQLITE_CONNECTION_PRAGMAS);
+    return withImmediateTransaction(db, () => {
+        const fromVersion = readSchemaVersion(db);
+        if (fromVersion > CURRENT_SCHEMA_VERSION) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_VERSION_TOO_NEW, `SQLite schema version ${fromVersion} is newer than supported version ${CURRENT_SCHEMA_VERSION}.`);
+        }
+        const hasSchema = tableExists(db, "sheet_registry");
+        if (fromVersion === 0 && !hasSchema) {
+            db.exec(syncSchemaTablesDdl());
+            verifyRequiredColumns(db);
+            db.exec(syncSchemaIndexesDdl());
+            writeSchemaVersion(db, CURRENT_SCHEMA_VERSION);
+            verifyCurrentSchema(db);
+            return {
+                fromVersion,
+                toVersion: CURRENT_SCHEMA_VERSION,
+                appliedVersions: [CURRENT_SCHEMA_VERSION],
+            };
+        }
+        if (!hasSchema) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_TABLE_MISSING, "SQLite schema is missing sheet_registry and cannot be migrated safely.");
+        }
+        // Create tables that were added after the original one-shot bootstrap,
+        // without changing existing table definitions implicitly.
+        db.exec(syncSchemaTablesDdl());
+        const appliedVersions = [];
+        if (fromVersion < 2) {
+            applyVersion2CandidateEpochMigration(db);
+            writeSchemaVersion(db, 2);
+            appliedVersions.push(2);
+        }
+        if (fromVersion < 3) {
+            applyVersion3EffectTimestampMigration(db);
+            writeSchemaVersion(db, 3);
+            appliedVersions.push(3);
+        }
+        verifyRequiredColumns(db);
+        db.exec(syncSchemaIndexesDdl());
+        verifyCurrentSchema(db);
+        return {
+            fromVersion,
+            toVersion: CURRENT_SCHEMA_VERSION,
+            appliedVersions,
+        };
+    });
+}
+/** Returns table DDL only, so migration transactions never change connection pragmas. */
+export function syncSchemaTablesDdl() {
+    return [
+        REGISTRY_TABLES_DDL,
+        IDENTITY_TABLES_DDL,
+        CANONICAL_STATE_TABLES_DDL,
+        VISIBLE_STATE_TABLES_DDL,
+        EVENT_LEDGER_TABLES_DDL,
+        CONFLICT_AND_QUARANTINE_TABLES_DDL,
+        BUSINESS_KEY_INDEX_DDL,
+        EFFECT_OUTBOX_DDL,
+        WRITER_LEASE_DDL,
+        CUTOVER_STATE_DDL,
+    ].join("\n");
+}
+/**
+ * Creates indexes that depend on additive migration columns only after those
+ * columns have been confirmed. This keeps a version-one upgrade ordered.
+ */
+export function syncSchemaIndexesDdl() {
+    return `
+    CREATE UNIQUE INDEX IF NOT EXISTS sync_conflict_candidate_attempt_uq
+      ON sync_conflict(row_binding_id, field_name, candidate_epoch);
+  `;
+}
+/** Applies the first additive migration after the historical one-shot DDL. */
+function applyVersion2CandidateEpochMigration(db) {
+    addColumnIfMissing(db, "sync_conflict", "candidate_epoch", "INTEGER NOT NULL DEFAULT 0");
+    addColumnIfMissing(db, "resolution_command", "expected_candidate_epoch", "INTEGER NOT NULL DEFAULT 0");
+}
+/** Adds durable effect creation time without rewriting existing outbox evidence. */
+function applyVersion3EffectTimestampMigration(db) {
+    addColumnIfMissing(db, "sheet_effect_outbox", "created_at", "INTEGER NOT NULL DEFAULT 0");
+}
+/** Refuses to treat a user_version marker as authoritative when required columns are absent. */
+function verifyCurrentSchema(db) {
+    verifyRequiredColumns(db);
+    if (!indexExists(db, "sync_conflict_candidate_attempt_uq")) {
+        throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_INDEX_MISSING, "SQLite schema is missing sync_conflict_candidate_attempt_uq.");
+    }
+}
+/** Verifies columns before a dependent unique index is created. */
+function verifyRequiredColumns(db) {
+    for (const [tableName, requiredColumns] of Object.entries(REQUIRED_V2_COLUMNS)) {
+        if (!tableExists(db, tableName)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_TABLE_MISSING, `SQLite schema is missing ${tableName}; refusing an unsafe migration marker.`);
+        }
+        for (const columnName of requiredColumns) {
+            if (!columnExists(db, tableName, columnName)) {
+                throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_COLUMN_MISSING, `SQLite schema is missing ${tableName}.${columnName}; refusing an unsafe migration marker.`);
+            }
+        }
+    }
+    for (const [tableName, requiredColumns] of Object.entries(REQUIRED_V3_COLUMNS)) {
+        if (!tableExists(db, tableName)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_TABLE_MISSING, `SQLite schema is missing ${tableName}; refusing an unsafe migration marker.`);
+        }
+        for (const columnName of requiredColumns) {
+            if (!columnExists(db, tableName, columnName)) {
+                throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_COLUMN_MISSING, `SQLite schema is missing ${tableName}.${columnName}; refusing an unsafe migration marker.`);
+            }
+        }
+    }
+}
+/** Adds one known additive column exactly once. Table and column names are internal constants. */
+function addColumnIfMissing(db, tableName, columnName, definition) {
+    if (columnExists(db, tableName, columnName))
+        return;
+    db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${definition}`);
+}
+/** Reads SQLite's built-in durable schema marker. */
+function readSchemaVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    const version = row?.user_version;
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_VERSION_INVALID, "SQLite user_version must be a non-negative safe integer.");
+    }
+    return version;
+}
+/** Writes the schema marker only in the same transaction as its DDL changes. */
+function writeSchemaVersion(db, version) {
+    db.exec(`PRAGMA user_version = ${version}`);
+}
+/** Checks for one schema-owned table without interpolating external input. */
+function tableExists(db, tableName) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(tableName) !== undefined;
+}
+/** Reads the schema-owned table definition to make an ALTER migration idempotent. */
+function columnExists(db, tableName, columnName) {
+    const rows = db.prepare(`PRAGMA table_info(${tableName})`).all();
+    return rows.some((row) => row.name === columnName);
+}
+/** Checks the immutable candidate-attempt index created by the current schema. */
+function indexExists(db, indexName) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?").get(indexName) !== undefined;
+}
+const REGISTRY_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS sheet_registry (
+    sheet_id TEXT PRIMARY KEY,
+    schema_version INTEGER NOT NULL,
+    ownership_manifest_json TEXT NOT NULL,
+    business_key_field TEXT NOT NULL,
+    locale TEXT,
+    timezone TEXT,
+    anchor_mode TEXT NOT NULL DEFAULT 'developer_metadata',
+    stable_encode_version TEXT NOT NULL DEFAULT 'stable_encode_v1',
+    enabled INTEGER NOT NULL DEFAULT 1
+  );
+
+  CREATE TABLE IF NOT EXISTS physical_sheet_registry (
+    physical_sheet_id TEXT PRIMARY KEY,
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    spreadsheet_id TEXT NOT NULL,
+    tab_name TEXT NOT NULL,
+    registered_range TEXT NOT NULL,
+    projection TEXT NOT NULL,
+    schema_version INTEGER NOT NULL,
+    anchor_mode TEXT NOT NULL DEFAULT 'developer_metadata',
+    enabled INTEGER NOT NULL DEFAULT 1,
+    UNIQUE(spreadsheet_id, tab_name, registered_range, projection)
+  );
+`;
+const IDENTITY_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS row_binding (
+    row_binding_id TEXT PRIMARY KEY,
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    anchor_reference TEXT NOT NULL,
+    entity_id TEXT,
+    last_business_id TEXT,
+    state TEXT NOT NULL CHECK (state IN ('candidate', 'active', 'tombstoned', 'ambiguous')),
+    candidate_epoch INTEGER NOT NULL DEFAULT 0,
+    UNIQUE(logical_sheet_id, anchor_reference)
+  );
+
+  CREATE TABLE IF NOT EXISTS projection_row_binding (
+    projection_row_id TEXT PRIMARY KEY,
+    physical_sheet_id TEXT NOT NULL REFERENCES physical_sheet_registry(physical_sheet_id),
+    row_binding_id TEXT REFERENCES row_binding(row_binding_id),
+    conflict_id TEXT,
+    anchor_reference TEXT NOT NULL,
+    physical_row_locator INTEGER NOT NULL,
+    state TEXT NOT NULL DEFAULT 'active',
+    CHECK ((row_binding_id IS NOT NULL) != (conflict_id IS NOT NULL)),
+    UNIQUE(physical_sheet_id, anchor_reference)
+  );
+
+  CREATE UNIQUE INDEX IF NOT EXISTS projection_row_binding_entity_uq
+    ON projection_row_binding(physical_sheet_id, row_binding_id)
+    WHERE row_binding_id IS NOT NULL;
+
+  CREATE UNIQUE INDEX IF NOT EXISTS projection_row_binding_conflict_uq
+    ON projection_row_binding(physical_sheet_id, conflict_id)
+    WHERE conflict_id IS NOT NULL;
+`;
+const CANONICAL_STATE_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS entity_state (
+    entity_id TEXT PRIMARY KEY,
+    entity_revision INTEGER NOT NULL,
+    accepted_snapshot_hash TEXT,
+    status TEXT NOT NULL DEFAULT 'active'
+  );
+
+  CREATE TABLE IF NOT EXISTS entity_field_state (
+    entity_id TEXT NOT NULL REFERENCES entity_state(entity_id),
+    field_name TEXT NOT NULL,
+    normalized_value TEXT NOT NULL,
+    field_revision INTEGER NOT NULL,
+    ownership TEXT NOT NULL CHECK (ownership IN ('user', 'system')),
+    PRIMARY KEY(entity_id, field_name)
+  );
+`;
+const VISIBLE_STATE_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS sheet_visible_state (
+    physical_sheet_id TEXT NOT NULL,
+    projection TEXT NOT NULL,
+    row_binding_id TEXT NOT NULL,
+    confirmed_snapshot_hash TEXT NOT NULL,
+    confirmed_visible_revision INTEGER NOT NULL,
+    confirmed_entity_revision INTEGER,
+    last_observed_hash TEXT,
+    PRIMARY KEY(physical_sheet_id, projection, row_binding_id),
+    FOREIGN KEY(physical_sheet_id) REFERENCES physical_sheet_registry(physical_sheet_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS sheet_visible_field_state (
+    physical_sheet_id TEXT NOT NULL,
+    projection TEXT NOT NULL,
+    row_binding_id TEXT NOT NULL,
+    field_name TEXT NOT NULL,
+    confirmed_field_hash TEXT NOT NULL,
+    confirmed_visible_revision INTEGER NOT NULL,
+    active_candidate_conflict_id TEXT,
+    active_candidate_hash TEXT,
+    candidate_epoch INTEGER NOT NULL DEFAULT 0,
+    last_observed_field_hash TEXT,
+    PRIMARY KEY(physical_sheet_id, projection, row_binding_id, field_name),
+    FOREIGN KEY(physical_sheet_id) REFERENCES physical_sheet_registry(physical_sheet_id)
+  );
+`;
+const EVENT_LEDGER_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS event_batch (
+    batch_id TEXT PRIMARY KEY,
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    physical_sheet_id TEXT NOT NULL REFERENCES physical_sheet_registry(physical_sheet_id),
+    source TEXT NOT NULL,
+    projection TEXT NOT NULL,
+    atomicity TEXT NOT NULL DEFAULT 'row_independent',
+    base_snapshot_hash TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS event_log (
+    event_id TEXT PRIMARY KEY,
+    logical_sheet_id TEXT NOT NULL,
+    physical_sheet_id TEXT NOT NULL,
+    event_key TEXT NOT NULL,
+    payload_hash TEXT NOT NULL,
+    event_sequence INTEGER NOT NULL,
+    batch_id TEXT NOT NULL REFERENCES event_batch(batch_id),
+    row_binding_id TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('accepted', 'conflict', 'quarantined')),
+    received_at INTEGER NOT NULL,
+    UNIQUE(logical_sheet_id, event_key)
+  );
+
+  CREATE TABLE IF NOT EXISTS event_observation (
+    observation_id TEXT PRIMARY KEY,
+    logical_sheet_id TEXT NOT NULL,
+    physical_sheet_id TEXT NOT NULL,
+    observation_key TEXT NOT NULL,
+    event_id TEXT,
+    source TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    payload_hash TEXT NOT NULL,
+    detected_at INTEGER NOT NULL,
+    received_at INTEGER NOT NULL,
+    redacted_at INTEGER,
+    ingress_actor_id TEXT NOT NULL,
+    editor_actor_id TEXT,
+    editor_actor_source TEXT NOT NULL DEFAULT 'unavailable'
+  );
+
+  CREATE TABLE IF NOT EXISTS observation_receipt (
+    logical_sheet_id TEXT NOT NULL,
+    observation_key TEXT NOT NULL,
+    representative_payload_hash TEXT NOT NULL,
+    first_observation_id TEXT NOT NULL,
+    last_observation_id TEXT NOT NULL,
+    event_id TEXT,
+    state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'evaluated', 'duplicate', 'quarantined')),
+    first_seen_at INTEGER NOT NULL,
+    last_seen_at INTEGER NOT NULL,
+    redacted_at INTEGER,
+    PRIMARY KEY(logical_sheet_id, observation_key)
+  );
+
+  CREATE TABLE IF NOT EXISTS event_row (
+    event_id TEXT PRIMARY KEY REFERENCES event_log(event_id),
+    before_row_json TEXT,
+    after_row_json TEXT,
+    before_hash TEXT,
+    after_hash TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS event_field (
+    event_id TEXT NOT NULL REFERENCES event_log(event_id),
+    field_name TEXT NOT NULL,
+    previous_value TEXT,
+    next_value TEXT,
+    base_field_revision INTEGER,
+    PRIMARY KEY(event_id, field_name)
+  );
+`;
+const CONFLICT_AND_QUARANTINE_TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS sync_conflict (
+    conflict_id TEXT PRIMARY KEY,
+    conflict_group_id TEXT,
+    event_id TEXT NOT NULL REFERENCES event_log(event_id),
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    entity_id TEXT NOT NULL,
+    row_binding_id TEXT NOT NULL REFERENCES row_binding(row_binding_id),
+    field_name TEXT NOT NULL,
+    user_value TEXT NOT NULL,
+    user_base_revision INTEGER NOT NULL,
+    canonical_value_at_detection TEXT NOT NULL,
+    canonical_revision_at_detection INTEGER NOT NULL,
+    current_canonical_value TEXT NOT NULL,
+    current_canonical_revision INTEGER NOT NULL,
+    candidate_epoch INTEGER NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'OPEN' CHECK (status IN ('OPEN', 'NEEDS_REBASE', 'RESOLVED')),
+    last_rebased_commit_id TEXT,
+    resolution_command_id TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS quarantine_record (
+    quarantine_id TEXT PRIMARY KEY,
+    event_id TEXT,
+    observation_id TEXT,
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    row_binding_id TEXT,
+    reason TEXT NOT NULL,
+    before_row_json TEXT,
+    after_row_json TEXT,
+    fields_json TEXT NOT NULL,
+    repair_fields_json TEXT NOT NULL DEFAULT '[]',
+    repair_state TEXT,
+    candidate_payload_json TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS resolution_command (
+    command_id TEXT PRIMARY KEY,
+    request_key TEXT NOT NULL UNIQUE,
+    action TEXT NOT NULL,
+    actor_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    target_conflict_id TEXT NOT NULL REFERENCES sync_conflict(conflict_id),
+    expected_revision INTEGER NOT NULL,
+    active_candidate_hash TEXT NOT NULL,
+    expected_candidate_epoch INTEGER NOT NULL DEFAULT 0,
+    payload_hash TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'applied', 'stale', 'rejected', 'failed')),
+    issued_at INTEGER NOT NULL,
+    applied_commit_id TEXT
+  );
+`;
+const BUSINESS_KEY_INDEX_DDL = `
+  CREATE TABLE IF NOT EXISTS business_key_index (
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    field_name TEXT NOT NULL,
+    normalized_key TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'active'
+  );
+
+  CREATE UNIQUE INDEX IF NOT EXISTS business_key_active_uq
+    ON business_key_index(logical_sheet_id, field_name, normalized_key)
+    WHERE state = 'active';
+`;
+const EFFECT_OUTBOX_DDL = `
+  CREATE TABLE IF NOT EXISTS sheet_effect_outbox (
+    effect_id TEXT PRIMARY KEY,
+    effect_kind TEXT NOT NULL,
+    commit_id TEXT NOT NULL,
+    logical_sheet_id TEXT NOT NULL REFERENCES sheet_registry(sheet_id),
+    physical_sheet_id TEXT NOT NULL REFERENCES physical_sheet_registry(physical_sheet_id),
+    projection TEXT NOT NULL,
+    row_binding_id TEXT,
+    conflict_id TEXT,
+    target_kind TEXT NOT NULL CHECK (target_kind IN ('entity', 'row_binding', 'projection_row', 'conflict')),
+    target_id TEXT NOT NULL,
+    target_entity_revision INTEGER,
+    target_field_revision_hash TEXT,
+    target_canonical_commit_id TEXT,
+    expected_visible_revision INTEGER NOT NULL,
+    expected_visible_hash TEXT NOT NULL,
+    repair_guard_hash TEXT,
+    source_quarantine_id TEXT,
+    payload_json TEXT NOT NULL,
+    payload_hash TEXT NOT NULL,
+    effect_dedupe_key TEXT NOT NULL UNIQUE,
+    stream_sequence INTEGER NOT NULL,
+    predecessor_effect_id TEXT,
+    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'applied', 'blocked_candidate', 'superseded', 'conflict', 'failed')),
+    attempts INTEGER NOT NULL DEFAULT 0,
+    lease_until INTEGER,
+    next_attempt_at INTEGER,
+    claim_token TEXT,
+    writer_epoch INTEGER,
+    supersedes_effect_id TEXT,
+    last_error_code TEXT,
+    last_error_message TEXT,
+    created_at INTEGER NOT NULL DEFAULT 0,
+    UNIQUE(logical_sheet_id, target_kind, target_id, stream_sequence)
+  );
+
+  CREATE INDEX IF NOT EXISTS effect_outbox_stream_idx
+    ON sheet_effect_outbox(logical_sheet_id, target_kind, target_id, stream_sequence)
+    WHERE status IN ('pending', 'processing');
+`;
+const WRITER_LEASE_DDL = `
+  CREATE TABLE IF NOT EXISTS writer_lease (
+    role TEXT PRIMARY KEY,
+    writer_id TEXT NOT NULL,
+    writer_epoch INTEGER NOT NULL,
+    fencing_token TEXT NOT NULL,
+    lease_until INTEGER NOT NULL
+  );
+`;
+const CUTOVER_STATE_DDL = `
+  CREATE TABLE IF NOT EXISTS cutover_state (
+    cutover_id TEXT PRIMARY KEY,
+    phase TEXT NOT NULL,
+    source_snapshot_hash TEXT,
+    marker TEXT,
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+  );
+`;
+//# sourceMappingURL=schema.js.map

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

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

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

@@ -0,0 +1,5 @@
+/** Table names used by the additive SQLite schema migrations. */
+export type SchemaMigrationTableName = "sync_conflict" | "resolution_command" | "sheet_effect_outbox";
+/** Column names added by the additive SQLite schema migrations. */
+export type SchemaMigrationColumnName = "candidate_epoch" | "expected_candidate_epoch" | "created_at";
+//# sourceMappingURL=schemaTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaTypes.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/schemaTypes.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAChC,eAAe,GACf,oBAAoB,GACpB,qBAAqB,CAAC;AAE1B,mEAAmE;AACnE,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,0BAA0B,GAC1B,YAAY,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schemaTypes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaTypes.js","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/schemaTypes.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,9 @@
+import type { SqlExecutor } from "../../../adapter/persistence/contracts/sql.js";
+/** Executes a SQLite SQL script statement-by-statement through the active executor. */
+export declare function executeSqlScript(executor: SqlExecutor, script: string): Promise<void>;
+/**
+ * Splits a SQLite script without treating semicolons inside quoted values or
+ * comments as statement boundaries.
+ */
+export declare function splitSqlStatements(script: string): readonly string[];
+//# sourceMappingURL=sqlScript.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlScript.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/sqlite/sqlScript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAC;AAGjF,uFAAuF;AACvF,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAmGpE"}