@syncular/server 0.20.1 → 0.21.0

package/dist/push.js

@@ -17,12 +17,13 @@
  * merge); a validator throw rejects the whole commit atomically with a
  * host code.
  */
-import { decodeRow, encodeRow, parseBlobRef, } from '@syncular/core';
-import { clockOf } from './context.js';
+import { decodeRow, decodeSparseRow, encodeRow, parseBlobRef, } from '@syncular/core';
+import { clockOf, limitsOf } from './context.js';
 import { SyncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
+import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
 import { StorageConstraintError } from './storage-errors.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
@@ -52,19 +53,28 @@ function errorRecord(opIndex, code, message, retryable = false, details) {
         },
     };
 }
-function conflictRecord(opIndex, serverVersion, serverRow) {
+function conflictRecord(opIndex, serverVersion, serverRow, conflictColumns) {
     return {
         kind: 'terminate',
         record: {
             opIndex,
             status: 'conflict',
             code: 'sync.version_conflict',
-            message: 'row version does not match baseVersion (§6.2)',
+            message: 'present columns moved past baseVersion (§6.2)',
             serverVersion,
             serverRow,
+            conflictColumns,
         },
     };
 }
+/** §6.3 `conflictColumns`: a presence-layout bitmap over the marked columns. */
+function conflictColumnsBitmap(columnCount, marked) {
+    const bytes = new Uint8Array(Math.ceil(columnCount / 8));
+    for (const index of marked) {
+        bytes[index >> 3] = (bytes[index >> 3] ?? 0) | (1 << (index & 7));
+    }
+    return bytes;
+}
 /**
  * §6.7: run the table's write-validation hook, if configured, on the row
  * that WILL persist (post scope-strip, post CRDT-merge — the values the
@@ -112,13 +122,17 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
  *
  * A NULL incoming crdt value is a semantic clear, not a merge — it passes
  * through untouched (the app is nulling the column, the same as any other
- * type). Merging only runs for a non-NULL incoming crdt value.
+ * type). Merging only runs for a non-NULL incoming crdt value. `present`
+ * marks the sparse payload's present columns (§6.2): an absent crdt column
+ * is unchanged and never merges.
  */
-async function mergeCrdtColumns(table, values, storedValues, opIndex, mergers) {
+async function mergeCrdtColumns(table, values, storedValues, present, opIndex, mergers) {
     if (table.crdtColumns.length === 0)
         return { changed: false };
     let changed = false;
     for (const { index, crdtType } of table.crdtColumns) {
+        if (!present[index])
+            continue;
         const incoming = values[index];
         if (!(incoming instanceof Uint8Array))
             continue; // NULL clear or absent
@@ -163,6 +177,13 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
                     row: undefined,
                     stored: undefined,
                 },
+                staged: {
+                    table,
+                    op: 'delete',
+                    rowId: op.rowId,
+                    opIndex,
+                    stored: undefined,
+                },
             };
         }
         if (!authorizeWrite(table, stored.scopes, resolved)) {
@@ -197,74 +218,126 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
                 stored: toValidateRow(table.columns, storedValues),
                 storedServerVersion: stored.serverVersion,
             },
+            staged: { table, op: 'delete', rowId: op.rowId, opIndex, stored },
         };
     }
-    // upsert — payload presence is enforced by the envelope codec (§6.1).
+    // upsert — payload presence is enforced by the envelope codec (§6.1). The
+    // payload is a sparse row (§2.4, wire version 3): `undefined` marks an
+    // absent column the apply leaves unchanged.
     const payload = op.payload;
     if (payload === undefined) {
         return errorRecord(opIndex, 'sync.invalid_request', 'upsert without payload');
     }
-    let values;
+    let sparse;
     try {
-        values = decodeRow(table.columns, payload);
+        sparse = decodeSparseRow(table.columns, table.primaryKeyIndex, payload);
     }
     catch (error) {
         return errorRecord(opIndex, 'sync.invalid_request', `row payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`);
     }
-    const pkValue = renderScopeValue(values[table.primaryKeyIndex]);
+    const pkValue = renderScopeValue(sparse[table.primaryKeyIndex] ?? null);
     if (pkValue !== op.rowId) {
         return errorRecord(opIndex, 'sync.invalid_request', 'payload primary key does not match rowId');
     }
