@syncular/server 0.30.4 → 0.30.6

package/README.md

@@ -1232,3 +1232,13 @@ maxima, preserve registration fields, and require a matching actor and current
 partition log epoch. Leave missing records unchanged. SQLite, Postgres, and D1
 perform one update without reading or serializing the subscription list. HTTP
 registration keeps its existing cursor and subscription replacement rules.
+
+## Reviewed schema windows
+
+Pass `schemaWindow: [compileSchema(schema), compileSchema(previousSchema)]` to
+serve the prior codec through the current storage and validation rules. Entries
+are newest first, with the compiled current schema first. Added tables and
+appended nullable columns are supported. Removed/renamed columns, changed codecs,
+primary keys, references or scopes reject the window before serving. Hosts must
+exclude semantically incompatible prior versions. The [schema upgrade guide](https://syncular.dev/concepts-schema-upgrades/#serving-a-compatibility-window)
+owns the pull, segment, push and realtime contract.

package/dist/context.d.ts

@@ -11,7 +11,7 @@ import type { SyncularErrorHandler } from './errors.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
 import type { AnyReactionPlanner } from './reactions.js';
-import type { ServerSchema } from './schema.js';
+import type { ServerSchema, CompiledSchema } from './schema.js';
 import type { SegmentStore } from './segment-store.js';
 import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
 import type { SqliteImageBuilder } from './sqlite-image.js';
@@ -72,6 +72,8 @@ export interface RealtimeNotifier {
 }
 export interface SyncServerConfig {
     readonly schema: ServerSchema;
+    /** Current compiled schema followed by the supported previous versions, newest first. */
+    readonly schemaWindow?: readonly CompiledSchema[];
     readonly storage: ServerStorage;
     /**
      * RFC 0007: the backfill checkpoints this host installs. Every readiness

package/dist/handler.js

@@ -18,6 +18,7 @@ import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, prepareSecti
 import { processPushCommitWithTrace } from './push.js';
 import { serveNotReadyError } from './readiness.js';
 import { compileSchema } from './schema.js';
+import { schemaWindowOf, projectRowPayload } from './schema-window.js';
 import { computeEffective } from './scopes.js';
 import { StorageQueryError } from './storage-errors.js';
 import { serveGateRefusal, serveGateTokenChanged, } from './storage.js';
@@ -195,7 +196,7 @@ async function planRequest(request, ctx, schema, registry) {
         }
         validated.push({ frame, table: frame.table });
     }
-    const { resolved, leaseToEmit } = await resolveOnce(ctx, header.clientId, schema);
+    const { resolved, leaseToEmit } = await resolveOnce(ctx, header.clientId, compileSchema(ctx.schema));
     const subscriptions = validated.map(({ frame }) => {
         const table = schema.tables.get(frame.table);
         if (table === undefined)
@@ -291,8 +292,8 @@ async function* streamResponse(plan, ctx, schema, report) {
             report.outcome = 'schema_floor';
         yield encodeResponseFrame({
             type: 'RESP_HEADER',
-            requiredSchemaVersion: schema.version,
-            latestSchemaVersion: schema.version,
+            requiredSchemaVersion: schemaWindowOf(ctx.schema, ctx.schemaWindow).at(-1).version,
+            latestSchemaVersion: ctx.schema.version,
             ...(plan.wireVersion >= 2
                 ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
                 : {}),
@@ -302,7 +303,7 @@ async function* streamResponse(plan, ctx, schema, report) {
     }
     yield encodeResponseFrame({
         type: 'RESP_HEADER',
-        latestSchemaVersion: schema.version,
+        latestSchemaVersion: ctx.schema.version,
         ...(plan.wireVersion >= 2
             ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
             : {}),
@@ -335,8 +336,27 @@ async function* streamResponse(plan, ctx, schema, report) {
     try {
         // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
         for (const push of plan.pushes) {
-            const processed = await processPushCommitWithTrace(ctx, schema, plan.resolved, plan.header.clientId, push);
-            const { frame } = processed;
+            const processed = await processPushCommitWithTrace(ctx, compileSchema(ctx.schema), plan.resolved, plan.header.clientId, push, schema);
+            const frame = {
+                ...processed.frame,
+                results: processed.frame.results.map((result) => {
+                    if (result.status !== 'conflict')
+                        return result;
+                    const operation = push.operations[result.opIndex];
+                    const target = schema.tables.get(operation.table);
+                    const current = compileSchema(ctx.schema).tables.get(operation.table);
+                    return {
+                        ...result,
+                        serverRow: projectRowPayload(current, target, result.serverRow),
+                        conflictColumns: result.conflictColumns
+                            .slice(0, Math.ceil(target.columns.length / 8))
+                            .map((byte, i) => i === Math.ceil(target.columns.length / 8) - 1 &&
+                            target.columns.length % 8 !== 0
+                            ? byte & ((1 << (target.columns.length % 8)) - 1)
+                            : byte),
+                    };
+                }),
+            };
             if (events !== undefined) {
                 emitPushEvent(events, ctx, plan.header.clientId, push, processed);
             }
@@ -419,6 +439,7 @@ async function* streamResponse(plan, ctx, schema, report) {
                 id: s.frame.id,
                 table: s.frame.table,
                 scopes: s.frame.scopes,
+                schemaVersion: schema.version,
             }))
             : [...(previous?.subscriptions ?? [])];
         const cursor = cursors.length > 0 ? Math.min(...cursors) : (previous?.cursor ?? -1);
@@ -529,7 +550,12 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
     const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
     if (refusal !== undefined)
         throw serveNotReadyError(refusal);
-    const plan = await planRequest(request, ctx, schema, registry);
+    const window = schemaWindowOf(ctx.schema, ctx.schemaWindow);
+    const header = request.frames[0];
+    const selected = window.find((candidate) => header?.type === 'REQ_HEADER' &&
+        candidate.version === header.schemaVersion);
+    const served = selected ?? schema;
+    const plan = await planRequest(request, ctx, served, registry);
     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
@@ -541,7 +567,7 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
     // key, so refusing the request is safe (proved in the serve-gate lane).
     const verified = async function* () {
         const buffered = [];
-        for await (const chunk of streamResponse(plan, ctx, schema, report)) {
+        for await (const chunk of streamResponse(plan, ctx, served, report)) {
             buffered.push(chunk);
         }
         const after = await ctx.storage.readServeGate(ctx.partition, schema.version);

package/dist/index.d.ts

@@ -52,3 +52,4 @@ export * from './sqlite-storage.js';
 export * from './storage.js';
 export { StorageQueryError, type StorageQueryErrorCode, } from './storage-errors.js';
 export * from './validate.js';
+export { schemaWindowOf } from './schema-window.js';

package/dist/index.js

@@ -56,3 +56,4 @@ export * from './sqlite-storage.js';
 export * from './storage.js';
 export { StorageQueryError, } from './storage-errors.js';
 export * from './validate.js';
+export { schemaWindowOf } from './schema-window.js';

package/dist/pull.js

@@ -2,11 +2,12 @@
  * Pull: incremental commit delivery, cursors, bootstrap segments
  * (SPEC.md §4, §5).
  */
-import { decodeRow, encodeRowsSegment, } from '@syncular/core';
+import { encodeRowsSegment, } from '@syncular/core';
 import { clockOf, limitsOf } from './context.js';
 import { compileSchema, } from './schema.js';
 import { scopeDigest } from './scopes.js';
 import { issueSegmentUrl } from './signed-url.js';
+import { projectRowPayload, projectRowValues } from './schema-window.js';
 // One artifact build per owning storage pair and complete immutable identity.
 const imageBuilds = new WeakMap();
 /**
@@ -69,7 +70,7 @@ function parseBootstrapToken(raw, table) {
         return undefined;
     }
 }
-function commitFrame(table, commit) {
+function commitFrame(table, commit, current, target) {
     const changes = commit.changes.map((change) => ({
         tableIndex: 0,
         rowId: change.rowId,
@@ -78,7 +79,9 @@ function commitFrame(table, commit) {
             ? { rowVersion: change.rowVersion }
             : {}),
         scopes: change.scopes,
-        ...(change.payload !== undefined ? { row: change.payload } : {}),
+        ...(change.payload !== undefined
+            ? { row: projectRowPayload(current, target, change.payload) }
+            : {}),
     }));
     return {
         type: 'COMMIT',
@@ -220,7 +223,10 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
                 scopeDigest: digest,
                 rowBatches: (async function* () {
                     rowCount += probe.length;
-                    yield probe;
+                    yield probe.map((row) => ({
+                        ...row,
+                        payload: projectRowPayload(compileSchema(ctx.schema).tables.get(plan.table.name), plan.table, row.payload),
+                    }));
                     let afterRowId = probe[probe.length - 1].rowId;
                     for (;;) {
                         const rows = await storage.scanRows(partition, {
@@ -230,7 +236,10 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
                             limit: 5_000,
                         });
                         rowCount += rows.length;
-                        yield rows;
+                        yield rows.map((row) => ({
+                            ...row,
+                            payload: projectRowPayload(compileSchema(ctx.schema).tables.get(plan.table.name), plan.table, row.payload),
+                        }));
                         const last = rows[rows.length - 1];
                         if (rows.length < 5_000 || last === undefined)
                             break;
@@ -285,7 +294,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
         // §5.2: every row record carries the row's current server_version.
         const decoded = pageRows.map((row) => ({
             serverVersion: row.serverVersion,
-            values: decodeRow(plan.table.columns, row.payload),
+            values: projectRowValues(compileSchema(ctx.schema).tables.get(plan.table.name), plan.table, row.payload),
         }));
         const bytes = encodeRowsSegment({
             table: plan.table.name,
@@ -525,7 +534,7 @@ export async function* preparedSection(ctx, schema, limits, plan, maxSeq, prepar
             delivered + commit.changes.length > limits.limitCommits) {
             break;
         }
-        yield commitFrame(sub.table, commit);
+        yield commitFrame(sub.table, commit, compileSchema(ctx.schema).tables.get(sub.table), plan.table);
         delivered += commit.changes.length;
         deliveredCommits += 1;
         lastDeliveredSeq = commit.commitSeq;

package/dist/push.d.ts

@@ -42,10 +42,10 @@ export declare function processPushCommit(ctx: SyncRequestContext, schema: Compi
  * rejected replays as `status: rejected`; this companion result preserves the
  * cache provenance needed by structured events and server helpers.
  */
-export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<ProcessedPushCommit>;
+export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame, wireSchema?: CompiledSchema): Promise<ProcessedPushCommit>;
 /**
  * Shared serialized apply path for SSP2 commits and authoritative commands.
  * The builder runs after the partition lock and idempotency re-check, so its
  * reads and the returned operations share the transaction that is committed.
  */
-export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly PushOperation[]>): Promise<ProcessedPushCommit>;
+export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly PushOperation[]>, wireSchema?: CompiledSchema): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -161,9 +161,10 @@ async function mergeCrdtColumns(table, values, storedValues, present, opIndex, m
     }
     return { changed };
 }
