@syncular/server 0.15.47 → 0.16.1

package/dist/d1-storage.js

@@ -1,4 +1,6 @@
 var _a;
+import { validateCommitPruneQuery } from './prune.js';
+import { StorageQueryError } from './storage-errors.js';
 /**
  * Cloudflare D1 server storage for Workers deployments.
  *
@@ -479,6 +481,12 @@ export class D1ServerStorage {
         for (const statement of sqliteDdlStatements()) {
             await this.#db.exec(`${statement.replace(/\s+/g, ' ')};`);
         }
+        const { results } = await this.#db
+            .prepare('PRAGMA table_info("sync_clients")')
+            .all();
+        if (!results.some((column) => column.name === 'wire_version')) {
+            await this.#db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1;');
+        }
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -563,6 +571,68 @@ export class D1ServerStorage {
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
     }
+    async touchPartition(partition, authenticatedAtMs, initialLogEpoch) {
+        if (initialLogEpoch.length === 0) {
+            throw new Error('initial log epoch must be non-empty');
+        }
+        await this.#db
+            .prepare(`INSERT INTO sync_partition_registry(
+           partition, log_epoch, last_authenticated_at_ms
+         ) VALUES (?,?,?)
+         ON CONFLICT(partition) DO UPDATE SET
+           last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
+            .bind(partition, initialLogEpoch, authenticatedAtMs)
+            .run();
+        const row = await this.#db
+            .prepare(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
+           FROM sync_partition_registry WHERE partition=?`)
+            .bind(partition)
+            .first();
+        if (row === null)
+            throw new Error('partition registry write did not persist');
+        return {
+            partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required === 1,
+            lastAuthenticatedAtMs: row.last_authenticated_at_ms,
+        };
+    }
+    async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
+        if (logEpoch.length === 0)
+            throw new Error('log epoch must be non-empty');
+        await this.#db.batch([
+            this.#db
+                .prepare(`INSERT INTO sync_partition_registry(
+             partition, log_epoch, epoch_required, last_authenticated_at_ms
+           ) VALUES (?,?,1,?)
+           ON CONFLICT(partition) DO UPDATE SET
+             log_epoch=excluded.log_epoch,
+             epoch_required=1,
+             last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
+                .bind(partition, logEpoch, authenticatedAtMs),
+            this.#db
+                .prepare('DELETE FROM sync_clients WHERE partition=?')
+                .bind(partition),
+        ]);
+        return {
+            partition,
+            logEpoch,
+            epochRequired: true,
+            lastAuthenticatedAtMs: authenticatedAtMs,
+        };
+    }
+    async listPartitionRegistry() {
+        const { results } = await this.#db
+            .prepare(`SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
+           FROM sync_partition_registry ORDER BY partition`)
+            .all();
+        return results.map((row) => ({
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required === 1,
+            lastAuthenticatedAtMs: row.last_authenticated_at_ms,
+        }));
+    }
     /** Keyset-paged migration rewrite (see the sqlite storage's counterpart). */
     async #rewriteRows(table, oldLayout) {
         const select = selectRowsForRewriteSql(table, 'sqlite');
@@ -608,7 +678,7 @@ export class D1ServerStorage {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
-        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
         const results = await this.#db.batch([
             this.#db.prepare(prepared.sql).bind(...prepared.params),
             this.#db
@@ -639,6 +709,13 @@ export class D1ServerStorage {
             maxCommitSeq,
         };
     }