+    const present = sparse.map((value) => value !== undefined);
+    const presentCount = present.filter(Boolean).length;
     if (stored !== undefined) {
         // §3.4 step 2: authorize against the STORED row, never the payload.
         if (!authorizeWrite(table, stored.scopes, resolved)) {
             return errorRecord(opIndex, 'sync.forbidden', 'write denied by scope authorization (§3.4)');
         }
-        if (op.baseVersion === 0) {
-            // Lost insert race (§6.2); the stored row was authorized above,
-            // so disclosure of the winner is permitted.
-            return conflictRecord(opIndex, stored.serverVersion, stored.payload);
-        }
-        if (op.baseVersion !== undefined &&
-            op.baseVersion !== stored.serverVersion) {
-            return conflictRecord(opIndex, stored.serverVersion, stored.payload);
-        }
-        // §3.4 rule 5: scope columns are immutable on update — keep the
-        // stored row's scope column values on both the baseVersion and
-        // last-write-wins paths.
         const storedValues = decodeRow(table.columns, stored.payload);
-        let mutated = false;
+        // §3.4 rule 5 / §6.2: scope columns are immutable on update. A present
+        // scope column whose value differs from the stored row is
+        // sync.invalid_request; present and equal applies as a no-op.
         for (const pattern of table.scopePatterns) {
-            const storedValue = storedValues[pattern.columnIndex] ?? null;
-            if (values[pattern.columnIndex] !== storedValue) {
-                values[pattern.columnIndex] = storedValue;
-                mutated = true;
+            const incoming = sparse[pattern.columnIndex];
+            if (incoming === undefined)
+                continue;
+            if ((incoming ?? null) !== (storedValues[pattern.columnIndex] ?? null)) {
+                return errorRecord(opIndex, 'sync.invalid_request', 'scope column is immutable on update (§3.4)');
+            }
+        }
+        if (op.baseVersion !== undefined && op.baseVersion > stored.serverVersion) {
+            return errorRecord(opIndex, 'sync.invalid_request', 'baseVersion exceeds the stored server version (§6.2)');
+        }
+        // §2.2 column versions. A row stored before column versions carries no
+        // blob: every column sits at the row's current serverVersion. With a
+        // blob, an unlisted column sits at 1.
+        const storedVersions = decodeColumnVersions(stored.columnVersions);
+        const effectiveVersion = (index) => storedVersions.get(index) ??
+            (stored.columnVersions === undefined ? stored.serverVersion : 1);
+        const crdtIndexes = new Set(table.crdtColumns.map((column) => column.index));
+        if (op.baseVersion === 0) {
+            // Lost insert race (§6.2); the stored row was authorized above, so
+            // disclosure of the winner is permitted. Every present non-crdt
+            // column exceeds baseVersion 0.
+            const marked = [];
+            for (let i = 0; i < table.columns.length; i++) {
+                if (present[i] && !crdtIndexes.has(i) && i !== table.primaryKeyIndex) {
+                    marked.push(i);
+                }
+            }
+            return conflictRecord(opIndex, stored.serverVersion, stored.payload, conflictColumnsBitmap(table.columns.length, marked));
+        }
+        if (op.baseVersion !== undefined) {
+            // §6.2: conflict when any present non-crdt column moved past
+            // baseVersion. crdt columns merge and never conflict.
+            const marked = [];
+            for (let i = 0; i < table.columns.length; i++) {
+                if (present[i] &&
+                    !crdtIndexes.has(i) &&
+                    effectiveVersion(i) > op.baseVersion) {
+                    marked.push(i);
+                }
+            }
+            if (marked.length > 0) {
+                return conflictRecord(opIndex, stored.serverVersion, stored.payload, conflictColumnsBitmap(table.columns.length, marked));
             }
         }
-        // §5.10.3: crdt columns merge (stored ⊕ incoming) — never LWW, never
-        // baseVersion-conflict (they were excluded from the checks above).
-        const mergeOutcome = await mergeCrdtColumns(table, values, storedValues, opIndex, crdtMergers);
+        // §6.2 apply: write the present non-crdt columns, merge the present
+        // crdt columns (stored ⊕ incoming, §5.10.3), leave absent columns
+        // unchanged, and increment server_version.
+        const values = [...storedValues];
+        for (let i = 0; i < table.columns.length; i++) {
+            if (!present[i])
+                continue;
+            values[i] = sparse[i] ?? null;
+        }
+        const mergeOutcome = await mergeCrdtColumns(table, values, storedValues, present, opIndex, crdtMergers);
         if ('kind' in mergeOutcome)
             return mergeOutcome;
-        if (mergeOutcome.changed)
-            mutated = true;
-        const newPayload = mutated ? encodeRow(table.columns, values) : payload;
         const newVersion = stored.serverVersion + 1;
+        const nextVersions = new Map();
+        for (let i = 0; i < table.columns.length; i++) {
+            // The primary key is immutable: its version never advances past the
+            // insert, so it never enters conflictColumns.
+            const version = present[i] && i !== table.primaryKeyIndex
+                ? newVersion
+                : effectiveVersion(i);
+            if (version > 1)
+                nextVersions.set(i, version);
+        }
+        // The stored payload is always the full-row codec (§2.4): the sparse
+        // push payload never reaches storage, segments, or COMMIT frames.
+        const newPayload = encodeRow(table.columns, values);
         // §6.6 / §5.9.6: verify referenced blobs exist before writing.
         const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
         if (blobCheck !== undefined)
             return blobCheck;
-        // §6.7: validate the merged, scope-stripped row that will persist —
-        // for a crdt column the validator sees the MERGED value (§5.10.3), the
-        // state the store holds, not the raw pushed update.
+        // §6.7: validate the merged row that will persist — for a crdt column
+        // the validator sees the MERGED value (§5.10.3), the state the store
+        // holds, not the raw pushed update.
         const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId);
         if (updateReject !== undefined)
             return updateReject;
+        const columnVersions = encodeColumnVersions(nextVersions);
         const newRow = {
             rowId: op.rowId,
             serverVersion: newVersion,
             scopes: stored.scopes,
             payload: newPayload,
+            ...(columnVersions !== undefined ? { columnVersions } : {}),
         };
         await tx.upsertRow(op.table, newRow, { opIndex });
         return {
@@ -287,9 +360,11 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
                 storedServerVersion: stored.serverVersion,
                 nextServerVersion: newVersion,
             },
+            staged: { table, op: 'upsert', rowId: op.rowId, opIndex, values, stored },
         };
     }