-async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId) {
+async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId) {
     const table = schema.tables.get(op.table);
-    if (table === undefined) {
+    const wireTable = wireSchema.tables.get(op.table);
+    if (table === undefined || wireTable === undefined) {
         return errorRecord(opIndex, 'sync.unknown_table', `table ${JSON.stringify(op.table)} is not handled by this server`);
     }
     if (!resolved.ok) {
@@ -237,7 +238,9 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     }
     let sparse;
     try {
-        sparse = decodeSparseRow(table.columns, table.primaryKeyIndex, payload);
+        sparse = decodeSparseRow(wireTable.columns, wireTable.primaryKeyIndex, payload);
+        while (sparse.length < table.columns.length)
+            sparse.push(stored === undefined ? null : undefined);
     }
     catch (error) {
         return errorRecord(opIndex, 'sync.invalid_request', `row payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`);
@@ -830,15 +833,15 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
  * rejected replays as `status: rejected`; this companion result preserves the
  * cache provenance needed by structured events and server helpers.
  */
-export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame) {
-    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations);
+export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame, wireSchema = schema) {
+    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations, wireSchema);
 }
 /**
  * Shared serialized apply path for SSP2 commits and authoritative commands.
  * The builder runs after the partition lock and idempotency re-check, so its
  * reads and the returned operations share the transaction that is committed.
  */