+    async getPartitionLogEpoch(partition) {
+        const row = await this.#db
+            .prepare('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .bind(partition)
+            .first();
+        return row?.log_epoch;
+    }
     async getHorizonSeq(partition) {
         const row = await this.#db
             .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -648,27 +725,55 @@ export class D1ServerStorage {
     }
     async setHorizonSeq(partition, seq) {
         await this.#db
-            .prepare('INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq')
+            .prepare('INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)')
             .bind(partition, seq)
             .run();
     }
-    async pruneCommitsThrough(partition, seq) {
-        const before = await this.#db
-            .prepare('SELECT count(*) AS n FROM sync_commits WHERE partition=? AND commit_seq<=?')
-            .bind(partition, seq)
-            .first();
-        await this.#db.batch([
+    async pruneCommitsThrough(partition, query) {
+        validateCommitPruneQuery(query);
+        if (!this.#pushApplySerialized)
+            throw new Error('D1 pruning requires externally serialized partition writes');
+        const epochGuard = 'EXISTS (SELECT 1 FROM sync_partition_registry WHERE partition=? AND log_epoch=?)';
+        const horizon = '(SELECT horizon_seq FROM sync_partitions WHERE partition=?)';
+        const results = await this.#db.batch([
             this.#db
-                .prepare('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`SELECT log_epoch, coalesce(${horizon},0) AS previous_horizon_seq FROM sync_partition_registry WHERE partition=?`)
+                .bind(partition, partition),
             this.#db
-                .prepare('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`INSERT INTO sync_partitions(partition,horizon_seq) SELECT ?,? WHERE ${epochGuard}
+        ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
+                .bind(partition, query.throughSeq, partition, query.logEpoch),
             this.#db
-                .prepare('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`)
+                .bind(partition, partition, partition),
+            ...['sync_commits', 'sync_changes', 'sync_change_scopes'].map((table) => this.#db
+                .prepare(`DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`)
+                .bind(partition, partition, partition, query.logEpoch)),
         ]);
-        return before?.n ?? 0;
+        const [before, after] = [results[0], results[2]].map((result) => {
+            if (typeof result !== 'object' ||
+                result === null ||
+                !('results' in result) ||
+                !Array.isArray(result.results)) {
+                throw new Error('D1 pruning returned an invalid batch result');
+            }
+            const row = result.results[0];
+            return typeof row === 'object' && row !== null
+                ? row
+                : undefined;
+        });
+        if (before?.log_epoch !== query.logEpoch)
+            throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
+        if (typeof before.previous_horizon_seq !== 'number' ||
+            typeof after?.horizon_seq !== 'number' ||
+            typeof after.removed_commits !== 'number') {
+            throw new Error('D1 pruning returned invalid horizon metadata');
+        }
+        return {
+            previousHorizonSeq: before.previous_horizon_seq,
+            horizonSeq: after.horizon_seq,
+            removedCommits: after.removed_commits,
+        };
     }
     async getCommitSeqBefore(partition, createdBeforeMs) {
         const row = await this.#db
@@ -912,7 +1017,7 @@ export class D1ServerStorage {
     }
     async getClientRecord(partition, clientId) {
         const record = await this.#db
-            .prepare('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')
+            .prepare('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')
             .bind(partition, clientId)
             .first();
         if (record === null)
@@ -920,6 +1025,7 @@ export class D1ServerStorage {
         return {
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: record.wire_version,
             cursor: record.cursor,
             updatedAtMs: record.updated_at_ms,
             subscriptions: JSON.parse(record.subscriptions),
@@ -927,10 +1033,17 @@ export class D1ServerStorage {
     }
     async putClientRecord(partition, record) {
         await this.#db
-            .prepare('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?)')
-            .bind(partition, record.clientId, record.actorId, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs)
+            .prepare('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)')
+            .bind(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs)
             .run();
     }
+    async getActiveClientCursorFloor(partition, cutoffMs) {
+        const row = await this.#db
+            .prepare('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?')
+            .bind(partition, cutoffMs)
+            .first();
+        return row.cursor;
+    }
     async listClientCursors(partition) {
         const { results } = await this.#db
             .prepare('SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?')
@@ -976,12 +1089,13 @@ export class D1ServerStorage {
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const { results } = await this.#db
-            .prepare('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC')
+            .prepare('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC')
             .bind(partition)
             .all();
         return results.map((record) => ({
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: record.wire_version,
             cursor: record.cursor,
             updatedAtMs: record.updated_at_ms,
             subscriptions: JSON.parse(record.subscriptions),
@@ -1065,12 +1179,6 @@ export class D1ServerStorage {
         };
     }
     async listPartitions() {
-        // Union: the registry row appears on first commit, the client row on
-        // first pull — a partition with only one of the two still shows up.
-        const { results } = await this.#db
-            .prepare(`SELECT partition FROM sync_partitions
-         UNION SELECT partition FROM sync_clients ORDER BY partition`)
-            .all();
-        return results.map((r) => r.partition);
+        return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }
 }

package/dist/errors.js

@@ -191,6 +191,12 @@ export const ERROR_CATALOG = {
         recommendedAction: 'upgradeClient',
         httpStatus: 400,
     },
+    'sync.client_wire_unsupported': {
+        category: 'schema-mismatch',
+        retryable: false,
+        recommendedAction: 'upgradeClient',
+        httpStatus: 400,
+    },
     'sync.websocket_connection_limit': {
         category: 'rate-limited',
         retryable: true,

package/dist/events.d.ts

@@ -28,10 +28,11 @@ export interface RequestHandledEvent {
     /**
      * `ok` — response streamed to END;
      * `schema_floor` — §2.4 required-schema answer;
+     * `reset` — §2.1 log-epoch reset answer;
      * `rejected` — request validation failed before any bytes (§1.7);
      * `error` — in-band ERROR frame (§1.6) or a thrown host failure.
      */
-    readonly outcome: 'ok' | 'schema_floor' | 'rejected' | 'error';
+    readonly outcome: 'ok' | 'schema_floor' | 'reset' | 'rejected' | 'error';
     /** §10.2 code for `rejected`/`error`; `"internal"` for non-SyncErrors. */
     readonly errorCode?: string;
     readonly pushCommits: number;

package/dist/frame-bytes.d.ts

@@ -10,11 +10,11 @@
  */
 import { type ResponseFrame } from '@syncular/core';
 /** The 8-byte SSP2 response envelope header (§1.2). */
-export declare const RESPONSE_ENVELOPE_HEADER: Uint8Array;
+export declare function responseEnvelopeHeader(wireVersion: number): Uint8Array;
 /** The terminating END frame (§1.2 rule 1). */
 export declare const END_FRAME_BYTES: Uint8Array;
 /**
  * Encode one response frame (5-byte frame header + payload) using the
  * reference codec.
  */
-export declare function encodeResponseFrame(frame: ResponseFrame): Uint8Array;
+export declare function encodeResponseFrame(frame: ResponseFrame, wireVersion?: number): Uint8Array;

package/dist/frame-bytes.js

@@ -9,7 +9,13 @@
  * bytes; the reference codec remains the single source of wire bytes.
  */
 import { encodeMessage, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
-const STUB_HEADER = { type: 'RESP_HEADER' };
+const stubHeader = (wireVersion) => wireVersion >= 2
+    ? {
+        type: 'RESP_HEADER',
+        logEpoch: 'frame-probe',
+        resetRequired: false,
+    }
+    : { type: 'RESP_HEADER' };
 const STUB_SUB_START = {
     type: 'SUB_START',
     id: '',
@@ -20,25 +26,32 @@ const STUB_SUB_START = {
 };
 const STUB_SUB_END = { type: 'SUB_END', nextCursor: 0 };
 const probe = encodeMessage({
-    wireVersion: PROTOCOL_WIRE_VERSION,
+    wireVersion: 1,
     msgKind: 'response',
-    frames: [STUB_HEADER],
+    frames: [stubHeader(1)],
 });
 /** The 8-byte SSP2 response envelope header (§1.2). */
-export const RESPONSE_ENVELOPE_HEADER = probe.slice(0, 8);
+export function responseEnvelopeHeader(wireVersion) {
+    const encoded = encodeMessage({
+        wireVersion,
+        msgKind: 'response',
+        frames: [stubHeader(wireVersion)],
+    });
+    return encoded.slice(0, 8);
+}
 /** The terminating END frame (§1.2 rule 1). */
 export const END_FRAME_BYTES = probe.slice(probe.length - 5);
-function wrapperFor(frame) {
+function wrapperFor(frame, wireVersion) {
     switch (frame.type) {
         case 'RESP_HEADER':
             return { frames: [frame], index: 0 };
         case 'LEASE':
             // §7.3.2: LEASE rides immediately after RESP_HEADER.
-            return { frames: [STUB_HEADER, frame], index: 1 };
+            return { frames: [stubHeader(wireVersion), frame], index: 1 };
         case 'PUSH_RESULT':
         case 'ERROR':
         case 'UNKNOWN':
-            return { frames: [STUB_HEADER, frame], index: 1 };
+            return { frames: [stubHeader(wireVersion), frame], index: 1 };
         case 'PUSH_RESULT_DETAILS': {
             const result = {
                 type: 'PUSH_RESULT',
@@ -52,17 +65,23 @@ function wrapperFor(frame) {
                     retryable: false,
                 })),
             };
-            return { frames: [STUB_HEADER, result, frame], index: 2 };
+            return { frames: [stubHeader(wireVersion), result, frame], index: 2 };
         }
         case 'SUB_START':
-            return { frames: [STUB_HEADER, frame, STUB_SUB_END], index: 1 };
+            return {
+                frames: [stubHeader(wireVersion), frame, STUB_SUB_END],
+                index: 1,
+            };
         case 'SUB_END':
-            return { frames: [STUB_HEADER, STUB_SUB_START, frame], index: 2 };
+            return {
+                frames: [stubHeader(wireVersion), STUB_SUB_START, frame],
+                index: 2,
+            };
         case 'COMMIT':
         case 'SEGMENT_REF':
         case 'SEGMENT_INLINE':
             return {
-                frames: [STUB_HEADER, STUB_SUB_START, frame, STUB_SUB_END],
+                frames: [stubHeader(wireVersion), STUB_SUB_START, frame, STUB_SUB_END],
                 index: 2,
             };
     }
@@ -71,10 +90,10 @@ function wrapperFor(frame) {
  * Encode one response frame (5-byte frame header + payload) using the
  * reference codec.
  */
-export function encodeResponseFrame(frame) {
-    const { frames, index } = wrapperFor(frame);
+export function encodeResponseFrame(frame, wireVersion = PROTOCOL_WIRE_VERSION) {
+    const { frames, index } = wrapperFor(frame, wireVersion);
     const encoded = encodeMessage({
-        wireVersion: PROTOCOL_WIRE_VERSION,
+        wireVersion,
         msgKind: 'response',
         frames,
     });

package/dist/handler.js

@@ -10,10 +10,10 @@
  * frame (§1.6).
  */
 import { DecodeError, decodeMessage, } from '@syncular/core';
-import { clockOf, limitsOf, REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, } from './context.js';
+import { clockOf, limitsOf, REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { SyncError, syncError } from './errors.js';
 import { emitEvent, } from './events.js';
-import { END_FRAME_BYTES, encodeResponseFrame, RESPONSE_ENVELOPE_HEADER, } from './frame-bytes.js';
+import { END_FRAME_BYTES, encodeResponseFrame, responseEnvelopeHeader, } from './frame-bytes.js';
 import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, subscriptionSection, } from './pull.js';
 import { processPushCommitWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
@@ -96,7 +96,7 @@ async function resolveOnce(ctx, clientId, schema) {
     }
     return { resolved: { ok: true, allowed }, leaseToEmit };
 }
-async function planRequest(request, ctx, schema) {
+async function planRequest(request, ctx, schema, registry) {
     const header = request.frames[0];
     if (header === undefined || header.type !== 'REQ_HEADER') {
         throw syncError('sync.invalid_request', 'missing REQ_HEADER');
@@ -112,10 +112,22 @@ async function planRequest(request, ctx, schema) {
         else if (frame.type === 'SUBSCRIPTION')
             subFrames.push(frame);
     }
+    if (request.wireVersion === 1 && registry.epochRequired) {
+        throw syncError('sync.client_wire_unsupported', 'this partition requires a client that validates log epochs (§2.1)');
+    }
+    if (request.wireVersion >= 2 &&
+        header.logEpoch === undefined &&
+        pushes.length > 0) {
+        throw syncError('sync.invalid_request', 'epoch acquisition requests must not carry push commits (§2.1)');
+    }
+    const epochReset = request.wireVersion >= 2 && header.logEpoch !== registry.logEpoch;
     if (header.schemaVersion !== schema.version) {
         // §2.4: no degraded encoding — answer with the schema floor (§1.6).
         // No lease is issued on a floor round (§7.3.3).
         return {
+            wireVersion: request.wireVersion,
+            logEpoch: registry.logEpoch,
+            epochReset,
             header,
             pushes,
             pull,
@@ -125,6 +137,20 @@ async function planRequest(request, ctx, schema) {
             leaseToEmit: undefined,
         };
     }
+    if (epochReset) {
+        return {
+            wireVersion: request.wireVersion,
+            logEpoch: registry.logEpoch,
+            epochReset: true,
+            header,
+            pushes: [],
+            pull: undefined,
+            subscriptions: [],
+            resolved: { ok: false },
+            schemaFloor: false,
+            leaseToEmit: undefined,
+        };
+    }
     if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
         throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
     }
@@ -181,6 +207,9 @@ async function planRequest(request, ctx, schema) {
         return { frame, table, status: 'revoked', effective: {} };
     });
     return {
+        wireVersion: request.wireVersion,
+        logEpoch: registry.logEpoch,
+        epochReset: false,
         header,
         pushes,
         pull,
@@ -256,7 +285,7 @@ function emitPushEvent(events, ctx, clientId, push, processed) {
 }
 async function* streamResponse(plan, ctx, schema, report) {
     const events = ctx.events;
-    yield RESPONSE_ENVELOPE_HEADER;
+    yield responseEnvelopeHeader(plan.wireVersion);
     if (plan.schemaFloor) {
         if (report !== undefined)
             report.outcome = 'schema_floor';
@@ -264,21 +293,33 @@ async function* streamResponse(plan, ctx, schema, report) {
             type: 'RESP_HEADER',
             requiredSchemaVersion: schema.version,
             latestSchemaVersion: schema.version,
-        });
+            ...(plan.wireVersion >= 2
+                ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
+                : {}),
+        }, plan.wireVersion);
         yield END_FRAME_BYTES;
         return;
     }
     yield encodeResponseFrame({
         type: 'RESP_HEADER',
         latestSchemaVersion: schema.version,
-    });
+        ...(plan.wireVersion >= 2
+            ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
+            : {}),
+    }, plan.wireVersion);
+    if (plan.epochReset) {
+        if (report !== undefined)
+            report.outcome = 'reset';
+        yield END_FRAME_BYTES;
+        return;
+    }
     // §7.3.2: the LEASE frame rides immediately after RESP_HEADER.
     if (plan.leaseToEmit !== undefined) {
         yield encodeResponseFrame({
             type: 'LEASE',
             leaseId: plan.leaseToEmit.leaseId,
             expiresAtMs: plan.leaseToEmit.expiresAtMs,
-        });
+        }, plan.wireVersion);
         if (events !== undefined) {
             emitEvent(events, {
                 type: 'lease.issued',
@@ -299,10 +340,11 @@ async function* streamResponse(plan, ctx, schema, report) {
             if (events !== undefined) {
                 emitPushEvent(events, ctx, plan.header.clientId, push, processed);
             }
-            yield encodeResponseFrame(frame);
+            yield encodeResponseFrame(frame, plan.wireVersion);
             const details = pushResultDetailsFrame(frame);
-            if (details !== undefined)
-                yield encodeResponseFrame(details);
+            if (details !== undefined) {
+                yield encodeResponseFrame(details, plan.wireVersion);
+            }
         }
         // Pull half (§4): subscriptions echoed in request order.
         const cursors = [];
@@ -313,7 +355,7 @@ async function* streamResponse(plan, ctx, schema, report) {
             const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
             for (const subscription of plan.subscriptions) {
                 const trace = summaries !== undefined ? { segments: [] } : undefined;
-                const section = subscriptionSection(ctx, schema, limits, subscription, maxSeq, horizonSeq, trace);
+                const section = subscriptionSection(ctx, schema, limits, subscription, maxSeq, horizonSeq, trace, plan.logEpoch);
                 let status = 'active';
                 let bootstrap = false;
                 let commits = 0;
@@ -331,7 +373,7 @@ async function* streamResponse(plan, ctx, schema, report) {
                             changes += frame.changes.length;
                         }
                     }
-                    yield encodeResponseFrame(frame);
+                    yield encodeResponseFrame(frame, plan.wireVersion);
                     step = await section.next();
                 }
                 if (step.value.active)
@@ -379,6 +421,7 @@ async function* streamResponse(plan, ctx, schema, report) {
         await ctx.storage.putClientRecord(ctx.partition, {
             clientId: plan.header.clientId,
             actorId: ctx.actorId,
+            wireVersion: plan.wireVersion,
             cursor,
             updatedAtMs: clockOf(ctx)(),
             subscriptions,
@@ -399,7 +442,7 @@ async function* streamResponse(plan, ctx, schema, report) {
                 retryable: error.retryable,
                 recommendedAction: error.recommendedAction,
                 ...(error.details !== undefined ? { details: error.details } : {}),
-            });
+            }, plan.wireVersion);
             yield END_FRAME_BYTES;
             return;
         }
@@ -461,7 +504,8 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
     // Relational row tables: create/
     // migrate on first contact; memoized per storage instance thereafter.
     await ctx.storage.ensureSchema(schema);
-    const plan = await planRequest(request, ctx, schema);
+    const registry = await touchAuthenticatedPartition(ctx);
+    const plan = await planRequest(request, ctx, schema, registry);
     if (events === undefined)
         return streamResponse(plan, ctx, schema);
     const report = { outcome: 'ok' };

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export * from './push.js';
 export * from './readiness.js';
 export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, type PlannedReaction, type PruneReactionsOptions, type ReactionHandler, type ReactionHandlerInput, type ReactionHandlers, type ReactionPlan, type ReactionPlanner, type ReactionPlannerInput, type ReactionPruneResult, type ReactionRetentionPolicy, type ReactionRunnerOptions, type ReactionRunResult, type ReactionTypeMap, } from './reactions.js';
 export * from './realtime.js';
+export * from './restore.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';
 export * from './s3-segment-store.js';

package/dist/index.js

@@ -36,6 +36,7 @@ export * from './push.js';
 export * from './readiness.js';
 export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, } from './reactions.js';
 export * from './realtime.js';
+export * from './restore.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';
 export * from './s3-segment-store.js';

package/dist/operations.d.ts

@@ -1,3 +1,4 @@
+import { type AuthoritativeRelationPlan } from './authoritative-query.js';
 import { type RemoteOperationResponse, type RowValue } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
 import type { AuthoritativeQueryValue } from './storage.js';
@@ -20,6 +21,7 @@ export interface AuthoritativeQueryDescriptor<Params = undefined> {
     readonly hasParams: boolean;
     readonly sql: string;
     readonly tables: readonly string[];
+    readonly relationPlans: readonly AuthoritativeRelationPlan[];
     readonly resultColumns: readonly {
         readonly name: string;
         readonly type: 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';

package/dist/operations.js

@@ -1,5 +1,6 @@
+import { validateAuthoritativeRelationPlan, } from './authoritative-query.js';
 import { decodeRow, decodeRemoteOperationRequest, encodeRow, encodeRemoteOperationResponse, } from '@syncular/core';
-import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE } from './context.js';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
@@ -97,13 +98,19 @@ function normalizeQueryRows(rows, columns) {
 }
 /** Register one generated named query as an authoritative remote operation. */
 export function registerRemoteQuery(descriptor, options) {
-    if (descriptor.id.length === 0 ||
+    if (!Array.isArray(descriptor.relationPlans) ||
+        !descriptor.relationPlans.some((plan) => plan.sql === descriptor.sql) ||
+        descriptor.relationPlans.some((plan) => !Array.isArray(plan.relations)) ||
+        descriptor.id.length === 0 ||
         new Set(descriptor.tables).size !== descriptor.tables.length ||
         !Array.isArray(descriptor.resultColumns) ||
         descriptor.resultColumns.length === 0 ||
         new Set(descriptor.resultColumns.map((column) => column.name)).size !==
             descriptor.resultColumns.length) {
-        throw new Error('remote query requires a non-empty id and unique tables and result columns');
+        throw new Error('remote query requires generated relation plans, a non-empty id, and unique tables and result columns; regenerate queries');
+    }
+    for (const plan of descriptor.relationPlans) {
+        validateAuthoritativeRelationPlan(plan, descriptor.tables);
     }
     if (!Number.isSafeInteger(options.maxRows) ||
         options.maxRows < 1 ||
@@ -173,12 +180,24 @@ export function registerRemoteQuery(descriptor, options) {
             if (ctx.storage.queryAuthoritative === undefined) {
                 throw syncError('operation.storage_unsupported', 'configured storage does not implement authoritative queries');
             }
-            await ctx.storage.ensureSchema(schema);
             const selectedSql = descriptor.sqlFor?.(params) ?? descriptor.sql;
+            const plan = descriptor.relationPlans.find((candidate) => candidate.sql === selectedSql);
+            if (plan === undefined) {
+                throw syncError('operation.invalid_request', 'selected SQL has no generated relation plan; regenerate queries');
+            }
+            await ctx.storage.ensureSchema(schema);
+            const prefix = 'SELECT * FROM (';
             let result;
             try {
                 result = await ctx.storage.queryAuthoritative(ctx.partition, {
-                    sql: `SELECT * FROM (${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+                    plan: {
+                        sql: `${prefix}${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+                        relations: plan.relations.map((relation) => ({
+                            ...relation,
+                            start: relation.start + prefix.length,
+                            end: relation.end + prefix.length,
+                        })),
+                    },
                     params: [...descriptor.bind(params), options.maxRows + 1],
                     tables: descriptor.tables,
                 });
@@ -362,6 +381,7 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
         return encodeRemoteOperationError(error, 'operation.invalid_request');
     }
     try {
+        await touchAuthenticatedPartition(ctx);
         if (request.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
             throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
         }