@syncular/server 0.15.46 → 0.15.48

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';
@@ -41,9 +42,10 @@ export * from './seed.js';
 export * from './segment-download.js';
 export * from './segment-store.js';
 export * from './signed-url.js';
-export * from './sqlite-blob-store.js';
 export * from './sqlite-dialect.js';
-export * from './sqlite-image.js';
+export * from './sqlite-driver.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, } from './sqlite-image.js';
+export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';
 export * from './sqlite-storage.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';
@@ -45,13 +46,10 @@ export * from './seed.js';
 export * from './segment-download.js';
 export * from './segment-store.js';
 export * from './signed-url.js';
-// Bun-specific storages (top-level `bun:sqlite`): re-exported for Bun/Node
-// hosts. Workers/edge builds tree-shake them (and their `bun:sqlite` import)
-// away — the runtime-neutral core closure is enforced by
-// `test/runtime-neutrality.test.ts`.
-export * from './sqlite-blob-store.js';
 export * from './sqlite-dialect.js';
-export * from './sqlite-image.js';
+export * from './sqlite-driver.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, } from './sqlite-image.js';
+export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';
 export * from './sqlite-storage.js';

package/dist/operations.js

@@ -1,5 +1,5 @@
 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';
@@ -362,6 +362,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)');
         }

package/dist/postgres-storage.d.ts

@@ -1,6 +1,6 @@
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -23,7 +23,7 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *     set, §5.9.5) as an index range, never a scan. `postgres-explain
  *     .test.ts` asserts an `Index` node here too.
  */
-export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
+export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
 export declare class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);
@@ -32,6 +32,9 @@ export declare class PostgresServerStorage implements ServerStorage {
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
     ensureSchema(schema: CompiledSchema): Promise<void>;
+    touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
+    rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
+    listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
     /**
      * Open a real Postgres transaction. The push handler drives the returned
      * `StorageTransaction` imperatively (getRow/upsert/…/commit), but the

package/dist/postgres-storage.js

@@ -33,6 +33,12 @@ CREATE TABLE IF NOT EXISTS sync_partitions(
   max_commit_seq BIGINT NOT NULL DEFAULT 0,
   horizon_seq BIGINT NOT NULL DEFAULT 0
 );
+CREATE TABLE IF NOT EXISTS sync_partition_registry(
+  partition TEXT PRIMARY KEY,
+  log_epoch TEXT NOT NULL,
+  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,
+  last_authenticated_at_ms BIGINT NOT NULL
+);
 CREATE TABLE IF NOT EXISTS sync_row_scopes(
   partition TEXT NOT NULL, tbl TEXT NOT NULL,
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
@@ -86,10 +92,13 @@ CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
   ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
+  wire_version INTEGER NOT NULL DEFAULT 1,
   cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,
   updated_at_ms BIGINT NOT NULL,
   PRIMARY KEY(partition, client_id)
 );
+ALTER TABLE sync_clients
+  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;
 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,
@@ -628,6 +637,58 @@ export class PostgresServerStorage {
         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');
+        }
+        const { rows } = await this.#exec.query(`INSERT INTO sync_partition_registry(
+         partition, log_epoch, last_authenticated_at_ms
+       ) VALUES ($1,$2,$3)
+       ON CONFLICT(partition) DO UPDATE SET
+         last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
+       RETURNING log_epoch, epoch_required, last_authenticated_at_ms`, [partition, initialLogEpoch, authenticatedAtMs]);
+        const row = rows[0];
+        if (row === undefined)
+            throw new Error('partition registry write did not persist');
+        return {
+            partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required,
+            lastAuthenticatedAtMs: asNumber(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.#exec.transaction(async (client) => {
+            await client.query(`INSERT INTO sync_partition_registry(
+           partition, log_epoch, epoch_required, last_authenticated_at_ms
+         ) VALUES ($1,$2,TRUE,$3)
+         ON CONFLICT(partition) DO UPDATE SET
+           log_epoch=EXCLUDED.log_epoch,
+           epoch_required=TRUE,
+           last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms`, [partition, logEpoch, authenticatedAtMs]);
+            await client.query('DELETE FROM sync_clients WHERE partition=$1', [
+                partition,
+            ]);
+        });
+        return {
+            partition,
+            logEpoch,
+            epochRequired: true,
+            lastAuthenticatedAtMs: authenticatedAtMs,
+        };
+    }
+    async listPartitionRegistry() {
+        const { rows } = await this.#exec.query(`SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
+         FROM sync_partition_registry ORDER BY partition`, []);
+        return rows.map((row) => ({
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required,
+            lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
+        }));
+    }
     /**
      * Open a real Postgres transaction. The push handler drives the returned
      * `StorageTransaction` imperatively (getRow/upsert/…/commit), but the
@@ -978,28 +1039,31 @@ export class PostgresServerStorage {
         return scanRowsByIndexOn(this.#exec, this.table(query.table), partition, query);
     }
     async getClientRecord(partition, clientId) {
-        const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2', [partition, clientId]);
+        const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2', [partition, clientId]);
         const record = rows[0];
         if (record === undefined)
             return undefined;
         return {
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: asNumber(record.wire_version),
             cursor: asNumber(record.cursor),
             updatedAtMs: asNumber(record.updated_at_ms),
             subscriptions: asJson(record.subscriptions),
         };
     }
     async putClientRecord(partition, record) {
-        await this.#exec.query(`INSERT INTO sync_clients(partition, client_id, actor_id, cursor, subscriptions, updated_at_ms)
-       VALUES ($1,$2,$3,$4,$5,$6)
+        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)
        ON CONFLICT (partition, client_id) DO UPDATE
-         SET actor_id=EXCLUDED.actor_id, cursor=EXCLUDED.cursor,
+         SET actor_id=EXCLUDED.actor_id, wire_version=EXCLUDED.wire_version,
+             cursor=EXCLUDED.cursor,
              subscriptions=EXCLUDED.subscriptions,
              updated_at_ms=EXCLUDED.updated_at_ms`, [
             partition,
             record.clientId,
             record.actorId,
+            record.wireVersion,
             record.cursor,
             JSON.stringify(record.subscriptions),
             record.updatedAtMs,
@@ -1040,10 +1104,11 @@ export class PostgresServerStorage {
     }
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
-        const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);
+        const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);
         return rows.map((r) => ({
             clientId: r.client_id,
             actorId: r.actor_id,
+            wireVersion: asNumber(r.wire_version),
             cursor: asNumber(r.cursor),
             updatedAtMs: asNumber(r.updated_at_ms),
             subscriptions: (typeof r.subscriptions === 'string'
@@ -1114,10 +1179,6 @@ export class PostgresServerStorage {
         };
     }
     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 { rows } = await this.#exec.query(`SELECT partition FROM sync_partitions
-       UNION SELECT partition FROM sync_clients ORDER BY partition`, []);
-        return rows.map((r) => r.partition);
+        return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }
 }

package/dist/pull.d.ts

@@ -41,4 +41,4 @@ export interface PullSectionTrace {
  * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
  * returning the cursor recorded for the retention watermark (§4.5).
  */
-export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace): AsyncGenerator<ResponseFrame, SubscriptionResult>;
+export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;