-export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations) {
+export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations, wireSchema = schema) {
     const { storage, partition } = ctx;
     let persisted;
     try {
@@ -936,7 +939,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             const op = operations[opIndex];
             if (op === undefined)
                 continue;
-            const outcome = await applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId);
+            const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId);
             if (outcome.kind === 'terminate') {
                 terminated = outcome.record;
                 break;

package/dist/readiness.d.ts

@@ -29,7 +29,7 @@ export declare class SyncServerReadinessError extends Error {
  * exposes only a stable code, phase, and schema version; operators can inspect
  * `cause` locally for the table/column or storage diagnostic.
  */
-export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'schema' | 'storage' | 'checkpoints'>): Promise<void>;
+export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'schema' | 'schemaWindow' | 'storage' | 'checkpoints'>): Promise<void>;
 /**
  * RFC 0007: refuse a serve path that observed a closed gate. The projection
  * name travels in structured details, never in the message.

package/dist/readiness.js

@@ -1,5 +1,6 @@
 import { syncError } from './errors.js';
 import { compileSchema } from './schema.js';
+import { schemaWindowOf } from './schema-window.js';
 export const SYNC_SERVER_READINESS_ERROR_CODE = 'sync.schema_not_ready';
 export class SyncServerReadinessError extends Error {
     name = 'SyncServerReadinessError';
@@ -23,6 +24,7 @@ export async function ensureSyncServerReady(config) {
     let compiled;
     try {
         compiled = compileSchema(config.schema);
+        schemaWindowOf(config.schema, config.schemaWindow);
     }
     catch (cause) {
         throw new SyncServerReadinessError({

package/dist/realtime.d.ts

@@ -20,6 +20,7 @@ import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/cor
 import type { SyncRequestContext, SyncServerConfig } from './context.js';
 import { type SyncularErrorHandler } from './errors.js';
 import { type SyncularServerEvents } from './events.js';
+import { type CompiledTable } from './schema.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
 /**
  * Realtime adds fanout/presence tuning to the canonical sync-server config;
@@ -62,6 +63,7 @@ export interface RealtimeConnectOptions {
     readonly closeSocket?: () => void;
 }
 interface Registration {
+    readonly codec: CompiledTable;
     readonly id: string;
     readonly table: string;
     readonly effective: ScopeMap;
@@ -172,6 +174,7 @@ export declare class RealtimeHub {
     /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
     readonly presence: PresenceRegistry;
     constructor(config: RealtimeHubConfig);
+    projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
     get sessionCount(): number;
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes(): number;

package/dist/realtime.js

@@ -21,7 +21,8 @@ import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPar
 import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
 import { emitEvent } from './events.js';
 import { createSyncResponseStream } from './handler.js';
-import { compileSchema } from './schema.js';
+import { compileSchema, } from './schema.js';
+import { schemaWindowOf, projectRowPayload } from './schema-window.js';
 import { computeEffective, matchesEffective, } from './scopes.js';
 const DEFAULT_MAX_DELTA_BYTES = 1024 * 1024;
 const DEFAULT_MAX_PRESENCE_BYTES = 16 * 1024;
@@ -608,7 +609,9 @@ export class RealtimeSession {
                     ? { rowVersion: change.rowVersion }
                     : {}),
                 scopes: change.scopes,
-                ...(change.payload !== undefined ? { row: change.payload } : {}),
+                ...(change.payload !== undefined
+                    ? { row: this.#hub.projectPayload(registration, change.payload) }
+                    : {}),
             }));
             if (changes.length > 0)
                 sections.push({ registration, changes });
@@ -706,6 +709,10 @@ export class RealtimeHub {
     constructor(config) {
         this.#config = config;
         this.#schema = compileSchema(config.schema);
+        schemaWindowOf(config.schema, config.schemaWindow);
+    }
+    projectPayload(registration, payload) {
+        return projectRowPayload(this.#schema.tables.get(registration.table), registration.codec, payload);
     }
     get sessionCount() {
         return this.#sessions.size;
@@ -775,7 +782,12 @@ export class RealtimeHub {
         }
         const registrations = [];
         for (const subscription of record?.subscriptions ?? []) {
-            const table = this.#schema.tables.get(subscription.table);
+            const window = schemaWindowOf(this.#config.schema, this.#config.schemaWindow);
+            const selected = subscription.schemaVersion === undefined &&
+                this.#config.schemaWindow === undefined
+                ? this.#schema
+                : window.find((schema) => schema.version === subscription.schemaVersion);
+            const table = selected?.tables.get(subscription.table);
             if (table === undefined)
                 continue;
             const keysValid = Object.keys(subscription.scopes).every((key) => table.declaredVariables.has(key));
@@ -786,6 +798,7 @@ export class RealtimeHub {
                 continue;
             registrations.push({
                 id: subscription.id,
+                codec: table,
                 table: subscription.table,
                 effective: outcome.effective,
             });
@@ -808,6 +821,9 @@ export class RealtimeHub {
             partition: identity.partition,
             actorId: identity.actorId,
             schema: this.#config.schema,
+            ...(this.#config.schemaWindow !== undefined
+                ? { schemaWindow: this.#config.schemaWindow }
+                : {}),
             storage: this.#config.storage,
             segments,
             resolveScopes: this.#config.resolveScopes,
@@ -896,7 +912,10 @@ export class RealtimeHub {
                 clientId: options.clientId,
                 cursor,
                 latestCursor: latestSeq,
-                requiresSync: record === undefined || cursor < latestSeq,
+                requiresSync: record === undefined ||
+                    cursor < latestSeq ||
+                    (this.#config.schemaWindow !== undefined &&
+                        record.subscriptions.some((subscription) => !schemaWindowOf(this.#config.schema, this.#config.schemaWindow).some((schema) => schema.version === subscription.schemaVersion))),
                 timestamp: clock(),
             },
         }));

package/dist/schema-window.d.ts

@@ -0,0 +1,7 @@
+import { type RowValue } from '@syncular/core';
+import { type CompiledSchema, type CompiledTable, type ServerSchema } from './schema.js';
+/** A host-reviewed newest-first window. Storage and validation always use current. */
+export declare function schemaWindowOf(current: ServerSchema, configured?: readonly CompiledSchema[]): readonly CompiledSchema[];
+/** Canonical stored bytes never leave the server under another version's codec. */
+export declare function projectRowValues(current: CompiledTable, target: CompiledTable, payload: Uint8Array): RowValue[];
+export declare function projectRowPayload(current: CompiledTable, target: CompiledTable, payload: Uint8Array): Uint8Array;

