@syncular/server 0.21.1 → 0.23.0

package/dist/sqlite-storage.js

@@ -1,5 +1,7 @@
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
+import { serveGateRefusal } from './storage.js';
+import { serveNotReadyError } from './readiness.js';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -10,12 +12,24 @@ import { StorageQueryError } from './storage-errors.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
+function toStoredCheckpoint(record) {
+    return {
+        partition: record.partition,
+        name: record.name,
+        schemaVersion: record.schema_version,
+        state: record.state,
+        watermark: record.watermark,
+        ownerEpoch: record.owner_epoch,
+        observedRows: record.observed_rows,
+        updatedAtMs: record.updated_at_ms,
+    };
+}
 function toStoredReaction(record) {
     return {
         idempotencyKey: record.idempotency_key,
@@ -45,12 +59,15 @@ function toStoredReaction(record) {
 class SqliteTransaction {
     #storage;
     #partition;
+    /** Schema version this transaction writes; rides every appended commit row. */
+    #writerVersion;
     #open = true;
     #pushApplySavepoint = false;
     #release;
-    constructor(storage, partition, release) {
+    constructor(storage, partition, writerVersion, release) {
         this.#storage = storage;
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#release = release;
         storage.db.exec('BEGIN IMMEDIATE');
     }
@@ -95,6 +112,21 @@ class SqliteTransaction {
         this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
     }
+    async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
+        this.#assertOpen();
+        const result = this.#storage.db
+            .query(`UPDATE sync_backfill_checkpoints
+            SET watermark=?, observed_rows=?, updated_at_ms=?
+          WHERE partition=? AND name=? AND owner_epoch=?`)
+            .run(watermark, observedRows, nowMs, this.#partition, name, ownerEpoch);
+        return Number(result.changes) === 1;
+    }
+    readServeGate(runningSchemaVersion) {
+        this.#assertOpen();
+        // Same shared connection: this read runs inside this transaction's
+        // BEGIN IMMEDIATE, so the gate and the write share one transaction.
+        return this.#storage.readServeGate(this.#partition, runningSchemaVersion);
+    }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         if (!this.#pushApplySavepoint) {
@@ -146,7 +178,7 @@ class SqliteTransaction {
             .get(p);
         const commitSeq = (row?.max_commit_seq ?? 0) + 1;
         db.query('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?').run(commitSeq, p);
-        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms) VALUES (?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs);
+        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs, this.#writerVersion);
         commit.changes.forEach((change, idx) => {
             db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
             if (change.op === 'delete') {
@@ -247,6 +279,30 @@ export class SqliteServerStorage {
         if (!clientColumns.some((column) => column.name === 'wire_version')) {
             this.db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1');
         }
+        const commitColumns = this.db
+            .query('PRAGMA table_info("sync_commits")')
+            .all();
+        if (!commitColumns.some((column) => column.name === 'writer_version')) {
+            // Nullable by design: an old writer omits the column and the trigger's
+            // explicit NULL test rejects it. `ADD COLUMN NOT NULL` is unavailable in
+            // SQLite, and a default would hand old writers a passing value.
+            this.db.exec('ALTER TABLE sync_commits ADD COLUMN writer_version INTEGER');
+        }
+        // The fence is database-side: an old binary's INSERT never reaches JS. An
+        // absent `sync_writer_fence` row makes the WHEN clause false, so a
+        // partition with no barrier behaves exactly as before.
+        this.db.exec(`CREATE TRIGGER IF NOT EXISTS sync_commits_writer_fence
+BEFORE INSERT ON sync_commits
+FOR EACH ROW
+WHEN EXISTS (
+  SELECT 1 FROM sync_writer_fence
+   WHERE partition = NEW.partition
+     AND (NEW.writer_version IS NULL
+          OR NEW.writer_version < required_writer_version)
+)
+BEGIN
+  SELECT RAISE(ABORT, 'sync.storage.writer_fence_rejected');
+END`);
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -256,10 +312,24 @@ export class SqliteServerStorage {
         }
         return table;
     }
-    async ensureSchema(schema) {
+    async ensureSchema(schema, checkpoints) {
         // Memoized fast path: same instance, same schema version.
         if (this.#schemaVersion === schema.version)
             return;
+        // The barrier reads stored state: a checkpoint at this schema version that
+        // is not activated and that this caller did not declare means this process
+        // must not serve. An omitted or empty declaration set declares nothing and
+        // is refused here, never treated as a bypass.
+        const declarations = checkpoints ?? [];
+        const incomplete = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(schema.version)
+            .filter((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
+            declaration.name === row.name));
+        if (incomplete.length > 0) {
+            throw new StorageQueryError('sync.storage.checkpoint_incomplete');
+        }
         this.db.exec(SCHEMA_META_DDL_SQLITE);
         const marker = this.db
             .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
@@ -267,6 +337,55 @@ export class SqliteServerStorage {
         if (marker !== null && marker.schema_version > schema.version) {
             throw new Error(`stored schema version ${marker.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
         }
+        if (marker !== null && marker.schema_version === schema.version) {
+            // Version equality is not layout equality: a marker written by another
+            // build at the same version describes rows the running codec cannot
+            // decode. Compare the stored layouts instead of trusting the number.
+            const storedLayouts = parseLayouts(marker.layouts);
+            const configuredLayouts = parseLayouts(layoutsOf(schema));
+            let mismatch;
+            for (const [tableName, columns] of Object.entries(configuredLayouts)) {
+                const stored = storedLayouts[tableName];
+                const columnCount = Math.max(columns.length, stored?.length ?? 0);
+                for (let index = 0; index < columnCount; index++) {
+                    const expected = columns[index];
+                    const actual = stored?.[index];
+                    if (expected !== undefined &&
+                        actual !== undefined &&
+                        actual.name === expected.name &&
+                        actual.type === expected.type &&
+                        actual.nullable === expected.nullable) {
+                        continue;
+                    }
+                    mismatch = `table ${JSON.stringify(tableName)} column ${JSON.stringify(expected?.name ?? actual?.name ?? '')}`;
+                    break;
+                }
+                if (mismatch !== undefined)
+                    break;
+            }
+            if (mismatch === undefined) {
+                for (const tableName of Object.keys(storedLayouts)) {
+                    if (!(tableName in configuredLayouts)) {
+                        mismatch = `table ${JSON.stringify(tableName)}`;
+                        break;
+                    }
+                }
+            }
+            if (mismatch !== undefined) {
+                throw new Error(`stored schema layouts disagree with the configured schema at version ${schema.version} (${mismatch}) — refusing to serve a database whose stored rows the running code cannot decode`);
+            }
+            // The persisted layouts describe the codec's app columns only: read the
+            // physical tables so a same-version database missing a
+            // storage-internal column is refused at startup instead of failing at
+            // the first write.
+            for (const table of schema.tables.values()) {
+                const escapedTableName = table.name.replaceAll('"', '""');
+                const columns = this.db
+                    .query(`PRAGMA table_info("${escapedTableName}")`)
+                    .all();
+                assertPhysicalColumns(table, new Set(columns.map((c) => c.name)));
+            }
+        }
         if (marker === null || marker.schema_version < schema.version) {
             // Introspect existing app tables, then apply the migration subset
             // (CREATE TABLE / ADD COLUMN / rebuild indexes) to reach `schema`, then
@@ -291,36 +410,50 @@ export class SqliteServerStorage {
                     existingIndexes.set(table.name, new Set(indexes.map((index) => index.name)));
                 }
             }
-            this.db.exec('BEGIN IMMEDIATE');
-            try {
-                for (const tableName of retiredTables) {
-                    this.db
-                        .query('DELETE FROM sync_row_scopes WHERE tbl=?')
-                        .run(tableName);
+            // The migration rewrites application rows (`#rewriteRows`) with no
+            // commit log entry. Serialize it through the same writer queue as
+            // pushes and prune (`#serializeWrite`) rather than trusting the
+            // migration as privileged; `BEGIN IMMEDIATE` then owns SQLite's writer
+            // lock for the whole rewrite.
+            await this.#serializeWrite(() => {
+                this.db.exec('BEGIN IMMEDIATE');
+                try {
+                    for (const tableName of retiredTables) {
+                        this.db
+                            .query('DELETE FROM sync_row_scopes WHERE tbl=?')
+                            .run(tableName);
+                        this.db
+                            .query('DELETE FROM sync_blob_refs WHERE tbl=?')
+                            .run(tableName);
+                        this.db.exec(dropTableDdl(tableName));
+                    }
+                    for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
+                        this.db.exec(statement);
+                    }
+                    for (const table of schema.tables.values()) {
+                        const oldLayout = layouts[table.name];
+                        const plan = rewritePlan(table, oldLayout, existing.get(table.name));
+                        if (!plan.migrate && !plan.backfill)
+                            continue;
+                        this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                    }
                     this.db
-                        .query('DELETE FROM sync_blob_refs WHERE tbl=?')
-                        .run(tableName);
-                    this.db.exec(dropTableDdl(tableName));
-                }
-                for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
-                    this.db.exec(statement);
+                        .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
+                        .run(schema.version, layoutsOf(schema));
+                    // The host's declared checkpoints install in the schema-bump
+                    // transaction, so no observer sees the bumped marker without the
+                    // fence, or the fence without its declaration row.
+                    const installedAtMs = Date.now();
+                    for (const declaration of checkpoints ?? []) {
+                        this.#installCheckpoint(declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
+                    }
+                    this.db.exec('COMMIT');
                 }
-                for (const table of schema.tables.values()) {
-                    const oldLayout = layouts[table.name];
-                    const plan = rewritePlan(table, oldLayout, existing.get(table.name));
-                    if (!plan.migrate && !plan.backfill)
-                        continue;
-                    this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                catch (error) {
+                    this.db.exec('ROLLBACK');
+                    throw error;
                 }
-                this.db
-                    .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
-                    .run(schema.version, layoutsOf(schema));
-                this.db.exec('COMMIT');
-            }
-            catch (error) {
-                this.db.exec('ROLLBACK');
-                throw error;
-            }
+            });
         }
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
@@ -436,7 +569,7 @@ export class SqliteServerStorage {
         });
         await previous;
         try {
-            return new SqliteTransaction(this, partition, release);
+            return new SqliteTransaction(this, partition, this.#schemaVersion ?? 0, release);
         }
         catch (error) {
             release();
@@ -464,7 +597,7 @@ export class SqliteServerStorage {
             .get(partition);
         return row?.max_commit_seq ?? 0;
     }
-    async queryAuthoritative(partition, query) {
+    async queryAuthoritative(partition, query, checkpoints) {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
@@ -479,6 +612,14 @@ export class SqliteServerStorage {
         try {
             this.db.exec('BEGIN');
             open = true;
+            // RFC 0007: evaluate the gate on this connection after BEGIN. SQLite is
+            // single-writer and the shared connection serializes writers, so the
+            // gate read and the query read cannot straddle a migration.
+            const runningVersion = this.#schemaVersion ?? 0;
+            const gate = await this.readServeGate(partition, runningVersion);
+            const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
+            if (refusal !== undefined)
+                throw serveNotReadyError(refusal);
             const rows = this.db
                 .query(prepared.sql)
                 .all(...prepared.params);
@@ -567,6 +708,177 @@ export class SqliteServerStorage {
             .get(partition, createdBeforeMs);
         return row?.seq ?? 0;
     }
+    async readServeGate(partition, runningSchemaVersion) {
+        const marker = this.db
+            .query('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+            .get();
+        const epoch = this.db
+            .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .get(partition);
+        const pending = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(runningSchemaVersion);
+        return {
+            storedSchemaVersion: marker?.schema_version ?? 0,
+            logEpoch: epoch?.log_epoch,
+            pending: pending.map((row) => ({
+                partition: row.partition,
+                name: row.name,
+            })),
+        };
+    }
+    async readCheckpoints(partition) {
+        return this.db
+            .query(`SELECT partition, name, schema_version, state, watermark,
+                owner_epoch, observed_rows, updated_at_ms
+           FROM sync_backfill_checkpoints WHERE partition=? ORDER BY name`)
+            .all(partition)
+            .map(toStoredCheckpoint);
+    }
+    /**
+     * Insert the `declared` row and raise the fence, inside the caller's open
+     * transaction. Shared by `declareCheckpoint` and the `ensureSchema`
+     * migration so the schema bump and the fence commit together. Never lowers a
+     * fence and never re-declares an existing row.
+     */
+    #installCheckpoint(partition, name, schemaVersion, nowMs) {
+        this.db
+            .query(`INSERT INTO sync_backfill_checkpoints(
+           partition, name, schema_version, state, watermark,
+           owner_epoch, observed_rows, updated_at_ms)
+         VALUES (?,?,?,'declared',0,0,0,?)
+         ON CONFLICT(partition, name) DO NOTHING`)
+            .run(partition, name, schemaVersion, nowMs);
+        this.db
+            .query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
+         VALUES (?,?)
+         ON CONFLICT(partition) DO UPDATE SET
+           required_writer_version=max(
+             sync_writer_fence.required_writer_version,
+             excluded.required_writer_version)`)
+            .run(partition, schemaVersion);
+    }
+    async declareCheckpoint(partition, name, schemaVersion, nowMs) {
+        // One transaction: the checkpoint becomes visible and the fence that
+        // protects it is raised together. The fence is raised at declaration, not
+        // at activation, so old writers are rejected for the whole backfill.
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.#installCheckpoint(partition, name, schemaVersion, nowMs);
+                const row = this.db
+                    .query(`SELECT partition, name, schema_version, state, watermark,
+                    owner_epoch, observed_rows, updated_at_ms
+               FROM sync_backfill_checkpoints WHERE partition=? AND name=?`)
+                    .get(partition, name);
+                if (row === null)
+                    throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+                this.db.exec('COMMIT');
+                return toStoredCheckpoint(row);
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
+        return this.#serializeWrite(() => {
+            // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
+            // lock a push takes. Nothing may observe activation without the fence.
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const fence = this.db
+                    .query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=?')
+                    .get(partition);
+                const checkpoint = this.db
+                    .query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?')
+                    .get(partition, name);
+                if (fence === null ||
+                    checkpoint === null ||
+                    fence.required_writer_version < checkpoint.schema_version) {
+                    // The barrier is not installed. Activating would certify a state old
+                    // writers can still decay; refuse instead of silently proceeding.
+                    throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
+                }
+                const coverage = this.#hasSourceChangesAbove(partition, sources, watermark);
+                if (coverage !== 'clean') {
+                    this.db.exec('ROLLBACK');
+                    return coverage === 'changed' ? 'stale' : 'unverifiable';
+                }
+                const updated = this.db
+                    .query(`UPDATE sync_backfill_checkpoints
+                SET state='activated', watermark=?, updated_at_ms=?
+              WHERE partition=? AND name=? AND owner_epoch=?
+                AND state<>'activated'`)
+                    .run(watermark, nowMs, partition, name, ownerEpoch);
+                this.db.exec('COMMIT');
+                return Number(updated.changes) === 1 ? 'activated' : 'stale';
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async claimCheckpoint(partition, name, schemaVersion, nowMs) {
+        return this.#serializeWrite(() => {
+            const claimed = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET owner_epoch=owner_epoch+1,
+                  state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
+                  schema_version=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND state<>'activated'
+        RETURNING partition, name, schema_version, state, watermark,
+                  owner_epoch, observed_rows, updated_at_ms`)
+                .get(schemaVersion, nowMs, partition, name);
+            if (claimed === null) {
+                throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+            }
+            return toStoredCheckpoint(claimed);
+        });
+    }
+    async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
+        return this.#serializeWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET watermark=?, observed_rows=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND owner_epoch=?`)
+                .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
+            return Number(result.changes) === 1;
+        });
+    }
+    async sourceCoverageSeq(partition, tables) {
+        if (tables.length === 0)
+            return 0;
+        const row = this.db
+            .query(`SELECT max(commit_seq) AS seq FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})`)
+            .get(partition, ...tables);
+        return row?.seq ?? 0;
+    }
+    #hasSourceChangesAbove(partition, tables, seq) {
+        // Read the horizon before the window scan: a horizon past `seq` means the
+        // history that would answer the question is gone, so an empty scan proves
+        // nothing and must not be reported as `clean`.
+        const horizon = this.db
+            .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
+            .get(partition)?.horizon_seq ?? 0;
+        if (tables.length === 0)
+            return 'clean';
+        const hit = this.db
+            .query(`SELECT 1 AS hit FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})
+            AND commit_seq>? LIMIT 1`)
+            .get(partition, ...tables, seq);
+        if (hit !== null && hit !== undefined)
+            return 'changed';
+        return horizon > seq ? 'unverifiable' : 'clean';
+    }
+    async hasSourceChangesAbove(partition, tables, seq) {
+        return this.#hasSourceChangesAbove(partition, tables, seq);
+    }
     async getRow(partition, table, rowId) {
         const record = this.db
             .query(selectRowSql(this.table(table), 'sqlite'))

package/dist/storage-errors.d.ts

@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor';
+export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
  * paths, or row data; callers branch on `code`, never message text.

package/dist/storage-errors.js

@@ -19,6 +19,10 @@ const STORAGE_QUERY_MESSAGES = {
     'sync.storage.prune_epoch_mismatch': 'partition log epoch changed; recompute retention inputs',
     'sync.storage.partition_unregistered': 'pruning requires a registered partition',
     'sync.storage.invalid_prune_cursor': 'pruning requires a non-negative safe integer cursor and a non-empty log epoch',
+    'sync.storage.checkpoint_not_declared': 'checkpoint claim requires a declared, not yet activated row',
+    'sync.storage.checkpoint_unsupported': 'this storage backend cannot declare backfill checkpoints',
+    'sync.storage.checkpoint_fence_missing': 'checkpoint activation requires the writer fence raised at declaration',
+    'sync.storage.checkpoint_incomplete': 'a declared backfill checkpoint is not activated and this caller did not declare it',
     'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
     'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',