-    // Insert path: no stored row.
+    // Insert path: no stored row (§5.2).
+    const values = sparse.map((value) => value ?? null);
     if (op.baseVersion !== undefined && op.baseVersion !== 0) {
         // Authorize the payload first so absence is not disclosed to actors
         // without the scope; then §6.2: baseVersion ≠ 0, row absent.
@@ -300,6 +375,18 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         }
         return errorRecord(opIndex, 'sync.row_missing', 'upsert with baseVersion targets an absent row (§6.2)');
     }
+    if (op.baseVersion === undefined) {
+        // §5.2: a delete within the retention horizon beats an unversioned
+        // upsert; an explicit insert (baseVersion 0) recreates instead.
+        const tombstoneSeq = await tx.getTombstoneSeq(op.table, op.rowId);
+        if (tombstoneSeq !== undefined) {
+            return errorRecord(opIndex, 'sync.row_deleted', 'a deleted row rejects an unversioned upsert within the retention horizon (§5.2)');
+        }
+    }
+    if (presentCount < table.columns.length) {
+        // §6.3: an insert requires every column present.
+        return errorRecord(opIndex, 'sync.row_missing', 'a partial payload targets an absent row (§6.3)');
+    }
     const extracted = storedScopesForRow(table, values);
     if ('missing' in extracted) {
         // §3.4 step 2: a missing or empty scope column value ⇒ deny.
@@ -310,12 +397,12 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     }
     // §5.10.3: on insert a crdt column merges against the empty document
     // (stored = null) — normalizes the initial state through the merger.
-    const insertMerge = await mergeCrdtColumns(table, values, undefined, opIndex, crdtMergers);
+    const insertMerge = await mergeCrdtColumns(table, values, undefined, present, opIndex, crdtMergers);
     if ('kind' in insertMerge)
         return insertMerge;
-    const insertPayload = insertMerge.changed
-        ? encodeRow(table.columns, values)
-        : payload;
+    // The stored payload is the full-row codec (§2.4); every column is
+    // present on an insert.
+    const insertPayload = encodeRow(table.columns, values);
     // §6.6 / §5.9.6: verify referenced blobs exist before writing.
     const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
     if (blobCheck !== undefined)