package/dist/schema-window.js

@@ -0,0 +1,46 @@
+import { decodeRow, encodeRow } from '@syncular/core';
+import { compileSchema, } from './schema.js';
+const validatedWindows = new WeakMap();
+/** A host-reviewed newest-first window. Storage and validation always use current. */
+export function schemaWindowOf(current, configured) {
+    const head = compileSchema(current);
+    if (configured === undefined)
+        return [head];
+    if (validatedWindows.get(configured) === head)
+        return configured;
+    if (configured.length === 0 || configured[0] !== head)
+        throw new Error('sync.schema_window.invalid_head');
+    let previous = head.version + 1;
+    for (const schema of configured) {
+        if (schema.version >= previous)
+            throw new Error('sync.schema_window.invalid_order');
+        previous = schema.version;
+        for (const table of schema.tables.values()) {
+            const next = head.tables.get(table.name);
+            if (next === undefined ||
+                table.columns.length > next.columns.length ||
+                table.columns.some((column, i) => JSON.stringify(column) !== JSON.stringify(next.columns[i])) ||
+                next.columns
+                    .slice(table.columns.length)
+                    .some((column) => !column.nullable) ||
+                table.primaryKeyIndex !== next.primaryKeyIndex ||
+                JSON.stringify(table.scopePatterns) !==
+                    JSON.stringify(next.scopePatterns) ||
+                JSON.stringify(table.references) !== JSON.stringify(next.references)) {
+                throw new Error('sync.schema_window.incompatible_schema');
+            }
+        }
+    }
+    validatedWindows.set(configured, head);
+    return configured;
+}
+/** Canonical stored bytes never leave the server under another version's codec. */
+export function projectRowValues(current, target, payload) {
+    const values = decodeRow(current.columns, payload);
+    return values.slice(0, target.columns.length);
+}
+export function projectRowPayload(current, target, payload) {
+    return current === target
+        ? payload
+        : encodeRow(target.columns, projectRowValues(current, target, payload));
+}

package/dist/segment-download.js

