@syncular/server 0.39.2 → 0.40.0

package/src/postgres-storage.ts

@@ -1,7 +1,11 @@
 import { validateCommitPruneQuery } from './prune';
 import { StorageQueryError } from './storage-errors';
 import type { CommitPruneQuery, CommitPruneResult } from './storage';
-import { PARTITION_TOUCH_INTERVAL_MS, serveGateRefusal } from './storage';
+import {
+  clientRoundState,
+  PARTITION_TOUCH_INTERVAL_MS,
+  serveGateRefusal,
+} from './storage';
 import { serveNotReadyError } from './readiness';
 /**
  * Postgres server storage: the production database path.
@@ -84,6 +88,7 @@ import {
   scanRowPageSql,
   indexSignature,
   schemaDdl,
+  serverIndexDdl,
   selectRowScopesSql,
   selectRowSql,
   prefetchRowsSql,
@@ -241,10 +246,16 @@ CREATE TABLE IF NOT EXISTS sync_clients(
   wire_version INTEGER NOT NULL DEFAULT 1,
   cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,
   updated_at_ms BIGINT NOT NULL,
+  last_round_at_ms BIGINT, last_error_code TEXT,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY(partition, client_id)
 );
 ALTER TABLE sync_clients
   ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS last_round_at_ms BIGINT;
+ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS last_error_code TEXT;
+ALTER TABLE sync_clients
+  ADD COLUMN IF NOT EXISTS consecutive_failures INTEGER NOT NULL DEFAULT 0;
 CREATE TABLE IF NOT EXISTS sync_blob_refs(
   partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
   blob_id TEXT NOT NULL,
@@ -339,6 +350,76 @@ async function installCheckpointOn(
   );
 }
 
+/**
+ * A scalar subquery over the table names in the JSON array bound to
+ * `namesParam`: the free-standing indexes of each table as a JSON array of
+ * `{tbl, name, unique, partial, columns}`. Parity with the SQLite/D1
+ * `origin === 'c'` filter: constraint-owned indexes (PRIMARY KEY, UNIQUE
+ * constraints) can only be removed through their constraint, so DROP INDEX on
+ * them would abort the transaction. Tables resolve through `to_regclass`,
+ * which follows the session's `search_path` like the row queries do.
+ */
+function indexesSubquery(namesParam: string): string {
+  return `(SELECT coalesce(json_agg(json_build_object(
+                  'tbl', tables.name,
+                  'name', index_class.relname,
+                  'unique', index_meta.indisunique,
+                  'partial', index_meta.indpred IS NOT NULL,
+                  'columns', ARRAY(
+                    SELECT attribute.attname::text
+                      FROM unnest(index_meta.indkey::int2[])
+                           WITH ORDINALITY AS key(attnum, ord)
+                      LEFT JOIN pg_catalog.pg_attribute AS attribute
+                        ON attribute.attrelid = index_meta.indrelid
+                       AND attribute.attnum = key.attnum
+                     WHERE key.ord <= index_meta.indnkeyatts
+                     ORDER BY key.ord))), '[]'::json)::text
+           FROM jsonb_array_elements_text(${namesParam}::text::jsonb) AS tables(name)
+           JOIN pg_catalog.pg_index AS index_meta
+             ON index_meta.indrelid = to_regclass(tables.name)
+           JOIN pg_catalog.pg_class AS index_class
+             ON index_class.oid = index_meta.indexrelid
+          WHERE NOT index_meta.indisprimary
+            AND NOT EXISTS (
+              SELECT 1
+                FROM pg_catalog.pg_constraint AS owning_constraint
+               WHERE owning_constraint.conindid = index_meta.indexrelid
+            ))`;
+}
+
+/** Table name to index name to {@link indexSignature}, from {@link indexesSubquery} JSON. */
+function parseIndexSignatures(
+  json: string,
+): Map<string, ReadonlyMap<string, string>> {
+  const byTable = new Map<string, Map<string, string>>();
+  for (const index of JSON.parse(json) as {
+    tbl: string;
+    name: string;
+    unique: boolean;
+    partial: boolean;
+    columns: (string | null)[];
+  }[]) {
+    const indexes = byTable.get(index.tbl) ?? new Map<string, string>();
+    indexes.set(
+      index.name,
+      indexSignature(index.columns, index.unique, index.partial),
+    );
+    byTable.set(index.tbl, indexes);
+  }
+  return byTable;
+}
+
+async function readIndexSignatures(
+  client: PgQueryable,
+  tableNames: readonly string[],
+): Promise<Map<string, ReadonlyMap<string, string>>> {
+  const { rows } = await client.query<{ indexes: string }>(
+    `SELECT ${indexesSubquery('$1')} AS indexes`,
+    [JSON.stringify(tableNames)],
+  );
+  return parseIndexSignatures(rows[0]?.indexes ?? '[]');
+}
+
 /** RFC 0007 serve gate on either the pool or a transaction's client. */
 async function readServeGateOn(
   client: PgQueryable,
@@ -1584,6 +1665,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
       layouts: unknown;
       incomplete: string;
       columns: string;
+      indexes: string;
     }>(
       `SELECT meta.schema_version AS schema_version, meta.layouts AS layouts,
               (SELECT coalesce(json_agg(json_build_object(
@@ -1609,7 +1691,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                  JOIN pg_attribute attribute
                    ON attribute.attrelid = to_regclass(tables.name)
                 WHERE attribute.attnum > 0
-                  AND NOT attribute.attisdropped) AS columns
+                  AND NOT attribute.attisdropped) AS columns,
+              ${indexesSubquery('$2')} AS indexes
          FROM (SELECT 1) AS one
          LEFT JOIN sync_schema_meta meta ON meta.id=1`,
       [schema.version, JSON.stringify([...schema.tables.keys()])],
@@ -1674,6 +1757,25 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
           'postgres',
         );
       }