@@ -326,6 +413,8 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, partition, actorId);
     if (insertReject !== undefined)
         return insertReject;
+    // §5.2: an explicit insert recreates — the tombstone goes with it.
+    await tx.clearTombstone(op.table, op.rowId);
     const newRow = {
         rowId: op.rowId,
         serverVersion: 1,
@@ -352,6 +441,14 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
             stored: undefined,
             nextServerVersion: 1,
         },
+        staged: {
+            table,
+            op: 'upsert',
+            rowId: op.rowId,
+            opIndex,
+            values,
+            stored: undefined,
+        },
     };
 }
 /**
@@ -456,6 +553,212 @@ async function runCommitValidator(validator, tx, schema, clientId, clientCommitI
     }
     return undefined;
 }
+/** §6.3.1 reference values are bounded to 256 encoded bytes; an over-long
+ * row id still rejects with the same code and reason, and the parent table
+ * name alone names the reference. */
+function parentReference(parentTable, parentRowId) {
+    return new TextEncoder().encode(parentRowId).length <= 256
+        ? { parent: parentTable, row: parentRowId }
+        : { parent: parentTable };
+}
+function referenceRejection(opIndex, message, details) {
+    return {
+        opIndex,
+        status: 'error',
+        code: 'sync.reference_violation',
+        message,
+        retryable: false,
+        details,
+    };
+}
+/**
+ * §6.11 declared-reference enforcement, once per commit after every client
+ * operation is staged and before whole-commit validation: a present non-null
+ * reference column must name a live parent, and a parent delete expands
+ * through `CASCADE` / `SET NULL` or rejects `restricted_delete` under
+ * `RESTRICT`. Candidate state is read through the transaction, so a commit
+ * that deletes a parent and its children together passes. Appended
+ * operations join the §6.8 staged operation list (`opIndex` ≥ the client
+ * operation count) and emit ordinary changes carrying the child's stored
+ * scopes; a rejection attributes to the originating client delete.
+ */
+async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit, validators, partition, actorId) {
+    const changes = [];
+    const operations = [];
+    const originByIndex = [];
+    for (const write of staged) {
+        if (write.op !== 'upsert' || write.values === undefined)
+            continue;
+        for (const reference of write.table.references) {
+            const value = write.values[reference.columnIndex];
+            if (value === null || value === undefined)
+                continue;
+            const parentRowId = renderScopeValue(value);
+            if (parentRowId === undefined)
+                continue;
+            if ((await tx.getRow(reference.parentTable, parentRowId)) !== undefined) {
+                continue;
+            }
+            return {
+                kind: 'terminate',
+                record: referenceRejection(write.opIndex, 'declared reference names an absent parent row (§6.11)', {
+                    reason: 'missing_parent',
+                    fieldPaths: [reference.column],
+                    references: parentReference(reference.parentTable, parentRowId),
+                }),
+            };
+        }
+    }
+    const schedule = (table, rowId, originOpIndex, scheduled, queue) => {
+        const key = `${table.name}\u0000${rowId}`;
+        if (scheduled.has(key))
+            return false;
+        scheduled.add(key);
+        queue.push({ table, rowId, originOpIndex });
+        return true;
+    };
+    const scheduled = new Set();
+    const processed = new Set();
+    const queue = [];
+    for (const write of staged) {
+        if (write.op === 'delete' && write.stored !== undefined) {
+            schedule(write.table, write.rowId, write.opIndex, scheduled, queue);
+        }
+    }
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const item = queue[cursor];
+        if (item === undefined)
+            continue;
+        const key = `${item.table.name}\u0000${item.rowId}`;
+        if (processed.has(key))
+            continue;
+        processed.add(key);
+        for (const reference of item.table.referencedBy) {
+            if (tx.scanRowsByIndex === undefined) {
+                throw new Error('storage transaction does not support declared-reference enforcement (scanRowsByIndex)');
+            }
+            const children = [];
+            let afterRowId = null;
+            for (;;) {
+                const page = await tx.scanRowsByIndex({
+                    table: reference.table,
+                    index: reference.index,
+                    values: [item.rowId],
+                    afterRowId,
+                    limit: 1_000,
+                });
+                children.push(...page);
+                if (page.length < 1_000)
+                    break;
+                afterRowId = page[page.length - 1]?.rowId ?? null;
+            }
+            if (children.length === 0)
+                continue;
+            if (reference.onDelete === 'RESTRICT') {
+                return {
+                    kind: 'terminate',
+                    record: referenceRejection(item.originOpIndex, 'delete is blocked by a declared reference with ON DELETE RESTRICT (§6.11)', {
+                        reason: 'restricted_delete',
+                        references: { child: reference.table },
+                    }),
+                };
+            }
+            const child = schema.tables.get(reference.table);
+            if (child === undefined) {
+                throw new Error(`unreachable: reference child table ${reference.table} is not compiled`);
+            }
+            for (const childRow of children) {
+                if (originByIndex.length >= cascadeLimit) {
+                    return {
+                        kind: 'terminate',
+                        record: referenceRejection(item.originOpIndex, 'declared-reference cascade exceeded the per-commit operation cap (§6.11)', { reason: 'cascade_limit' }),
+                    };
+                }
+                if (!schedule(child, childRow.rowId, item.originOpIndex, scheduled, queue)) {
+                    continue;
+                }
+                const syntheticIndex = clientOpCount + originByIndex.length;
+                const storedValues = decodeRow(child.columns, childRow.payload);
+                if (reference.onDelete === 'CASCADE') {
+                    const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, partition, actorId);
+                    if (reject !== undefined) {
+                        return { kind: 'terminate', record: reject.record };
+                    }
+                    await tx.deleteRow(child.name, childRow.rowId);
+                    changes.push({
+                        table: child.name,
+                        rowId: childRow.rowId,
+                        op: 'delete',
+                        scopes: childRow.scopes,
+                    });
+                    operations.push({
+                        opIndex: syntheticIndex,
+                        op: 'delete',
+                        table: child.name,
+                        rowId: childRow.rowId,
+                        row: undefined,
+                        stored: toValidateRow(child.columns, storedValues),
+                        storedServerVersion: childRow.serverVersion,
+                    });
+                }
+                else {
+                    const values = [...storedValues];
+                    values[reference.columnIndex] = null;
+                    const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, partition, actorId);
+                    if (reject !== undefined) {
+                        return { kind: 'terminate', record: reject.record };
+                    }
+                    const nextServerVersion = childRow.serverVersion + 1;
+                    // §6.2: the SET NULL upsert writes only the reference column, so
+                    // only that column's version moves.
+                    const storedVersions = decodeColumnVersions(childRow.columnVersions);
+                    const nextVersions = new Map();
+                    for (let i = 0; i < child.columns.length; i++) {
+                        const version = i === reference.columnIndex
+                            ? nextServerVersion
+                            : (storedVersions.get(i) ??
+                                (childRow.columnVersions === undefined
+                                    ? childRow.serverVersion
+                                    : 1));
+                        if (version > 1)
+                            nextVersions.set(i, version);
+                    }
+                    const payload = encodeRow(child.columns, values);
+                    const cascadeVersions = encodeColumnVersions(nextVersions);
+                    await tx.upsertRow(child.name, {
+                        rowId: childRow.rowId,
+                        serverVersion: nextServerVersion,
+                        scopes: childRow.scopes,
+                        payload,
+                        ...(cascadeVersions !== undefined
+                            ? { columnVersions: cascadeVersions }
+                            : {}),
+                    }, { opIndex: syntheticIndex });
+                    changes.push({
+                        table: child.name,
+                        rowId: childRow.rowId,
+                        op: 'upsert',
+                        rowVersion: nextServerVersion,
+                        scopes: childRow.scopes,
+                        payload,
+                    });
+                    operations.push({
+                        opIndex: syntheticIndex,
+                        op: 'upsert',
+                        table: child.name,
+                        rowId: childRow.rowId,
+                        row: toValidateRow(child.columns, values),
+                        stored: toValidateRow(child.columns, storedValues),
+                        storedServerVersion: childRow.serverVersion,
+                        nextServerVersion,
+                    });
+                }
+                originByIndex.push(item.originOpIndex);
+            }
+        }
+    }
+    return { kind: 'ok', changes, operations, originByIndex };
+}
 function resultFrame(clientCommitId, stored, replay) {
     const status = stored.status === 'applied' ? (replay ? 'cached' : 'applied') : 'rejected';
     return {
@@ -592,6 +895,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
         const results = [];
         const changes = [];
         const validatedOperations = [];
+        const stagedWrites = [];
         let terminated;
         const operations = await buildOperations(tx);
         for (let opIndex = 0; opIndex < operations.length; opIndex++) {
@@ -605,13 +909,38 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             }
             results.push({ opIndex, status: 'applied' });
             validatedOperations.push(outcome.operation);
+            stagedWrites.push(outcome.staged);
             if (outcome.change !== undefined)
                 changes.push(outcome.change);
         }
+        // §6.11: reference enforcement runs after every client operation is
+        // staged (so the candidate state is final for the client's own writes)
+        // and before whole-commit validation.
+        let appendedOrigin = [];
+        if (terminated === undefined) {
+            const referencePass = await enforceReferences(tx, schema, stagedWrites, operations.length, limitsOf(ctx).maxCascadeOperationsPerCommit, validators, partition, ctx.actorId);
+            if (referencePass.kind === 'terminate') {
+                terminated = referencePass.record;
+            }
+            else {
+                changes.push(...referencePass.changes);
+                validatedOperations.push(...referencePass.operations);
+                appendedOrigin = referencePass.originByIndex;
+            }
+        }
         if (terminated === undefined) {
             const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, clientCommitId, ctx.actorId, partition, validatedOperations);
             if (commitReject?.kind === 'terminate') {
-                terminated = commitReject.record;
+                // An appended §6.11 cascade operation carries a synthetic opIndex;
+                // surface the originating client operation instead.
+                const rejected = commitReject.record;
+                terminated =
+                    rejected.opIndex >= operations.length
+                        ? {
+                            ...rejected,
+                            opIndex: appendedOrigin[rejected.opIndex - operations.length] ?? 0,
+                        }
+                        : rejected;
             }
         }
         let preparedReactions = [];