@@ -2,6 +2,7 @@ import { clockOf, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './contex
 import { SyncError, syncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { compileSchema } from './schema.js';
+import { schemaWindowOf } from './schema-window.js';
 import { computeEffective, scopeDigest } from './scopes.js';
 import { bytesStream, publicationRecord, } from './segment-store.js';
 function parseScopesHeader(header) {
@@ -184,7 +185,8 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
     // earlier valid publication of the same bytes exists.
     const schema = compileSchema(ctx.schema);
     const candidates = live.filter((publication) => {
-        const table = schema.tables.get(publication.table);
+        const served = schemaWindowOf(ctx.schema, ctx.schemaWindow).find((candidate) => candidate.version === publication.schemaVersion);
+        const table = served?.tables.get(publication.table);
         return (table !== undefined &&
             Object.entries(requested).every(([key, values]) => table.declaredVariables.has(key) && !values.includes('*')));
     });

package/dist/storage.d.ts

@@ -219,6 +219,8 @@ export interface StoredPushResult {
     readonly results: readonly PushOperationResult[];
 }
 export interface ClientSubscription {
+    /** Codec accepted by the last pull; absent on records written before schema windows. */
+    readonly schemaVersion?: number;
     readonly id: string;
     readonly table: string;
     /** Requested scopes of the client's most recent pull (§8.1). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.30.4",
+  "version": "0.30.6",
   "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.30.4"
+    "@syncular/core": "0.30.6"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/context.ts

@@ -11,7 +11,7 @@ import type { SyncularErrorHandler } from './errors';
 import type { SyncularServerEvents } from './events';
 import type { LeaseStore } from './lease-store';
 import type { AnyReactionPlanner } from './reactions';
-import type { ServerSchema } from './schema';
+import type { ServerSchema, CompiledSchema } from './schema';
 import type { SegmentStore } from './segment-store';
 import type {
   BlobPresignConfig,
@@ -97,6 +97,8 @@ export interface RealtimeNotifier {
 
 export interface SyncServerConfig {
   readonly schema: ServerSchema;
+  /** Current compiled schema followed by the supported previous versions, newest first. */
+  readonly schemaWindow?: readonly CompiledSchema[];
   readonly storage: ServerStorage;
   /**
    * RFC 0007: the backfill checkpoints this host installs. Every readiness

package/src/handler.ts

@@ -55,6 +55,7 @@ import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
 import { serveNotReadyError } from './readiness';
 import type { CompiledSchema } from './schema';
 import { compileSchema } from './schema';
+import { schemaWindowOf, projectRowPayload } from './schema-window';
 import { computeEffective, type ResolvedScopes } from './scopes';
 import { StorageQueryError } from './storage-errors';
 import {
@@ -343,7 +344,7 @@ async function planRequest(
   const { resolved, leaseToEmit } = await resolveOnce(
     ctx,
     header.clientId,
-    schema,
+    compileSchema(ctx.schema),
   );
 
   const subscriptions: SubscriptionPlan[] = validated.map(({ frame }) => {
@@ -466,8 +467,10 @@ async function* streamResponse(
     yield encodeResponseFrame(
       {
         type: 'RESP_HEADER',
-        requiredSchemaVersion: schema.version,
-        latestSchemaVersion: schema.version,
+        requiredSchemaVersion: schemaWindowOf(ctx.schema, ctx.schemaWindow).at(
+          -1,
+        )!.version,
+        latestSchemaVersion: ctx.schema.version,
         ...(plan.wireVersion >= 2
           ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
           : {}),
@@ -480,7 +483,7 @@ async function* streamResponse(
   yield encodeResponseFrame(
     {
       type: 'RESP_HEADER',
-      latestSchemaVersion: schema.version,
+      latestSchemaVersion: ctx.schema.version,
       ...(plan.wireVersion >= 2
         ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
         : {}),
@@ -519,12 +522,35 @@ async function* streamResponse(
     for (const push of plan.pushes) {
       const processed = await processPushCommitWithTrace(
         ctx,
-        schema,
+        compileSchema(ctx.schema),
         plan.resolved,
         plan.header.clientId,
         push,
+        schema,
       );
-      const { frame } = processed;
+      const frame = {
+        ...processed.frame,
+        results: processed.frame.results.map((result) => {
+          if (result.status !== 'conflict') return result;
+          const operation = push.operations[result.opIndex]!;
+          const target = schema.tables.get(operation.table)!;
+          const current = compileSchema(ctx.schema).tables.get(
+            operation.table,
+          )!;
+          return {
+            ...result,
+            serverRow: projectRowPayload(current, target, result.serverRow),
+            conflictColumns: result.conflictColumns
+              .slice(0, Math.ceil(target.columns.length / 8))
+              .map((byte, i) =>
+                i === Math.ceil(target.columns.length / 8) - 1 &&
+                target.columns.length % 8 !== 0
+                  ? byte & ((1 << (target.columns.length % 8)) - 1)
+                  : byte,
+              ),
+          };
+        }),
+      };
       if (events !== undefined) {
         emitPushEvent(events, ctx, plan.header.clientId, push, processed);
       }
@@ -630,6 +656,7 @@ async function* streamResponse(
             id: s.frame.id,
             table: s.frame.table,
             scopes: s.frame.scopes,
+            schemaVersion: schema.version,
           }))
         : [...(previous?.subscriptions ?? [])];
     const cursor =
@@ -754,7 +781,15 @@ async function createStreamCore(
   const gate = await ctx.storage.readServeGate(ctx.partition, schema.version);
   const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
   if (refusal !== undefined) throw serveNotReadyError(refusal);
-  const plan = await planRequest(request, ctx, schema, registry);
+  const window = schemaWindowOf(ctx.schema, ctx.schemaWindow);
+  const header = request.frames[0];
+  const selected = window.find(
+    (candidate) =>
+      header?.type === 'REQ_HEADER' &&
+      candidate.version === header.schemaVersion,
+  );
+  const served = selected ?? schema;
+  const plan = await planRequest(request, ctx, served, registry);
   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
@@ -766,7 +801,7 @@ async function createStreamCore(
   // key, so refusing the request is safe (proved in the serve-gate lane).
   const verified = async function* (): AsyncGenerator<Uint8Array> {
     const buffered: Uint8Array[] = [];
-    for await (const chunk of streamResponse(plan, ctx, schema, report)) {
+    for await (const chunk of streamResponse(plan, ctx, served, report)) {
       buffered.push(chunk);
     }
     const after = await ctx.storage.readServeGate(

package/src/index.ts

@@ -93,3 +93,5 @@ export {
   type StorageQueryErrorCode,
 } from './storage-errors';
 export * from './validate';
+
+export { schemaWindowOf } from './schema-window';

package/src/pull.ts

@@ -4,7 +4,6 @@
  */
 import {
   type CommitChange,
-  decodeRow,
   encodeRowsSegment,
   type PullHeaderFrame,
   type ResponseFrame,
@@ -26,6 +25,7 @@ import type { SegmentRecord, SegmentStore } from './segment-store';
 import { issueSegmentUrl } from './signed-url';
 import type { SqliteImageBuilder } from './sqlite-image';
 import type { ServerStorage, StoredCommit, StoredRow } from './storage';
+import { projectRowPayload, projectRowValues } from './schema-window';
 
 // One artifact build per owning storage pair and complete immutable identity.
 const imageBuilds = new WeakMap<
@@ -136,7 +136,12 @@ function parseBootstrapToken(
   }
 }
 
-function commitFrame(table: string, commit: StoredCommit): ResponseFrame {
+function commitFrame(
+  table: string,
+  commit: StoredCommit,
+  current: CompiledTable,
+  target: CompiledTable,
+): ResponseFrame {
   const changes: CommitChange[] = commit.changes.map((change) => ({
     tableIndex: 0,
     rowId: change.rowId,
@@ -145,7 +150,9 @@ function commitFrame(table: string, commit: StoredCommit): ResponseFrame {
       ? { rowVersion: change.rowVersion }
       : {}),
     scopes: change.scopes,
-    ...(change.payload !== undefined ? { row: change.payload } : {}),
+    ...(change.payload !== undefined
+      ? { row: projectRowPayload(current, target, change.payload) }
+      : {}),
   }));
   return {
     type: 'COMMIT',
@@ -318,7 +325,14 @@ async function* sqliteImageSegment(
         scopeDigest: digest,
         rowBatches: (async function* () {
           rowCount += probe.length;
-          yield probe;
+          yield probe.map((row) => ({
+            ...row,
+            payload: projectRowPayload(
+              compileSchema(ctx.schema).tables.get(plan.table.name)!,
+              plan.table,
+              row.payload,
+            ),
+          }));
           let afterRowId = probe[probe.length - 1]!.rowId;
           for (;;) {
             const rows = await storage.scanRows(partition, {
@@ -328,7 +342,14 @@ async function* sqliteImageSegment(
               limit: 5_000,
             });
             rowCount += rows.length;
-            yield rows;
+            yield rows.map((row) => ({
+              ...row,
+              payload: projectRowPayload(
+                compileSchema(ctx.schema).tables.get(plan.table.name)!,
+                plan.table,
+                row.payload,
+              ),
+            }));
             const last = rows[rows.length - 1];
             if (rows.length < 5_000 || last === undefined) break;
             afterRowId = last.rowId;
@@ -420,7 +441,11 @@ async function* bootstrapSegments(
     // §5.2: every row record carries the row's current server_version.
     const decoded = pageRows.map((row: StoredRow) => ({
       serverVersion: row.serverVersion,
-      values: decodeRow(plan.table.columns, row.payload),
+      values: projectRowValues(
+        compileSchema(ctx.schema).tables.get(plan.table.name)!,
+        plan.table,
+        row.payload,
+      ),
     }));
     const bytes = encodeRowsSegment({
       table: plan.table.name,
@@ -772,7 +797,12 @@ export async function* preparedSection(
     ) {
       break;
     }
-    yield commitFrame(sub.table, commit);
+    yield commitFrame(
+      sub.table,
+      commit,
+      compileSchema(ctx.schema).tables.get(sub.table)!,
+      plan.table,
+    );
     delivered += commit.changes.length;
     deliveredCommits += 1;
     lastDeliveredSeq = commit.commitSeq;

package/src/push.ts

@@ -293,6 +293,7 @@ async function mergeCrdtColumns(
 async function applyOperation(
   tx: StorageTransaction,
   schema: CompiledSchema,
+  wireSchema: CompiledSchema,
   resolved: ResolvedScopes,
   op: PushOperation,
   opIndex: number,
@@ -303,7 +304,8 @@ async function applyOperation(
   actorId: string,
 ): Promise<OperationOutcome> {
   const table = schema.tables.get(op.table);
-  if (table === undefined) {
+  const wireTable = wireSchema.tables.get(op.table);
+  if (table === undefined || wireTable === undefined) {
     return errorRecord(
       opIndex,
       'sync.unknown_table',
@@ -409,7 +411,13 @@ async function applyOperation(
   }
   let sparse: SparseRowValue[];
   try {
-    sparse = decodeSparseRow(table.columns, table.primaryKeyIndex, payload);
+    sparse = decodeSparseRow(
+      wireTable.columns,
+      wireTable.primaryKeyIndex,
+      payload,
+    );
+    while (sparse.length < table.columns.length)
+      sparse.push(stored === undefined ? null : undefined);
   } catch (error) {
     return errorRecord(
       opIndex,
@@ -1300,6 +1308,7 @@ export async function processPushCommitWithTrace(
   resolved: ResolvedScopes,
   clientId: string,
   frame: PushCommitFrame,
+  wireSchema: CompiledSchema = schema,
 ): Promise<ProcessedPushCommit> {
   return processPushOperationsWithTrace(
     ctx,
@@ -1308,6 +1317,7 @@ export async function processPushCommitWithTrace(
     clientId,
     frame.clientCommitId,
     async () => frame.operations,
+    wireSchema,
   );
 }
 
@@ -1325,6 +1335,7 @@ export async function processPushOperationsWithTrace(
   buildOperations: (
     tx: StorageTransaction,
   ) => Promise<readonly PushOperation[]>,
+  wireSchema: CompiledSchema = schema,
 ): Promise<ProcessedPushCommit> {
   const { storage, partition } = ctx;
   let persisted: StoredPushResult | undefined;
@@ -1437,6 +1448,7 @@ export async function processPushOperationsWithTrace(
       const outcome = await applyOperation(
         tx,
         schema,
+        wireSchema,
         resolved,
         op,
         opIndex,

package/src/readiness.ts

@@ -9,6 +9,7 @@
 import type { SyncServerConfig } from './context';
 import { type SyncError, syncError } from './errors';
 import { type CompiledSchema, compileSchema } from './schema';
+import { schemaWindowOf } from './schema-window';
 import type { ServeGateRefusal } from './storage';
 
 export const SYNC_SERVER_READINESS_ERROR_CODE =
@@ -47,11 +48,15 @@ export class SyncServerReadinessError extends Error {
  * `cause` locally for the table/column or storage diagnostic.
  */
 export async function ensureSyncServerReady(
-  config: Pick<SyncServerConfig, 'schema' | 'storage' | 'checkpoints'>,
+  config: Pick<
+    SyncServerConfig,
+    'schema' | 'schemaWindow' | 'storage' | 'checkpoints'
+  >,
 ): Promise<void> {
   let compiled: CompiledSchema;
   try {
     compiled = compileSchema(config.schema);
+    schemaWindowOf(config.schema, config.schemaWindow);
   } catch (cause) {
     throw new SyncServerReadinessError({
       phase: 'schema_compile',

package/src/realtime.ts

@@ -48,7 +48,12 @@ import {
 } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
 import { createSyncResponseStream } from './handler';
-import { type CompiledSchema, compileSchema } from './schema';
+import {
+  type CompiledSchema,
+  type CompiledTable,
+  compileSchema,
+} from './schema';
+import { schemaWindowOf, projectRowPayload } from './schema-window';
 import {
   computeEffective,
   matchesEffective,
@@ -99,6 +104,7 @@ export interface RealtimeConnectOptions {
 }
 
 interface Registration {
+  readonly codec: CompiledTable;
   readonly id: string;
   readonly table: string;
   readonly effective: ScopeMap;
@@ -794,7 +800,9 @@ export class RealtimeSession {
               ? { rowVersion: change.rowVersion }
               : {}),
             scopes: change.scopes,
-            ...(change.payload !== undefined ? { row: change.payload } : {}),
+            ...(change.payload !== undefined
+              ? { row: this.#hub.projectPayload(registration, change.payload) }
+              : {}),
           }),
         );
       if (changes.length > 0) sections.push({ registration, changes });
@@ -894,6 +902,15 @@ export class RealtimeHub {
   constructor(config: RealtimeHubConfig) {
     this.#config = config;
     this.#schema = compileSchema(config.schema);
+    schemaWindowOf(config.schema, config.schemaWindow);
+  }
+
+  projectPayload(registration: Registration, payload: Uint8Array): Uint8Array {
+    return projectRowPayload(
+      this.#schema.tables.get(registration.table)!,
+      registration.codec,
+      payload,
+    );
   }
 
   get sessionCount(): number {
@@ -983,7 +1000,18 @@ export class RealtimeHub {
     }
     const registrations: Registration[] = [];
     for (const subscription of record?.subscriptions ?? []) {
-      const table = this.#schema.tables.get(subscription.table);
+      const window = schemaWindowOf(
+        this.#config.schema,
+        this.#config.schemaWindow,
+      );
+      const selected =
+        subscription.schemaVersion === undefined &&
+        this.#config.schemaWindow === undefined
+          ? this.#schema
+          : window.find(
+              (schema) => schema.version === subscription.schemaVersion,
+            );
+      const table = selected?.tables.get(subscription.table);
       if (table === undefined) continue;
       const keysValid = Object.keys(subscription.scopes).every((key) =>
         table.declaredVariables.has(key),
@@ -993,6 +1021,7 @@ export class RealtimeHub {
       if (outcome.status !== 'active') continue;
       registrations.push({
         id: subscription.id,
+        codec: table,
         table: subscription.table,
         effective: outcome.effective,
       });
@@ -1022,6 +1051,9 @@ export class RealtimeHub {
       partition: identity.partition,
       actorId: identity.actorId,
       schema: this.#config.schema,
+      ...(this.#config.schemaWindow !== undefined
+        ? { schemaWindow: this.#config.schemaWindow }
+        : {}),
       storage: this.#config.storage,
       segments,
       resolveScopes: this.#config.resolveScopes,
@@ -1139,7 +1171,19 @@ export class RealtimeHub {
           clientId: options.clientId,
           cursor,
           latestCursor: latestSeq,
-          requiresSync: record === undefined || cursor < latestSeq,
+          requiresSync:
+            record === undefined ||
+            cursor < latestSeq ||
+            (this.#config.schemaWindow !== undefined &&
+              record.subscriptions.some(
+                (subscription) =>
+                  !schemaWindowOf(
+                    this.#config.schema,
+                    this.#config.schemaWindow,
+                  ).some(
+                    (schema) => schema.version === subscription.schemaVersion,
+                  ),
+              )),
           timestamp: clock(),
         },
       }),

package/src/schema-window.ts

@@ -0,0 +1,72 @@
+import { decodeRow, encodeRow, type RowValue } from '@syncular/core';
+import {
+  compileSchema,
+  type CompiledSchema,
+  type CompiledTable,
+  type ServerSchema,
+} from './schema';
+
+const validatedWindows = new WeakMap<
+  readonly CompiledSchema[],
+  CompiledSchema
+>();
+
+/** A host-reviewed newest-first window. Storage and validation always use current. */
+export function schemaWindowOf(
+  current: ServerSchema,
+  configured?: readonly CompiledSchema[],
+): readonly CompiledSchema[] {
+  const head = compileSchema(current);
+  if (configured === undefined) return [head];
+  if (validatedWindows.get(configured) === head) return configured;
+  if (configured.length === 0 || configured[0] !== head)
+    throw new Error('sync.schema_window.invalid_head');
+  let previous = head.version + 1;
+  for (const schema of configured) {
+    if (schema.version >= previous)
+      throw new Error('sync.schema_window.invalid_order');
+    previous = schema.version;
+    for (const table of schema.tables.values()) {
+      const next = head.tables.get(table.name);
+      if (
+        next === undefined ||
+        table.columns.length > next.columns.length ||
+        table.columns.some(
+          (column, i) =>
+            JSON.stringify(column) !== JSON.stringify(next.columns[i]),
+        ) ||
+        next.columns
+          .slice(table.columns.length)
+          .some((column) => !column.nullable) ||
+        table.primaryKeyIndex !== next.primaryKeyIndex ||
+        JSON.stringify(table.scopePatterns) !==
+          JSON.stringify(next.scopePatterns) ||
+        JSON.stringify(table.references) !== JSON.stringify(next.references)
+      ) {
+        throw new Error('sync.schema_window.incompatible_schema');
+      }
+    }
+  }
+  validatedWindows.set(configured, head);
+  return configured;
+}
+
+/** Canonical stored bytes never leave the server under another version's codec. */
+export function projectRowValues(
+  current: CompiledTable,
+  target: CompiledTable,
+  payload: Uint8Array,
+): RowValue[] {
+  const values = decodeRow(current.columns, payload);
+  return values.slice(0, target.columns.length);
+}
+
+export function projectRowPayload(
+  current: CompiledTable,
+  target: CompiledTable,
+  payload: Uint8Array,
+): Uint8Array {
+  return current === target
+    ? payload
+    : encodeRow(target.columns, projectRowValues(current, target, payload));
+}

package/src/segment-download.ts

@@ -18,6 +18,7 @@ import {
 import { SyncError, syncError } from './errors';
 import { emitEvent } from './events';
 import { compileSchema } from './schema';
+import { schemaWindowOf } from './schema-window';
 import { computeEffective, type ResolvedScopes, scopeDigest } from './scopes';
 import {
   bytesStream,
@@ -291,7 +292,10 @@ async function authorizePublication(
   // earlier valid publication of the same bytes exists.
   const schema = compileSchema(ctx.schema);
   const candidates = live.filter((publication) => {
-    const table = schema.tables.get(publication.table);
+    const served = schemaWindowOf(ctx.schema, ctx.schemaWindow).find(
+      (candidate) => candidate.version === publication.schemaVersion,
+    );
+    const table = served?.tables.get(publication.table);
     return (
       table !== undefined &&
       Object.entries(requested).every(

package/src/storage.ts

@@ -288,6 +288,8 @@ export interface StoredPushResult {
 }
 
 export interface ClientSubscription {
+  /** Codec accepted by the last pull; absent on records written before schema windows. */
+  readonly schemaVersion?: number;
   readonly id: string;
   readonly table: string;
   /** Requested scopes of the client's most recent pull (§8.1). */