@syncular/client 0.30.12 → 0.30.14

package/src/failed-overlay.ts

@@ -1,3 +1,6 @@
+import { hasUniqueIndex } from './schema';
+import { OUTCOMES_TABLE } from './outcomes';
+import { OUTBOX_TABLE } from './outbox';
 export const RETAINED_ROWS = '_syncular_failed_rows';
 import { ClientSyncError } from './errors';
 import type { ClientDatabase } from './database';
@@ -48,7 +51,7 @@ export function retainedBaseWrite(
     table.name,
     rowId,
   ]);
-  if (!table.indexes.some((index) => index.unique)) return;
+  if (!hasUniqueIndex(table)) return;
   for (const retained of db.query(
     `SELECT commit_id,idx,intent,unique_conflicts FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq IS NULL`,
     [table.name],
@@ -164,90 +167,51 @@ export function uniqueConflicts(
     );
 }
 
-function retainedRows(db: ClientDatabase, rowKeys?: readonly string[]) {
+/** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
+export type OverlayScope = readonly string[];
+
+export function overlayScopePredicate(table: string, id: string): string {
+  return `?1 IS NULL OR json_array(${table},${id}) IN(SELECT value FROM json_each(?1)) OR json_array(${table}) IN(SELECT value FROM json_each(?1))`;
+}
+
+function retainedRows(
+  db: ClientDatabase,
+  scope?: OverlayScope,
+  acknowledged?: boolean,
+) {
   return db.query(
-    `SELECT * FROM ${RETAINED_ROWS} WHERE ?1 IS NULL OR json_array(tbl,id) IN(SELECT value FROM json_each(?1)) ORDER BY commit_seq,at,commit_id,idx`,
-    [rowKeys ? JSON.stringify(rowKeys) : null],
+    `SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
+    [scope ? JSON.stringify(scope) : null],
   );
 }
 
+function retainedTable(
+  schema: CompiledClientSchema,
+  name: string,
+): CompiledClientTable {
+  const table = schema.tables.get(name);
+  if (!table)
+    throw new ClientSyncError(
+      'sync.unknown_table',
+      'retained table is unknown',
+    );
+  return table;
+}
+
 export function restoreFailedBases(
   db: ClientDatabase,
   schema: CompiledClientSchema,
-  absentIntent = false,
-  rowKeys?: readonly string[],
+  scope?: OverlayScope,
 ): boolean {
   const seen = new Set<string>();
-  for (const row of retainedRows(db, rowKeys)) {
+  for (const row of retainedRows(db, scope)) {
     const key = JSON.stringify([row.tbl, row.id]);
-    if (!absentIntent && seen.has(key)) continue;
+    if (seen.has(key)) continue;
     seen.add(key);
-    const table = schema.tables.get(row.tbl as string);
-    if (!table)
-      throw new ClientSyncError(
-        'sync.unknown_table',
-        'retained table is unknown',
-      );
-    const json = absentIntent ? row.intent : row.base;
-    if (absentIntent && row.intent !== null) {
-      const values: Record<string, JsonRowValue> = JSON.parse(
-        row.intent as string,
-      );
-      const conflicts = uniqueConflicts(
-        db,
-        table,
-        mapRowValues(values, jsonToRowValue),
-      );
-      // Hydrate a pre-0.30.11 failure after its winner was already imported.
-      // Pending and retained overlays cannot supply authoritative row evidence.
-      if (row.commit_seq === null && row.unique_conflicts === null) {
-        const authorized = conflicts.filter(
-          (conflict) =>
-            conflict.serverVersion >= 0 &&
-            !db.query(
-              `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM _syncular_outbox,json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
-              [table.name, conflict.rowId, table.name, conflict.rowId],
-            ).length,
-        );
-        if (authorized.length)
-          db.exec(
-            `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
-            [
-              JSON.stringify(
-                authorized.map((conflict) => ({
-                  ...conflict,
-                  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
-                })),
-              ),
-              row.commit_id as string,
-              row.idx as number,
-            ],
-          );
-      }
-      if (conflicts.length) continue;
-    }
-    if (
-      absentIntent &&
-      (json === null ||
-        db.query(
-          `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-          [row.id as string],
-        ).length)
-    )
-      continue;
-    if (json === null) deleteLocalRow(db, table, row.id as string, false);
+    const table = retainedTable(schema, row.tbl as string);
+    if (row.base === null) deleteLocalRow(db, table, row.id as string, false);
     else {
-      const values: Record<string, JsonRowValue> = JSON.parse(String(json));
-      if (absentIntent) {
-        const operation: OutboxOperation = JSON.parse(row.op as string);
-        if (
-          row.commit_seq === null &&
-          !table.columns.every((column) =>
-            Object.hasOwn(operation.values ?? {}, column.name),
-          )
-        )
-          continue;
-      }
+      const values: Record<string, JsonRowValue> = JSON.parse(String(row.base));
       upsertLocalRow(
         db,
         table,
@@ -265,7 +229,8 @@ export function restoreFailedBases(
 export function failedOverlayCommits(
   db: ClientDatabase,
   acknowledged = false,
-  rowKeys?: readonly string[],
+  scope?: OverlayScope,
+  schema?: CompiledClientSchema,
 ): OutboxCommit[] {
   const commits = new Map<
     string,
@@ -276,10 +241,55 @@ export function failedOverlayCommits(
       operations: OutboxOperation[];
     }
   >();
-  for (const row of retainedRows(db, rowKeys)) {
-    if ((row.commit_seq !== null) !== acknowledged) continue;
+  for (const row of retainedRows(db, scope, acknowledged)) {
     const id = row.commit_id as string;
-    const operation: OutboxOperation = JSON.parse(row.op as string);
+    let operation: OutboxOperation = JSON.parse(row.op as string);
+    if (schema && operation.op === 'upsert') {
+      const table = retainedTable(schema, operation.table);
+      if (acknowledged) {
+        if (
+          !db.query(
+            `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
+            [operation.rowId],
+          ).length
+        )
+          operation = {
+            ...operation,
+            values: JSON.parse(row.intent as string),
+          };
+      } else if (row.unique_conflicts === null && row.intent !== null) {
+        // Hydrate legacy failure evidence from authoritative unique-key peers.
+        const values: Record<string, JsonRowValue> = JSON.parse(
+          row.intent as string,
+        );
+        const authorized = uniqueConflicts(
+          db,
+          table,
+          mapRowValues(values, jsonToRowValue),
+        ).filter(
+          (conflict) =>
+            conflict.serverVersion >= 0 &&
+            !db.query(
+              `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_TABLE},json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
+              [table.name, conflict.rowId, table.name, conflict.rowId],
+            ).length,
+        );
+        if (authorized.length)
+          db.exec(
+            `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
+            [
+              JSON.stringify(
+                authorized.map((conflict) => ({
+                  ...conflict,
+                  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
+                })),
+              ),
+              row.commit_id as string,
+              row.idx as number,
+            ],
+          );
+      }
+    }
     const prior = commits.get(id);
     if (prior) prior.operations.push(operation);
     else
@@ -295,6 +305,7 @@ export function failedOverlayCommits(
 
 export function dropFailedRows(
   db: ClientDatabase,
+  schema: CompiledClientSchema,
   matches: (
     table: string,
     values: Readonly<Record<string, JsonRowValue>>,
@@ -312,10 +323,17 @@ export function dropFailedRows(
     ...failedOverlayCommits(db),
     ...failedOverlayCommits(db, true),
   ].filter((commit) => ids.has(commit.clientCommitId));
+  restoreFailedBases(
+    db,
+    schema,
+    dropped.flatMap((commit) =>
+      commit.operations.map((op) => JSON.stringify([op.table, op.rowId])),
+    ),
+  );
   for (const id of ids) {
     db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [id]);
     db.exec(
-      "UPDATE _syncular_commit_outcomes SET operations=NULL,results='[]' WHERE client_commit_id=?",
+      `UPDATE ${OUTCOMES_TABLE} SET operations=NULL,results='[]' WHERE client_commit_id=?`,
       [id],
     );
   }

package/src/outbox.ts

@@ -1,3 +1,7 @@
+import { BLOB_COMMIT_REFS } from './blob';
+export const OUTBOX_TABLE = '_syncular_outbox';
+export const OUTBOX_IMAGES = '_syncular_outbox_before_images';
+import { overlayScopePredicate, type OverlayScope } from './failed-overlay';
 /**
  * The durable outbox (SPEC.md §7.1) with encode-at-send (the §0 binary-push
  * outbox rule): local mutations are persisted in a schema-agnostic JSON
@@ -68,7 +72,7 @@ export function appendOutboxCommit(
     );
   }
   db.exec(
-    'INSERT INTO _syncular_outbox(client_commit_id,created_at_ms,operations)VALUES(?,?,?)',
+    `INSERT INTO ${OUTBOX_TABLE}(client_commit_id,created_at_ms,operations)VALUES(?,?,?)`,
     [clientCommitId, nowMs, JSON.stringify(operations)],
   );
   replaceOutboxBeforeImages(db, clientCommitId, beforeImages);
@@ -77,14 +81,14 @@ export function appendOutboxCommit(
 /** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
 export function listOutbox(
   db: ClientDatabase,
-  rowKeys?: readonly string[],
+  scope?: OverlayScope,
 ): OutboxCommit[] {
   return db
     .query(
-      rowKeys === undefined
-        ? 'SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox ORDER BY seq ASC'
-        : "SELECT * FROM _syncular_outbox WHERE EXISTS(SELECT 1 FROM json_each(operations) WHERE json_array(json_extract(value,'$.table'),json_extract(value,'$.rowId')) IN(SELECT value FROM json_each(?))) ORDER BY seq",
-      rowKeys && [JSON.stringify(rowKeys)],
+      scope === undefined
+        ? `SELECT * FROM ${OUTBOX_TABLE} ORDER BY seq ASC`
+        : `SELECT * FROM ${OUTBOX_TABLE} WHERE EXISTS(SELECT 1 FROM json_each(operations) WHERE ${overlayScopePredicate("json_extract(value,'$.table')", "json_extract(value,'$.rowId')")}) ORDER BY seq`,
+      scope && [JSON.stringify(scope)],
     )
     .map(decodeOutboxRow);
 }
@@ -106,7 +110,7 @@ export function* iterateOutbox(
   let afterSeq = 0;
   while (afterSeq < throughSeq) {
     const rows = db.query(
-      'SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32',
+      `SELECT * FROM ${OUTBOX_TABLE} WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32`,
       [afterSeq, throughSeq],
     );
     if (rows.length === 0) return;
@@ -120,7 +124,7 @@ export function* iterateOutbox(
 
 /** Routine status reads never load operation bodies. */
 export function countOutbox(db: ClientDatabase): number {
-  return db.query('SELECT COUNT(*)AS count FROM _syncular_outbox')[0]!
+  return db.query(`SELECT COUNT(*)AS count FROM ${OUTBOX_TABLE}`)[0]!
     .count as number;
 }
 
@@ -128,14 +132,13 @@ export function deleteOutboxCommit(
   db: ClientDatabase,
   clientCommitId: string,
 ): void {
-  db.exec('DELETE FROM _syncular_blob_commit_refs WHERE commit_id=?', [
+  db.exec(`DELETE FROM ${BLOB_COMMIT_REFS} WHERE commit_id=?`, [
     clientCommitId,
   ]);
-  db.exec(
-    'DELETE FROM _syncular_outbox_before_images WHERE client_commit_id=?',
-    [clientCommitId],
-  );
-  db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id=?', [
+  db.exec(`DELETE FROM ${OUTBOX_IMAGES} WHERE client_commit_id=?`, [
+    clientCommitId,
+  ]);
+  db.exec(`DELETE FROM ${OUTBOX_TABLE} WHERE client_commit_id=?`, [
     clientCommitId,
   ]);
 }
@@ -146,7 +149,7 @@ export function listOutboxBeforeImages(
 ): OutboxBeforeImage[] {
   return db
     .query(
-      'SELECT op_index,existed,sync_version,values_json,delivery_seq FROM _syncular_outbox_before_images WHERE client_commit_id=? ORDER BY op_index',
+      `SELECT op_index,existed,sync_version,values_json,delivery_seq FROM ${OUTBOX_IMAGES} WHERE client_commit_id=? ORDER BY op_index`,
       [clientCommitId],
     )
     .map((row) => ({
@@ -175,7 +178,7 @@ export function replaceOutboxBeforeImages(
 ): void {
   for (const image of replacements) {
     db.exec(
-      'INSERT INTO _syncular_outbox_before_images(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?) ON CONFLICT(client_commit_id,op_index)DO UPDATE SET existed=excluded.existed,sync_version=excluded.sync_version,values_json=excluded.values_json',
+      `INSERT INTO ${OUTBOX_IMAGES}(client_commit_id,op_index,existed,sync_version,values_json)VALUES(?,?,?,?,?) ON CONFLICT(client_commit_id,op_index)DO UPDATE SET existed=excluded.existed,sync_version=excluded.sync_version,values_json=excluded.values_json`,
       [
         clientCommitId,
         image.opIndex,

package/src/outcomes.ts

@@ -1,3 +1,5 @@
+export const OUTCOMES_TABLE = '_syncular_commit_outcomes';
+const SELECT_OUTCOME = `SELECT * FROM ${OUTCOMES_TABLE}`;
 import { RETAINED_ROWS } from './failed-overlay';
 /**
  * Durable per-client commit outcomes.
@@ -233,7 +235,7 @@ export function recordCommitOutcome(
   outcome: Omit<CommitOutcome, 'sequence' | 'resolution'>,
 ): CommitOutcome {
   db.exec(
-    "INSERT INTO _syncular_commit_outcomes(client_commit_id,status,recorded_at_ms,results,operations,resolution)VALUES(?,?,?,?,?,'active')",
+    `INSERT INTO ${OUTCOMES_TABLE}(client_commit_id,status,recorded_at_ms,results,operations,resolution)VALUES(?,?,?,?,?,'active')`,
     [
       outcome.clientCommitId,
       outcome.status,
@@ -251,10 +253,9 @@ export function commitOutcome(
   db: ClientDatabase,
   clientCommitId: string,
 ): CommitOutcome | undefined {
-  const row = db.query(
-    'SELECT seq,client_commit_id,status,recorded_at_ms,results,operations,resolution,resolved_at_ms,replacement_client_commit_id FROM _syncular_commit_outcomes WHERE client_commit_id=?',
-    [clientCommitId],
-  )[0];
+  const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
+    clientCommitId,
+  ])[0];
   return row === undefined ? undefined : parseOutcome(db, row);
 }
 
@@ -273,7 +274,7 @@ export function listCommitOutcomes(
     ? "WHERE resolution = 'active' AND status IN ('conflict', 'rejected')"
     : '';
   const rows = db.query(
-    `SELECT seq,client_commit_id,status,recorded_at_ms,results,operations,resolution,resolved_at_ms,replacement_client_commit_id FROM _syncular_commit_outcomes ${where} ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`,
+    `${SELECT_OUTCOME} ${where} ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`,
     limit === undefined ? [] : [limit],
   );
   return rows.map((row) => parseOutcome(db, row));
@@ -285,7 +286,7 @@ export function persistCommitOutcomeResolution(
   nowMs: number,
 ): CommitOutcome | undefined {
   db.exec(
-    "UPDATE _syncular_commit_outcomes SET resolution=?,resolved_at_ms=?,replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'",
+    `UPDATE ${OUTCOMES_TABLE} SET resolution=?,resolved_at_ms=?,replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'`,
     [
       input.resolution,
       nowMs,
@@ -310,17 +311,16 @@ export function pruneCommitOutcomes(
       'outcome retention maxEntries must be a positive safe integer',
     );
   }
-  const count = db.query(
-    'SELECT COUNT(*) AS count FROM _syncular_commit_outcomes',
-  )[0]?.count as number | undefined;
+  const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
+    ?.count as number | undefined;
   const excess = Math.max(0, (count ?? 0) - maxEntries);
   if (excess === 0) return 0;
   const candidates = db.query(
-    "SELECT seq FROM _syncular_commit_outcomes WHERE status IN('applied','cached')OR resolution !='active' ORDER BY seq ASC LIMIT ?",
+    `SELECT seq FROM ${OUTCOMES_TABLE} WHERE status IN('applied','cached')OR resolution !='active' ORDER BY seq ASC LIMIT ?`,
     [excess],
   );
   for (const candidate of candidates) {
-    db.exec('DELETE FROM _syncular_commit_outcomes WHERE seq=?', [
+    db.exec(`DELETE FROM ${OUTCOMES_TABLE} WHERE seq=?`, [
       candidate.seq as number,
     ]);
   }

package/src/previous-version.ts

@@ -42,7 +42,7 @@ import {
   quoteIdent,
   rowValueToJson,
 } from './schema';
-import { getMeta, setMeta } from './state';
+import { getMeta, setMeta, META_TABLE } from './state';
 
 /** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
 const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
@@ -724,7 +724,7 @@ export function writePreviousVersionRefusal(
 
 /** Delete the durable refusal. Part of the orphan sweep and of a successful capture. */
 export function clearPreviousVersionRefusal(db: ClientDatabase): void {
-  db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+  db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
     PREVIOUS_VERSION_CONTEXT_KEY,
   ]);
 }
@@ -892,7 +892,7 @@ export function writePreviousVersionAudit(
 
 /** Delete the advisory audit. Part of a discard, never of a normal bump. */
 export function clearPreviousVersionAudit(db: ClientDatabase): void {
-  db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+  db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
     PREVIOUS_VERSION_AUDIT_KEY,
   ]);
 }

package/src/schema.ts

@@ -1,3 +1,9 @@
+import { BLOB_COMMIT_REFS } from './blob';
+import { PENDING_EVICTIONS } from './window';
+import { WINDOWS_TABLE } from './window';
+import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox';
+import { OUTCOMES_TABLE } from './outcomes';
+import { SUBSCRIPTIONS_TABLE, META_TABLE } from './state';
 import { ensureFailedOverlaySchema } from './failed-overlay';
 /**
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
@@ -265,6 +271,10 @@ export function stripSyncColumns(rows: SqlRow[]): SqlRow[] {
   });
 }
 
+export function hasUniqueIndex(table: CompiledClientTable): boolean {
+  return table.indexes.some((index) => index.unique);
+}
+
 export function matchesLocalScopes(
   table: CompiledClientTable,
   scopes: Readonly<Record<string, readonly string[]>>,
@@ -531,64 +541,60 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
     ensureFailedOverlaySchema(db);
     const createTable = (name: string, columns: string) =>
       db.exec(`CREATE TABLE IF NOT EXISTS ${name}(${columns})`);
-    createTable('_syncular_meta', 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
+    createTable(META_TABLE, 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
     createTable(
-      '_syncular_blob_commit_refs',
+      BLOB_COMMIT_REFS,
       'commit_id TEXT NOT NULL,blob_id TEXT NOT NULL,PRIMARY KEY(commit_id,blob_id)',
     );
     db.exec(
-      'CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)',
+      `CREATE INDEX IF NOT EXISTS ${BLOB_COMMIT_REFS}_body ON ${BLOB_COMMIT_REFS}(blob_id)`,
     );
     db.exec(
-      "INSERT OR IGNORE INTO _syncular_meta(key,value)VALUES('localRevision','0')",
+      `INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`,
     );
     createTable(
-      '_syncular_outbox',
+      OUTBOX_TABLE,
       'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL',
     );
     createTable(
-      '_syncular_outbox_before_images',
+      OUTBOX_IMAGES,
       'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)',
     );
     if (
       !db
-        .query('PRAGMA table_info(_syncular_outbox_before_images)')
+        .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
         .some((row) => row.name === 'delivery_seq')
     )
-      db.exec(
-        'ALTER TABLE _syncular_outbox_before_images ADD COLUMN delivery_seq INTEGER',
-      );
+      db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
     createTable(
-      '_syncular_commit_outcomes',
+      OUTCOMES_TABLE,
       "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT",
     );
     // Outcomes created before durable aggregate recovery retain no commit
     // envelope. New failed outcomes store it in the protected client DB.
     try {
-      db.exec(
-        'ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations TEXT',
-      );
+      db.exec(`ALTER TABLE ${OUTCOMES_TABLE} ADD COLUMN operations TEXT`);
     } catch {
       // column already exists — the CREATE above included it
     }
     db.exec(
-      'CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq ON _syncular_commit_outcomes(resolution,seq)',
+      `CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`,
     );
     createTable(
-      '_syncular_subscriptions',
+      SUBSCRIPTIONS_TABLE,
       "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT",
     );
     // §4.8 window registry: which units (scope values) of a window base are
     // live locally — the completeness oracle (I3) and the shrink driver
     // (a unit's omission from the next pull unregisters it, §4.1).
     createTable(
-      '_syncular_windows',
+      WINDOWS_TABLE,
       'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
     );
     // §4.8 E1: units that left the window but still had outbox-pinned rows.
     // Retried when the outbox drains; cancelled if the unit re-enters.
     createTable(
-      '_syncular_window_pending_evict',
+      PENDING_EVICTIONS,
       'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL',
     );
   });

package/src/state.ts

@@ -1,3 +1,7 @@
+export const META_TABLE = '_syncular_meta';
+import { PENDING_EVICTIONS } from './window';
+import { WINDOWS_TABLE } from './window';
+export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
 /**
  * Durable client sync state: per-subscription cursor, bootstrap resume
  * token (round-tripped opaquely, §4.7), and the last-echoed effective
@@ -58,7 +62,7 @@ function rowToRecord(row: Record<string, unknown>): SubscriptionRecord {
 
 export function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[] {
   return db
-    .query('SELECT * FROM _syncular_subscriptions ORDER BY rowid ASC')
+    .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
     .map(rowToRecord);
 }
 
@@ -66,7 +70,7 @@ export function getSubscription(
   db: ClientDatabase,
   id: string,
 ): SubscriptionRecord | undefined {
-  const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id=?', [
+  const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [
     id,
   ])[0];
   return row === undefined ? undefined : rowToRecord(row);
@@ -77,7 +81,7 @@ export function saveSubscription(
   record: SubscriptionRecord,
 ): void {
   db.exec(
-    'INSERT OR REPLACE INTO _syncular_subscriptions(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)',
+    `INSERT OR REPLACE INTO ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`,
     [
       record.id,
       record.table,
@@ -95,7 +99,7 @@ export function saveSubscription(
 }
 
 export function deleteSubscription(db: ClientDatabase, id: string): void {
-  db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+  db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
 }
 
 /**
@@ -107,7 +111,7 @@ export function deleteSubscription(db: ClientDatabase, id: string): void {
  */
 export function resetSubscriptionsForBump(db: ClientDatabase): void {
   db.exec(
-    "UPDATE _syncular_subscriptions SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL",
+    `UPDATE ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`,
   );
 }
 
@@ -184,7 +188,7 @@ export function pruneUnknownSubscriptions(
   // Shrinking a pinned window already removed its registration. Its deferred
   // eviction still carries the old scope declaration and needs the same fence.
   for (const row of db.query(
-    'SELECT sub_id,tbl,effective_scopes FROM _syncular_window_pending_evict',
+    `SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
   )) {
     if (
       !compatible({
@@ -197,25 +201,21 @@ export function pruneUnknownSubscriptions(
   if (staleIds.size === 0) return retained;
   db.transaction(() => {
     for (const id of staleIds) {
-      db.exec('DELETE FROM _syncular_windows WHERE sub_id=?', [id]);
-      db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id=?', [
-        id,
-      ]);
-      db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+      db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
+      db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
+      db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
     }
   });
   return retained;
 }
 
 export function getMeta(db: ClientDatabase, key: string): string | undefined {
-  const row = db.query('SELECT value FROM _syncular_meta WHERE key=?', [
-    key,
-  ])[0];
+  const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
   return row === undefined ? undefined : (row.value as string);
 }
 
 export function setMeta(db: ClientDatabase, key: string, value: string): void {
-  db.exec('INSERT OR REPLACE INTO _syncular_meta(key,value)VALUES(?,?)', [
+  db.exec(`INSERT OR REPLACE INTO ${META_TABLE}(key,value)VALUES(?,?)`, [
     key,
     value,
   ]);