package/dist/pull.js

@@ -19,7 +19,7 @@ async function resolveImageBuilder(ctx) {
     if (cachedDefaultBuilder === undefined) {
         const hasBun = globalThis.Bun !== undefined;
         cachedDefaultBuilder = hasBun
-            ? (await import('./sqlite-image.js')).buildSqliteImage
+            ? (await import('./sqlite-bun.js')).buildSqliteImage
             : null;
     }
     return cachedDefaultBuilder ?? undefined;
@@ -134,11 +134,12 @@ function segmentRefFrame(record, extra) {
  * bootstrap-storm rule. Returns false when the table is not eligible
  * (the rows lane takes over).
  */
-async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace) {
+async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch) {
     const { storage, segments, partition } = ctx;
     const now = clockOf(ctx)();
     const existing = await segments.find({
         partition,
+        logEpoch,
         table: plan.table.name,
         schemaVersion: schema.version,
         mediaType: 'sqlite',
@@ -204,6 +205,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     });
     const record = await segments.put({
         partition,
+        logEpoch,
         table: plan.table.name,
         schemaVersion: schema.version,
         mediaType: 'sqlite',
@@ -223,7 +225,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
     return true;
 }
-async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace) {
+async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch) {
     const { storage, segments, partition } = ctx;
     const serverLimits = limitsOf(ctx);
     const digest = await scopeDigest(plan.effective);
@@ -237,7 +239,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
     if ((limits.accept & ACCEPT_SQLITE) !== 0 &&
         startRowCursor === null &&
         plan.table.encryptedColumnIndices.length === 0) {
-        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace);
+        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch);
         if (imaged)
             return { complete: true, rowCursor: null };
     }
@@ -281,6 +283,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
         else {
             const record = await segments.put({
                 partition,
+                logEpoch,
                 table: plan.table.name,
                 schemaVersion: schema.version,
                 mediaType: 'rows',
@@ -309,8 +312,11 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
  * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
  * returning the cursor recorded for the retention watermark (§4.5).
  */
-export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, horizonSeq, trace) {
+export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, horizonSeq, trace, logEpoch) {
     const sub = plan.frame;
+    if (logEpoch === undefined || logEpoch.length === 0) {
+        throw new Error('subscriptionSection requires a non-empty log epoch');
+    }
     if (plan.status === 'revoked') {
         yield {
             type: 'SUB_START',
@@ -355,7 +361,7 @@ export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, ho
             effectiveScopes: plan.effective,
             bootstrap: true,
         };
-        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace);
+        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace, logEpoch);
         if (outcome.complete) {
             yield { type: 'SUB_END', nextCursor: asOf };
         }

package/dist/realtime.d.ts

@@ -96,6 +96,9 @@ export declare class RealtimeSession {
     readonly partition: string;
     readonly actorId: string;
     readonly clientId: string;
+    readonly logEpoch: string;
+    /** Response/delta layout selected by the most recent socket round. */
+    wireVersion: number;
     /** Highest contiguously applied commitSeq acknowledged by the client. */
     cursor: number;
     /** Suppress deltas until the client catches up via pull + ack (§8.2). */
@@ -105,7 +108,7 @@ export declare class RealtimeSession {
     registrations: readonly Registration[];
     /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
     readonly openedAtMs: number;
-    constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, events: SyncularServerEvents | undefined);
+    constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, logEpoch: string, wireVersion: number, events: SyncularServerEvents | undefined);
     /** Feed an inbound text frame (client → server control message, §8.2
      * ack, §8.6.2 presence). */
     handleMessage(text: string): void;

package/dist/realtime.js

@@ -14,7 +14,7 @@
  * the `sync` wake-up (§8.3).
  */
 import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } 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 { emitEvent } from './events.js';
 import { createSyncResponseStream } from './handler.js';
@@ -120,6 +120,9 @@ export class RealtimeSession {
     partition;
     actorId;
     clientId;
+    logEpoch;
+    /** Response/delta layout selected by the most recent socket round. */
+    wireVersion;
     /** Highest contiguously applied commitSeq acknowledged by the client. */
     cursor;
     /** Suppress deltas until the client catches up via pull + ack (§8.2). */
@@ -144,11 +147,13 @@ export class RealtimeSession {
     /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
      * document coalesced while over the cap. */
     #presenceRate = new Map();
-    constructor(hub, options, registrations, cursor, latestSeq, clock, maxDeltaBytes, storage, events) {
+    constructor(hub, options, registrations, cursor, latestSeq, clock, maxDeltaBytes, storage, logEpoch, wireVersion, events) {
         this.sessionId = crypto.randomUUID();
         this.partition = options.partition;
         this.actorId = options.actorId;
         this.clientId = options.clientId;
+        this.logEpoch = logEpoch;
+        this.wireVersion = wireVersion;
         this.cursor = cursor;
         this.lastKnownSeq = latestSeq;
         this.wakePending = cursor < latestSeq;
@@ -376,6 +381,10 @@ export class RealtimeSession {
                 this.#activeRound = undefined;
         };
         try {
+            const requestedWireVersion = (requestBytes[4] ?? 0) | ((requestBytes[5] ?? 0) << 8);
+            if (requestedWireVersion === 1 || requestedWireVersion === 2) {
+                this.wireVersion = requestedWireVersion;
+            }
             let stream;
             try {
                 // §8.7: the round's clientId must match the connection's —
@@ -398,7 +407,7 @@ export class RealtimeSession {
                         ? error
                         : syncError(error.code, error.message);
                     finishRound(); // END is in this one chunk
-                    await this.#sendRoundChunk(errorResponseBytes(sync));
+                    await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
                     return;
                 }
                 throw error;
@@ -550,7 +559,14 @@ export class RealtimeSession {
             this.sendWake('catchup-required');
             return;
         }
-        const frames = [{ type: 'RESP_HEADER' }];
+        const frames = [
+            {
+                type: 'RESP_HEADER',
+                ...(this.wireVersion >= 2
+                    ? { logEpoch: this.logEpoch, resetRequired: false }
+                    : {}),
+            },
+        ];
         for (const section of sections) {
             frames.push({
                 type: 'SUB_START',
@@ -571,7 +587,7 @@ export class RealtimeSession {
             frames.push({ type: 'SUB_END', nextCursor: commit.commitSeq });
         }
         const bytes = encodeMessage({
-            wireVersion: PROTOCOL_WIRE_VERSION,
+            wireVersion: this.wireVersion,
             msgKind: 'response',
             frames,
         });
@@ -770,6 +786,11 @@ export class RealtimeHub {
     async connect(options) {
         const { storage } = this.#config;
         const clock = this.#config.clock ?? Date.now;
+        const registry = await touchAuthenticatedPartition({
+            ...this.#config,
+            partition: options.partition,
+            actorId: options.actorId,
+        });
         if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
             throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
         }
@@ -780,7 +801,7 @@ export class RealtimeHub {
         const registrations = await this.loadRegistrations(options.partition, options.actorId, options.clientId);
         const latestSeq = await storage.getMaxCommitSeq(options.partition);
         const cursor = record?.cursor ?? -1;
-        const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, this.#config.events);
+        const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, registry.logEpoch, record?.wireVersion ?? PROTOCOL_WIRE_VERSION, this.#config.events);
         this.#sessions.add(session);
         const helloResult = options.send(JSON.stringify({
             event: 'hello',
@@ -860,12 +881,15 @@ export function createRealtimeHub(config) {
 /** §8.7 failures: the socket has no HTTP status surface, so a
  * request-level failure becomes a minimal RESP_HEADER/ERROR/END
  * response message delivered as the round's response stream. */
-function errorResponseBytes(error) {
+function errorResponseBytes(error, wireVersion, logEpoch) {
     return encodeMessage({
-        wireVersion: PROTOCOL_WIRE_VERSION,
+        wireVersion,
         msgKind: 'response',
         frames: [
-            { type: 'RESP_HEADER' },
+            {
+                type: 'RESP_HEADER',
+                ...(wireVersion >= 2 ? { logEpoch, resetRequired: false } : {}),
+            },
             {
                 type: 'ERROR',
                 code: error.code,

package/dist/restore.d.ts

@@ -0,0 +1,13 @@
+import type { PartitionRegistryEntry, ServerStorage } from './storage.js';
+export interface RotatePartitionLogEpochOptions {
+    readonly storage: ServerStorage;
+    readonly partition: string;
+    readonly nowMs?: number;
+    /** Deterministic operator/test override. Defaults to a random UUID. */
+    readonly logEpoch?: string;
+}
+/**
+ * Fence clients from a prior authoritative database timeline after restore.
+ * Call while traffic and realtime delivery remain stopped (§2.1).
+ */
+export declare function rotatePartitionLogEpoch(options: RotatePartitionLogEpochOptions): Promise<PartitionRegistryEntry>;

package/dist/restore.js

@@ -0,0 +1,13 @@
+/**
+ * Fence clients from a prior authoritative database timeline after restore.
+ * Call while traffic and realtime delivery remain stopped (§2.1).
+ */
+export function rotatePartitionLogEpoch(options) {
+    if (options.partition.length === 0) {
+        throw new TypeError('partition must be non-empty');
+    }
+    const logEpoch = options.logEpoch ?? crypto.randomUUID();
+    if (logEpoch.length === 0)
+        throw new TypeError('logEpoch must be non-empty');
+    return options.storage.rotatePartitionLogEpoch(options.partition, logEpoch, options.nowMs ?? Date.now());
+}

package/dist/s3-segment-store.js

@@ -70,7 +70,13 @@ function parseRecordJson(json, source) {
         throw new Error(`S3SegmentStore: corrupt record in ${source}`);
     }
     const r = parsed;
-    const strings = ['segmentId', 'partition', 'table', 'scopeDigest'];
+    const strings = [
+        'segmentId',
+        'partition',
+        'logEpoch',
+        'table',
+        'scopeDigest',
+    ];
     const numbers = [
         'schemaVersion',
         'asOfCommitSeq',
@@ -99,6 +105,7 @@ function parseRecordJson(json, source) {
     return {
         segmentId: r.segmentId,
         partition: r.partition,
+        logEpoch: r.logEpoch,
         table: r.table,
         schemaVersion: r.schemaVersion,
         mediaType: r.mediaType,
@@ -136,6 +143,7 @@ export class S3SegmentStore {
     async #findKeyFor(key) {
         const canonical = JSON.stringify([
             key.partition,
+            key.logEpoch,
             key.table,
             key.schemaVersion,
             key.mediaType,
@@ -304,6 +312,7 @@ export class S3SegmentStore {
             return undefined;
         const record = parseRecordJson(await response.text(), 'reuse pointer');
         if (record.partition !== key.partition ||
+            record.logEpoch !== key.logEpoch ||
             record.table !== key.table ||
             record.schemaVersion !== key.schemaVersion ||
             record.mediaType !== key.mediaType ||

package/dist/seed.js

@@ -105,8 +105,42 @@ export async function seedMutations(config, target, mutations) {
             payload: encodeRow(table.columns, values),
         };
     });
+    const requestContext = {
+        ...config,
+        partition: target.partition,
+        actorId: target.actorId,
+    };
+    const acquisition = decodeMessage(await handleSyncRequest(encodeMessage({
+        wireVersion: PROTOCOL_WIRE_VERSION,
+        msgKind: 'request',
+        frames: [
+            {
+                type: 'REQ_HEADER',
+                clientId,
+                schemaVersion: config.schema.version,
+            },
+            {
+                type: 'PULL_HEADER',
+                limitCommits: 0,
+                limitSnapshotRows: 0,
+                maxSnapshotPages: 0,
+                accept: 0b0011,
+            },
+        ],
+    }), requestContext));
+    const acquisitionHeader = acquisition.frames[0];
+    if (acquisition.msgKind !== 'response' ||
+        acquisitionHeader?.type !== 'RESP_HEADER' ||
+        acquisitionHeader.logEpoch === undefined) {
+        throw new SyncError('sync.invalid_request', 'seedMutations: epoch acquisition returned an invalid response');
+    }
     const frames = [
-        { type: 'REQ_HEADER', clientId, schemaVersion: config.schema.version },
+        {
+            type: 'REQ_HEADER',
+            clientId,
+            schemaVersion: config.schema.version,
+            logEpoch: acquisitionHeader.logEpoch,
+        },
         { type: 'PUSH_COMMIT', clientCommitId, operations },
         // A pull that asks for nothing: the round exists for its push half.
         {
@@ -132,9 +166,7 @@ export async function seedMutations(config, target, mutations) {
         msgKind: 'request',
         frames,
     }), {
-        ...config,
-        partition: target.partition,
-        actorId: target.actorId,
+        ...requestContext,
         events: config.events === undefined
             ? capture
             : composeEvents(config.events, capture),

package/dist/segment-download.js

@@ -1,4 +1,4 @@
-import { clockOf, RESOLVER_OUTAGE } from './context.js';
+import { clockOf, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { SyncError, syncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { compileSchema } from './schema.js';
@@ -60,8 +60,11 @@ export async function handleSegmentDownload(ctx, request) {
     }
 }
 async function downloadSegment(ctx, request) {
+    const registry = await touchAuthenticatedPartition(ctx);
     const entry = await ctx.segments.get(request.segmentId);
-    if (entry === undefined || entry.record.partition !== ctx.partition) {
+    if (entry === undefined ||
+        entry.record.partition !== ctx.partition ||
+        entry.record.logEpoch !== registry.logEpoch) {
         throw syncError('sync.not_found', 'unknown segment (§5.5)');
     }
     if (entry.record.expiresAtMs <= clockOf(ctx)()) {

package/dist/segment-store.d.ts

@@ -1,6 +1,8 @@
 export declare const DEFAULT_SEGMENT_TTL_MS: number;
 export interface SegmentMetadata {
     readonly partition: string;
+    /** Partition log continuity that produced these bytes (§2.1). */
+    readonly logEpoch: string;
     readonly table: string;
     readonly schemaVersion: number;
     readonly mediaType: 'rows' | 'sqlite';
@@ -23,6 +25,7 @@ export interface SegmentRecord extends SegmentMetadata {
  */
 export interface SegmentFindKey {
     readonly partition: string;
+    readonly logEpoch: string;
     readonly table: string;
     readonly schemaVersion: number;
     readonly mediaType: 'rows' | 'sqlite';

package/dist/segment-store.js

@@ -35,6 +35,7 @@ export class MemorySegmentStore {
     async find(key, nowMs) {
         for (const { record } of this.#entries.values()) {
             if (record.partition === key.partition &&
+                record.logEpoch === key.logEpoch &&
                 record.table === key.table &&
                 record.schemaVersion === key.schemaVersion &&
                 record.mediaType === key.mediaType &&