package/dist/relational-rows.d.ts

@@ -3,7 +3,7 @@
  *
  * Every synced table is a REAL table in the server database — the app's
  * columns with proper type affinities, queryable with plain SQL/joins/BI —
- * plus five `_sync_*` meta columns:
+ * plus six `_sync_*` meta columns:
  *
  *   _sync_partition       TEXT      partition key (multi-partition servers
  *                                   share one database; same app PK in two
@@ -23,6 +23,10 @@
  *                                   so sync round-trips are byte-identical by
  *                                   construction. Typed columns are a
  *                                   queryable projection.
+ *   _sync_column_versions BLOB/BYTEA §2.2 per-column versions: LEB128
+ *                                   (ordinal, version) pairs for columns
+ *                                   above 1; NULL when none exceeds 1
+ *                                   (every fresh insert). Server-internal.
  *
  * PRIMARY KEY (_sync_partition, _sync_row_id).
  *
@@ -52,6 +56,15 @@ export declare const SYNC_ROW_ID_COLUMN = "_sync_row_id";
 export declare const SYNC_VERSION_COLUMN = "_sync_server_version";
 export declare const SYNC_SCOPES_COLUMN = "_sync_scopes";
 export declare const SYNC_PAYLOAD_COLUMN = "_sync_payload";
+export declare const SYNC_COLUMN_VERSIONS_COLUMN = "_sync_column_versions";
+/**
+ * §2.2 column-version storage: LEB128 `(ordinal, version)` varint pairs,
+ * ascending ordinal, for the columns whose version exceeds 1. An empty (or
+ * NULL) blob means no column exceeds 1. Server-internal: these bytes never
+ * ride the wire.
+ */
+export declare function encodeColumnVersions(versions: ReadonlyMap<number, number>): Uint8Array | undefined;
+export declare function decodeColumnVersions(blob: Uint8Array | undefined | null): Map<number, number>;
 /** SQL-standard identifier quoting (both dialects). */
 export declare function quoteIdent(name: string): string;
 /** §5.3-style type affinities, per dialect. */
@@ -67,6 +80,9 @@ export declare function createTableDdl(table: CompiledTable, dialect: Relational
 /**
  * ALTER TABLE ADD COLUMN statements for schema columns missing from
  * `existingColumns` (introspected). Added columns are nullable (header note).
+ * The `_sync_column_versions` meta column is added to pre-column-version
+ * tables too, materialized or not: it is storage-internal, nullable, and
+ * never part of the app-column migration subset.
  */
 export declare function addColumnDdl(table: CompiledTable, existingColumns: ReadonlySet<string>, dialect: RelationalDialect): string[];
 /**