+      // Server-only indexes reconcile at every open of a database already at
+      // this version: they never reach a client, so no version bump is needed.
+      // The unlocked read finds the common no-op case; the diff is recomputed
+      // under the migration barrier before any DDL runs.
+      const reconcile = serverIndexDdl(
+        schema,
+        parseIndexSignatures(marker.indexes),
+      );
+      if (reconcile.length > 0) {
+        await this.#exec.transaction(async (client) => {
+          await client.query('LOCK TABLE sync_partitions IN EXCLUSIVE MODE');
+          for (const statement of serverIndexDdl(
+            schema,
+            await readIndexSignatures(client, [...schema.tables.keys()]),
+          )) {
+            await client.query(statement);
+          }
+        });
+      }
     }
     if (stored === undefined || stored < schema.version) {
       // Introspect existing app tables, apply the migration subset
@@ -1721,6 +1823,9 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
         const retiredTables = retiredTableNames(schema, layouts);
         const existing = new Map<string, ReadonlySet<string>>();
         const existingIndexes = new Map<string, ReadonlyMap<string, string>>();
+        const tableIndexes = await readIndexSignatures(client, [
+          ...schema.tables.keys(),
+        ]);
         for (const table of schema.tables.values()) {
           const { rows } = await client.query<{ column_name: string }>(
             `SELECT column_name FROM information_schema.columns
@@ -1729,59 +1834,9 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
           );
           if (rows.length > 0) {
             existing.set(table.name, new Set(rows.map((r) => r.column_name)));
-            // Parity with the SQLite/D1 `origin === 'c'` filter: only
-            // free-standing indexes enter the rebuild set. Constraint-owned
-            // indexes (PRIMARY KEY, UNIQUE constraints) can only be removed
-            // through their constraint, so DROP INDEX on them would abort
-            // the migration transaction.
-            const indexes = await client.query<{
-              index_name: string;
-              is_unique: boolean;
-              is_partial: boolean;
-              columns: (string | null)[];
-            }>(
-              `SELECT index_class.relname AS index_name,
-                      index_meta.indisunique AS is_unique,
-                      index_meta.indpred IS NOT NULL AS is_partial,
-                      ARRAY(
-                        SELECT attribute.attname::text
-                          FROM unnest(index_meta.indkey::int2[])
-                               WITH ORDINALITY AS key(attnum, ord)
-                          LEFT JOIN pg_catalog.pg_attribute AS attribute
-                            ON attribute.attrelid = table_class.oid
-                           AND attribute.attnum = key.attnum
-                         WHERE key.ord <= index_meta.indnkeyatts
-                         ORDER BY key.ord
-                      ) AS columns
-                 FROM pg_catalog.pg_class AS table_class
-                 JOIN pg_catalog.pg_namespace AS namespace
-                   ON namespace.oid = table_class.relnamespace
-                 JOIN pg_catalog.pg_index AS index_meta
-                   ON index_meta.indrelid = table_class.oid
-                 JOIN pg_catalog.pg_class AS index_class
-                   ON index_class.oid = index_meta.indexrelid
-                WHERE namespace.nspname = current_schema()
-                  AND table_class.relname = $1
-                  AND NOT index_meta.indisprimary
-                  AND NOT EXISTS (
-                    SELECT 1
-                      FROM pg_catalog.pg_constraint AS owning_constraint
-                     WHERE owning_constraint.conindid = index_meta.indexrelid
-                  )`,
-              [table.name],
-            );
             existingIndexes.set(
               table.name,
-              new Map(
-                indexes.rows.map((index) => [
-                  index.index_name,
-                  indexSignature(
-                    index.columns,
-                    index.is_unique,
-                    index.is_partial,
-                  ),
-                ]),
-              ),
+              tableIndexes.get(table.name) ?? new Map(),
             );
           }
         }
@@ -2694,8 +2749,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
       cursor: unknown;
       subscriptions: unknown;
       updated_at_ms: unknown;
+      last_round_at_ms: unknown;
+      last_error_code: string | null;
+      consecutive_failures: unknown;
     }>(
-      'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2',
+      'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=$1 AND client_id=$2',
       [partition, clientId],
     );
     const record = rows[0];
@@ -2707,6 +2765,13 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
       cursor: asNumber(record.cursor),
       updatedAtMs: asNumber(record.updated_at_ms),
       subscriptions: asJson<ClientSubscription[]>(record.subscriptions),
+      ...clientRoundState(
+        record.last_round_at_ms === null
+          ? null
+          : asNumber(record.last_round_at_ms),
+        record.last_error_code,
+        asNumber(record.consecutive_failures),
+      ),
     };
   }
 
@@ -2715,13 +2780,15 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
     record: ClientRecord,
   ): Promise<void> {
     await this.#exec.query(
-      `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms)
-       VALUES ($1,$2,$3,$4,$5,$6,$7)
+      `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$7)
        ON CONFLICT (partition, client_id) DO UPDATE
          SET actor_id=EXCLUDED.actor_id, wire_version=EXCLUDED.wire_version,
              cursor=EXCLUDED.cursor,
              subscriptions=EXCLUDED.subscriptions,
-             updated_at_ms=EXCLUDED.updated_at_ms`,
+             updated_at_ms=EXCLUDED.updated_at_ms,
+             last_round_at_ms=EXCLUDED.last_round_at_ms,
+             last_error_code=NULL, consecutive_failures=0`,
       [
         partition,
         record.clientId,
@@ -2734,6 +2801,22 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
     );
   }
 
+  async recordClientRoundFailure(
+    partition: string,
+    clientId: string,
+    actorId: string,
+    errorCode: string,
+    atMs: number,
+  ): Promise<void> {
+    await this.#exec.query(
+      `UPDATE sync_clients
+         SET last_round_at_ms=$1, last_error_code=$2,
+             consecutive_failures=consecutive_failures+1
+       WHERE partition=$3 AND client_id=$4 AND actor_id=$5`,
+      [atMs, errorCode, partition, clientId, actorId],
+    );
+  }
+
   async advanceClientCursor(
     partition: string,
     clientId: string,
@@ -2910,8 +2993,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
       cursor: unknown;
       subscriptions: unknown;
       updated_at_ms: unknown;
+      last_round_at_ms: unknown;
+      last_error_code: string | null;
+      consecutive_failures: unknown;
     }>(
-      'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC',
+      'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC',
       [partition],
     );
     return rows.map((r) => ({
@@ -2923,6 +3009,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
       subscriptions: (typeof r.subscriptions === 'string'
         ? JSON.parse(r.subscriptions)
         : r.subscriptions) as ClientSubscription[],
+      ...clientRoundState(
+        r.last_round_at_ms === null ? null : asNumber(r.last_round_at_ms),
+        r.last_error_code,
+        asNumber(r.consecutive_failures),
+      ),
     }));
   }
 

package/src/relational-rows.ts

@@ -1196,3 +1196,37 @@ export function schemaDdl(
   // receiving table re-creates it.
   return [...drops, ...creates];
 }
+
+/**
+ * DDL that reconciles the server-only indexes of a database already at
+ * `schema.version`, so declaring or changing a `serverIndexes` entry needs no
+ * schema-version bump (server indexes never reach a client). It creates
+ * missing server indexes and drops every Syncular-owned index the schema no
+ * longer names. Declared `indexes` belong to the version bump and are never
+ * created or rebuilt here.
+ */
+export function serverIndexDdl(
+  schema: CompiledSchema,
+  existingIndexesByTable: ReadonlyMap<string, ReadonlyMap<string, string>>,
+): string[] {
+  const drops: string[] = [];
+  const creates: string[] = [];
+  for (const table of schema.tables.values()) {
+    const existing = existingIndexesByTable.get(table.name);
+    if (existing === undefined) continue;
+    const desired = desiredIndexes(table);
+    for (const indexName of existing.keys()) {
+      if (
+        indexName.startsWith(SYNC_INDEX_PREFIX) &&
+        !desired.some((index) => index.name === indexName)
+      ) {
+        drops.push(dropIndexDdl(indexName));
+      }
+    }
+    // `desiredIndexes` lists the declared indexes first, then the server ones.
+    for (const index of desired.slice(table.indexes.length)) {
+      if (!existing.has(index.name)) creates.push(index.ddl);
+    }
+  }
+  return [...drops, ...creates];
+}

package/src/sqlite-dialect.ts

@@ -115,6 +115,8 @@ CREATE TABLE IF NOT EXISTS sync_clients(
   wire_version INTEGER NOT NULL DEFAULT 1,
   cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,
   updated_at_ms INTEGER NOT NULL,
+  last_round_at_ms INTEGER, last_error_code TEXT,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY(partition, client_id)
 );
 CREATE TABLE IF NOT EXISTS sync_blob_refs(
@@ -145,6 +147,13 @@ CREATE TABLE IF NOT EXISTS sync_writer_fence(
 );
 `;
 
+/** Columns added to `sync_clients` after its first release, by column name. */
+export const SYNC_CLIENT_ROUND_COLUMNS = {
+  last_round_at_ms: 'INTEGER',
+  last_error_code: 'TEXT',
+  consecutive_failures: 'INTEGER NOT NULL DEFAULT 0',
+} as const;
+
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export function sqliteDdlStatements(): string[] {
   return SQLITE_DDL.split(';')

package/src/sqlite-storage.ts

@@ -2,7 +2,11 @@ import { retainRollbackFailure, rollbackAfterError } from './storage-errors';
 import { validateCommitPruneQuery } from './prune';
 import { StorageQueryError } from './storage-errors';
 import type { CommitPruneQuery, CommitPruneResult } from './storage';
-import { PARTITION_TOUCH_INTERVAL_MS, serveGateRefusal } from './storage';
+import {
+  clientRoundState,
+  PARTITION_TOUCH_INTERVAL_MS,
+  serveGateRefusal,
+} from './storage';
 import { serveNotReadyError } from './readiness';
 /**
  * SQLite server storage over the shared synchronous driver.
@@ -45,6 +49,7 @@ import {
   type StoredColumnLayout,
   scanRowPageSql,
   schemaDdl,
+  serverIndexDdl,
   SQLITE_TABLE_INDEXES_SQL,
   type SqliteTableIndexRow,
   sqliteIndexSignatures,
@@ -64,6 +69,7 @@ import {
   LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
   placeholders,
   SQLITE_DDL,
+  SYNC_CLIENT_ROUND_COLUMNS,
   type SqliteChangeRecord,
   type SqliteCommitWindowRecord,
   type SqliteRowRecord,
@@ -550,6 +556,15 @@ export class SqliteServerStorage implements ServerStorage {
         'ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1',
       );
     }
+    for (const [name, definition] of Object.entries(
+      SYNC_CLIENT_ROUND_COLUMNS,
+    )) {
+      if (!clientColumns.some((column) => column.name === name)) {
+        this.db.exec(
+          `ALTER TABLE sync_clients ADD COLUMN ${name} ${definition}`,
+        );
+      }
+    }
     const commitColumns = this.db
       .query<{ name: string }, []>('PRAGMA table_info("sync_commits")')
       .all();
@@ -649,6 +664,40 @@ END`);
           'sqlite',
         );
       }
+      // Server-only indexes reconcile at every open of a database already at
+      // this version: they never reach a client, so no version bump is needed.
+      const reconcile = serverIndexDdl(
+        schema,
+        new Map(
+          [...schema.tables.values()].map((table) => [
+            table.name,
+            new Map(
+              Object.entries(
+                sqliteIndexSignatures(
+                  this.db
+                    .query<SqliteTableIndexRow, [string]>(
+                      SQLITE_TABLE_INDEXES_SQL,
+                    )
+                    .all(table.name),
+                ),
+              ),
+            ),
+          ]),
+        ),
+      );
+      if (reconcile.length > 0) {
+        await this.#serializeWrite(() => {
+          this.db.exec('BEGIN IMMEDIATE');
+          try {
+            for (const statement of reconcile) this.db.exec(statement);
+            this.db.exec('COMMIT');
+          } catch (error) {
+            rollbackAfterError(() => {
+              this.db.exec('ROLLBACK');
+            }, error);
+          }
+        });
+      }
     }
     if (marker === null || marker.schema_version < schema.version) {
       // Introspect existing app tables, then apply the migration subset
@@ -1815,10 +1864,13 @@ END`);
           cursor: number;
           subscriptions: string;
           updated_at_ms: number;
+          last_round_at_ms: number | null;
+          last_error_code: string | null;
+          consecutive_failures: number;
         },
         [string, string]
       >(
-        'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?',
+        'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=? AND client_id=?',
       )
       .get(partition, clientId);
     if (record === null) return undefined;
@@ -1829,6 +1881,11 @@ END`);
       cursor: record.cursor,
       updatedAtMs: record.updated_at_ms,
       subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
+      ...clientRoundState(
+        record.last_round_at_ms,
+        record.last_error_code,
+        record.consecutive_failures,
+      ),
     };
   }
 
@@ -1838,7 +1895,7 @@ END`);
   ): Promise<void> {
     this.db
       .query(
-        'INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)',
+        'INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)',
       )
       .run(
         partition,
@@ -1848,9 +1905,27 @@ END`);
         record.cursor,
         JSON.stringify(record.subscriptions),
         record.updatedAtMs,
+        record.updatedAtMs,
       );
   }
 
+  async recordClientRoundFailure(
+    partition: string,
+    clientId: string,
+    actorId: string,
+    errorCode: string,
+    atMs: number,
+  ): Promise<void> {
+    this.db
+      .query(
+        `UPDATE sync_clients
+         SET last_round_at_ms=?, last_error_code=?,
+             consecutive_failures=consecutive_failures+1
+         WHERE partition=? AND client_id=? AND actor_id=?`,
+      )
+      .run(atMs, errorCode, partition, clientId, actorId);
+  }
+
   async advanceClientCursor(
     partition: string,
     clientId: string,
@@ -2006,10 +2081,13 @@ END`);
           cursor: number;
           subscriptions: string;
           updated_at_ms: number;
+          last_round_at_ms: number | null;
+          last_error_code: string | null;
+          consecutive_failures: number;
         },
         [string]
       >(
-        'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC',
+        'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC',
       )
       .all(partition);
     return records.map((record) => ({
@@ -2019,6 +2097,11 @@ END`);
       cursor: record.cursor,
       updatedAtMs: record.updated_at_ms,
       subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
+      ...clientRoundState(
+        record.last_round_at_ms,
+        record.last_error_code,
+        record.consecutive_failures,
+      ),
     }));
   }
 

package/src/storage.ts

@@ -305,6 +305,28 @@ export interface ClientRecord {
   readonly cursor: number;
   readonly updatedAtMs: number;
   readonly subscriptions: readonly ClientSubscription[];
+  /** When this client's last sync round finished, successfully or not. */
+  readonly lastRoundAtMs?: number;
+  /** Code of the last round when it failed; absent after a successful round. */
+  readonly lastErrorCode?: string;
+  /** Rounds that failed in a row since the last successful round. */
+  readonly consecutiveFailures?: number;
+}
+
+/** The round-state fields of a stored `sync_clients` row. */
+export function clientRoundState(
+  lastRoundAtMs: number | null,
+  lastErrorCode: string | null,
+  consecutiveFailures: number,
+): Pick<
+  ClientRecord,
+  'lastRoundAtMs' | 'lastErrorCode' | 'consecutiveFailures'
+> {
+  return {
+    ...(lastRoundAtMs !== null ? { lastRoundAtMs } : {}),
+    ...(lastErrorCode !== null ? { lastErrorCode } : {}),
+    ...(consecutiveFailures > 0 ? { consecutiveFailures } : {}),
+  };
 }
 
 export interface CommitWindowQuery {
@@ -917,7 +939,24 @@ export interface ServerStorage {
     partition: string,
     clientId: string,
   ): Promise<ClientRecord | undefined>;
+  /**
+   * Write the record for a completed round. The round-state fields reset: the
+   * stored last round is a success at `updatedAtMs` with no failures.
+   */
   putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+  /**
+   * Record a failed round on an existing record: set `lastRoundAtMs` and
+   * `lastErrorCode`, and increment `consecutiveFailures`. Requires a matching
+   * actor; a missing record or another actor's record is unchanged, and
+   * `updatedAtMs` (the pruning liveness signal) is never touched.
+   */
+  recordClientRoundFailure(
+    partition: string,
+    clientId: string,
+    actorId: string,
+    errorCode: string,
+    atMs: number,
+  ): Promise<void>;
   /**
    * Atomically advance an existing record's cursor and activity timestamp.
    * Preserve registration fields; require matching actor and current log epoch.