@syncular/server 0.40.0 → 0.41.0

package/dist/d1-storage.d.ts

@@ -42,7 +42,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
  */
 import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -123,7 +123,7 @@ export declare class D1ServerStorage implements ServerStorage {
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
-    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
     recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
     advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
     updateClientCursor(partition: string, clientId: string, cursor: number, updatedAtMs: number): Promise<void>;

package/dist/d1-storage.js

@@ -1605,10 +1605,11 @@ export class D1ServerStorage {
             ...clientRoundState(record.last_round_at_ms, record.last_error_code, record.consecutive_failures),
         };
     }
-    async putClientRecord(partition, record) {
+    async putClientRecord(partition, record, options) {
         // Update the existing record in place, so the table keeps one row per
         // (partition, client_id). Every non-key field is written from the new
         // record; a delete-and-insert would drop and recreate the row instead.
+        // `keepRoundOutcome` leaves the round-state columns alone (§1.5, §4.5).
         await this.#db
             .prepare(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
          ON CONFLICT(partition, client_id) DO UPDATE SET
@@ -1617,9 +1618,11 @@ export class D1ServerStorage {
            cursor=excluded.cursor,
            subscriptions=excluded.subscriptions,
            updated_at_ms=excluded.updated_at_ms,
-           last_round_at_ms=excluded.last_round_at_ms,
+           last_round_at_ms=excluded.last_round_at_ms${options?.keepRoundOutcome === true
+            ? ''
+            : `,
            last_error_code=NULL,
-           consecutive_failures=0`)
+           consecutive_failures=0`}`)
             .bind(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs, record.updatedAtMs)
             .run();
     }

package/dist/handler.js

@@ -106,10 +106,13 @@ async function planRequest(request, ctx, schema, registry) {
         throw syncError('sync.invalid_request', 'missing REQ_HEADER');
     }
     const pushes = [];
+    let roundFailure;
     let pull;
     const subFrames = [];
     for (const frame of request.frames) {
-        if (frame.type === 'PUSH_COMMIT')
+        if (frame.type === 'ROUND_FAILURE')
+            roundFailure = frame;
+        else if (frame.type === 'PUSH_COMMIT')
             pushes.push(frame);
         else if (frame.type === 'PULL_HEADER')
             pull = frame;
@@ -130,6 +133,7 @@ async function planRequest(request, ctx, schema, registry) {
             logEpoch: registry.logEpoch,
             epochReset,
             header,
+            roundFailure,
             pushes,
             pull,
             subscriptions: [],
@@ -144,6 +148,7 @@ async function planRequest(request, ctx, schema, registry) {
             logEpoch: registry.logEpoch,
             epochReset: true,
             header,
+            roundFailure,
             pushes: [],
             pull: undefined,
             subscriptions: [],
@@ -212,6 +217,7 @@ async function planRequest(request, ctx, schema, registry) {
         logEpoch: registry.logEpoch,
         epochReset: false,
         header,
+        roundFailure,
         pushes,
         pull,
         subscriptions,
@@ -483,7 +489,11 @@ async function* streamResponse(plan, ctx, schema, report) {
             cursor,
             updatedAtMs: clockOf(ctx)(),
             subscriptions,
-        });
+        }, 
+        // §4.5: a round that carried a `ROUND_FAILURE` report completes without
+        // clearing the reported code and streak; the next request without the
+        // frame clears them as a plain completed round does.
+        plan.roundFailure !== undefined ? { keepRoundOutcome: true } : undefined);
         if (ctx.realtime?.notifySubscriptions !== undefined &&
             JSON.stringify((previous?.subscriptions ?? []).map((s) => [s.id, s.table, s.scopes])) !== JSON.stringify(subscriptions.map((s) => [s.id, s.table, s.scopes]))) {
             await ctx.realtime.notifySubscriptions(ctx.partition, plan.header.clientId);
@@ -583,10 +593,15 @@ function requestClientId(bytes) {
  * `onError` and never replaces the round's own outcome.
  */
 async function recordRoundFailure(ctx, clientId, error) {
+    await recordRoundFailureCode(ctx, clientId, error instanceof SyncError ? error.code : 'sync.internal_error');
+}
+/** As `recordRoundFailure`, for a code that is not a thrown catalog error
+ * (a `ROUND_FAILURE` report, §1.5). */
+async function recordRoundFailureCode(ctx, clientId, code) {
     if (clientId === undefined)
         return;
     try {
-        await ctx.storage.recordClientRoundFailure(ctx.partition, clientId, ctx.actorId, error instanceof SyncError ? error.code : 'sync.internal_error', clockOf(ctx)());
+        await ctx.storage.recordClientRoundFailure(ctx.partition, clientId, ctx.actorId, code, clockOf(ctx)());
     }
     catch (failure) {
         reportError(failure, ctx.onError, 'sync');
@@ -648,6 +663,12 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
         candidate.version === header.schemaVersion);
     const served = selected ?? schema;
     const plan = await planRequest(request, ctx, served, registry);
+    // §1.5/§4.5: record the reported round failure on the existing record
+    // before the round runs (it never creates one, never touches another
+    // actor's record). The completion of this round leaves it in place.
+    if (plan.roundFailure !== undefined) {
+        await recordRoundFailureCode(ctx, plan.header.clientId, plan.roundFailure.code);
+    }
     const report = { outcome: 'ok' };
     // RFC 0007 read-verify-refuse for the streamed read path: the generator
     // builds the whole response (its data reads) before yielding the first

package/dist/postgres-storage.d.ts

@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -129,7 +129,7 @@ export declare class PostgresServerStorage implements ServerStorage {
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
-    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
     recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
     advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
     updateClientCursor(partition: string, clientId: string, cursor: number, updatedAtMs: number): Promise<void>;

package/dist/postgres-storage.js

@@ -1827,7 +1827,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                 : asNumber(record.last_round_at_ms), record.last_error_code, asNumber(record.consecutive_failures)),
         };
     }
-    async putClientRecord(partition, record) {
+    async putClientRecord(partition, record, options) {
         await this.#exec.query(`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
@@ -1835,8 +1835,9 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
              cursor=EXCLUDED.cursor,
              subscriptions=EXCLUDED.subscriptions,
              updated_at_ms=EXCLUDED.updated_at_ms,
-             last_round_at_ms=EXCLUDED.last_round_at_ms,
-             last_error_code=NULL, consecutive_failures=0`, [
+             last_round_at_ms=EXCLUDED.last_round_at_ms${options?.keepRoundOutcome === true
+            ? ''
+            : ',\n             last_error_code=NULL, consecutive_failures=0'}`, [
             partition,
             record.clientId,
             record.actorId,

package/dist/sqlite-storage.d.ts

@@ -2,7 +2,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
@@ -56,7 +56,7 @@ export declare class SqliteServerStorage implements ServerStorage {
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
-    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
     recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
     advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
     updateClientCursor(partition: string, clientId: string, cursor: number, updatedAtMs: number): Promise<void>;

package/dist/sqlite-storage.js

@@ -1175,9 +1175,20 @@ END`);
             ...clientRoundState(record.last_round_at_ms, record.last_error_code, record.consecutive_failures),
         };
     }
-    async putClientRecord(partition, record) {
+    async putClientRecord(partition, record, options) {
         this.db
-            .query('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)')
+            .query(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
+         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,
+           last_round_at_ms=excluded.last_round_at_ms${options?.keepRoundOutcome === true
+            ? ''
+            : `,
+           last_error_code=NULL,
+           consecutive_failures=0`}`)
             .run(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs, record.updatedAtMs);
     }
     async recordClientRoundFailure(partition, clientId, actorId, errorCode, atMs) {

package/dist/storage.d.ts

@@ -242,6 +242,15 @@ export interface ClientRecord {
     /** Rounds that failed in a row since the last successful round. */
     readonly consecutiveFailures?: number;
 }
+/** `putClientRecord` options. */
+export interface ClientRecordWriteOptions {
+    /**
+     * Leave the stored round outcome (`lastErrorCode`, `consecutiveFailures`)
+     * untouched. Set for a completed round that carried a `ROUND_FAILURE` report
+     * (§1.5, §4.5). `lastRoundAtMs` still moves to this round's completion.
+     */
+    readonly keepRoundOutcome?: boolean;
+}
 /** The round-state fields of a stored `sync_clients` row. */
 export declare function clientRoundState(lastRoundAtMs: number | null, lastErrorCode: string | null, consecutiveFailures: number): Pick<ClientRecord, 'lastRoundAtMs' | 'lastErrorCode' | 'consecutiveFailures'>;
 export interface CommitWindowQuery {
@@ -690,9 +699,11 @@ export interface ServerStorage {
     getClientRecord(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.
+     * stored last round is a success at `updatedAtMs` with no failures — unless
+     * `keepRoundOutcome` is set, which leaves the reported code and streak in
+     * place (the round carried a `ROUND_FAILURE` report, §1.5/§4.5).
      */
-    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
     /**
      * Record a failed round on an existing record: set `lastRoundAtMs` and
      * `lastErrorCode`, and increment `consecutiveFailures`. Requires a matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.40.0"
+    "@syncular/core": "0.41.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/d1-storage.ts

@@ -116,6 +116,7 @@ import type {
   ClientCursorInfo,
   ClientPushResult,
   ClientRecord,
+  ClientRecordWriteOptions,
   ClientSubscription,
   CommitChangeSummary,
   CommitDetail,
@@ -2416,10 +2417,12 @@ export class D1ServerStorage implements ServerStorage {
   async putClientRecord(
     partition: string,
     record: ClientRecord,
+    options?: ClientRecordWriteOptions,
   ): Promise<void> {
     // Update the existing record in place, so the table keeps one row per
     // (partition, client_id). Every non-key field is written from the new
     // record; a delete-and-insert would drop and recreate the row instead.
+    // `keepRoundOutcome` leaves the round-state columns alone (§1.5, §4.5).
     await this.#db
       .prepare(
         `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
@@ -2429,9 +2432,13 @@ export class D1ServerStorage implements ServerStorage {
            cursor=excluded.cursor,
            subscriptions=excluded.subscriptions,
            updated_at_ms=excluded.updated_at_ms,
-           last_round_at_ms=excluded.last_round_at_ms,
+           last_round_at_ms=excluded.last_round_at_ms${
+             options?.keepRoundOutcome === true
+               ? ''
+               : `,
            last_error_code=NULL,
-           consecutive_failures=0`,
+           consecutive_failures=0`
+           }`,
       )
       .bind(
         partition,

package/src/handler.ts

@@ -19,6 +19,7 @@ import {
   type ReqHeaderFrame,
   type RequestMessage,
   type ResponseFrame,
+  type RoundFailureFrame,
   type ScopeMap,
   type SubscriptionFrame,
 } from '@syncular/core';
@@ -70,6 +71,8 @@ interface RequestPlan {
   readonly logEpoch: string;
   readonly epochReset: boolean;
   readonly header: ReqHeaderFrame;
+  /** §1.5: the code this request reports for its last unseen round failure. */
+  readonly roundFailure: RoundFailureFrame | undefined;
   readonly pushes: readonly PushCommitFrame[];
   readonly pull: PullHeaderFrame | undefined;
   readonly subscriptions: readonly SubscriptionPlan[];
@@ -212,10 +215,12 @@ async function planRequest(
     throw syncError('sync.invalid_request', 'missing REQ_HEADER');
   }
   const pushes: PushCommitFrame[] = [];
+  let roundFailure: RoundFailureFrame | undefined;
   let pull: PullHeaderFrame | undefined;
   const subFrames: SubscriptionFrame[] = [];
   for (const frame of request.frames) {
-    if (frame.type === 'PUSH_COMMIT') pushes.push(frame);
+    if (frame.type === 'ROUND_FAILURE') roundFailure = frame;
+    else if (frame.type === 'PUSH_COMMIT') pushes.push(frame);
     else if (frame.type === 'PULL_HEADER') pull = frame;
     else if (frame.type === 'SUBSCRIPTION') subFrames.push(frame);
   }
@@ -241,6 +246,7 @@ async function planRequest(
       logEpoch: registry.logEpoch,
       epochReset,
       header,
+      roundFailure,
       pushes,
       pull,
       subscriptions: [],
@@ -256,6 +262,7 @@ async function planRequest(
       logEpoch: registry.logEpoch,
       epochReset: true,
       header,
+      roundFailure,
       pushes: [],
       pull: undefined,
       subscriptions: [],
@@ -362,6 +369,7 @@ async function planRequest(
     logEpoch: registry.logEpoch,
     epochReset: false,
     header,
+    roundFailure,
     pushes,
     pull,
     subscriptions,
@@ -709,14 +717,21 @@ async function* streamResponse(
         : [...(previous?.subscriptions ?? [])];
     const cursor =
       cursors.length > 0 ? Math.min(...cursors) : (previous?.cursor ?? -1);
-    await ctx.storage.putClientRecord(ctx.partition, {
-      clientId: plan.header.clientId,
-      actorId: ctx.actorId,
-      wireVersion: plan.wireVersion,
-      cursor,
-      updatedAtMs: clockOf(ctx)(),
-      subscriptions,
-    });
+    await ctx.storage.putClientRecord(
+      ctx.partition,
+      {
+        clientId: plan.header.clientId,
+        actorId: ctx.actorId,
+        wireVersion: plan.wireVersion,
+        cursor,
+        updatedAtMs: clockOf(ctx)(),
+        subscriptions,
+      },
+      // §4.5: a round that carried a `ROUND_FAILURE` report completes without
+      // clearing the reported code and streak; the next request without the
+      // frame clears them as a plain completed round does.
+      plan.roundFailure !== undefined ? { keepRoundOutcome: true } : undefined,
+    );
     if (
       ctx.realtime?.notifySubscriptions !== undefined &&
       JSON.stringify(
@@ -831,6 +846,20 @@ async function recordRoundFailure(
   ctx: SyncRequestContext,
   clientId: string | undefined,
   error: unknown,
+): Promise<void> {
+  await recordRoundFailureCode(
+    ctx,
+    clientId,
+    error instanceof SyncError ? error.code : 'sync.internal_error',
+  );
+}
+
+/** As `recordRoundFailure`, for a code that is not a thrown catalog error
+ * (a `ROUND_FAILURE` report, §1.5). */
+async function recordRoundFailureCode(
+  ctx: SyncRequestContext,
+  clientId: string | undefined,
+  code: string,
 ): Promise<void> {
   if (clientId === undefined) return;
   try {
@@ -838,7 +867,7 @@ async function recordRoundFailure(
       ctx.partition,
       clientId,
       ctx.actorId,
-      error instanceof SyncError ? error.code : 'sync.internal_error',
+      code,
       clockOf(ctx)(),
     );
   } catch (failure) {
@@ -917,6 +946,16 @@ async function createStreamCore(
   );
   const served = selected ?? schema;
   const plan = await planRequest(request, ctx, served, registry);
+  // §1.5/§4.5: record the reported round failure on the existing record
+  // before the round runs (it never creates one, never touches another
+  // actor's record). The completion of this round leaves it in place.
+  if (plan.roundFailure !== undefined) {
+    await recordRoundFailureCode(
+      ctx,
+      plan.header.clientId,
+      plan.roundFailure.code,
+    );
+  }
   const report: RequestReport = { outcome: 'ok' };
   // RFC 0007 read-verify-refuse for the streamed read path: the generator
   // builds the whole response (its data reads) before yielding the first

package/src/postgres-storage.ts

@@ -105,6 +105,7 @@ import type {
   ClientCursorInfo,
   ClientPushResult,
   ClientRecord,
+  ClientRecordWriteOptions,
   ClientSubscription,
   CommitChangeSummary,
   CommitDetail,
@@ -2778,6 +2779,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
   async putClientRecord(
     partition: string,
     record: ClientRecord,
+    options?: ClientRecordWriteOptions,
   ): Promise<void> {
     await this.#exec.query(
       `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms)
@@ -2787,8 +2789,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
              cursor=EXCLUDED.cursor,
              subscriptions=EXCLUDED.subscriptions,
              updated_at_ms=EXCLUDED.updated_at_ms,
-             last_round_at_ms=EXCLUDED.last_round_at_ms,
-             last_error_code=NULL, consecutive_failures=0`,
+             last_round_at_ms=EXCLUDED.last_round_at_ms${
+               options?.keepRoundOutcome === true
+                 ? ''
+                 : ',\n             last_error_code=NULL, consecutive_failures=0'
+             }`,
       [
         partition,
         record.clientId,

package/src/sqlite-storage.ts

@@ -89,6 +89,7 @@ import type {
   ClientCursorInfo,
   ClientPushResult,
   ClientRecord,
+  ClientRecordWriteOptions,
   ClientSubscription,
   CommitChangeSummary,
   CommitDetail,
@@ -1892,10 +1893,24 @@ END`);
   async putClientRecord(
     partition: string,
     record: ClientRecord,
+    options?: ClientRecordWriteOptions,
   ): Promise<void> {
     this.db
       .query(
-        'INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)',
+        `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
+         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,
+           last_round_at_ms=excluded.last_round_at_ms${
+             options?.keepRoundOutcome === true
+               ? ''
+               : `,
+           last_error_code=NULL,
+           consecutive_failures=0`
+           }`,
       )
       .run(
         partition,

package/src/storage.ts

@@ -313,6 +313,16 @@ export interface ClientRecord {
   readonly consecutiveFailures?: number;
 }
 
+/** `putClientRecord` options. */
+export interface ClientRecordWriteOptions {
+  /**
+   * Leave the stored round outcome (`lastErrorCode`, `consecutiveFailures`)
+   * untouched. Set for a completed round that carried a `ROUND_FAILURE` report
+   * (§1.5, §4.5). `lastRoundAtMs` still moves to this round's completion.
+   */
+  readonly keepRoundOutcome?: boolean;
+}
+
 /** The round-state fields of a stored `sync_clients` row. */
 export function clientRoundState(
   lastRoundAtMs: number | null,
@@ -941,9 +951,15 @@ export interface ServerStorage {
   ): 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.
+   * stored last round is a success at `updatedAtMs` with no failures — unless
+   * `keepRoundOutcome` is set, which leaves the reported code and streak in
+   * place (the round carried a `ROUND_FAILURE` report, §1.5/§4.5).
    */
-  putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+  putClientRecord(
+    partition: string,
+    record: ClientRecord,
+    options?: ClientRecordWriteOptions,
+  ): Promise<void>;
   /**
    * Record a failed round on an existing record: set `lastRoundAtMs` and
    * `lastErrorCode`, and increment `consecutiveFailures`. Requires a matching