@syncular/server 0.20.1 → 0.21.1

package/dist/relational-rows.js

@@ -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).
  *
@@ -49,6 +53,62 @@ export const SYNC_ROW_ID_COLUMN = '_sync_row_id';
 export const SYNC_VERSION_COLUMN = '_sync_server_version';
 export const SYNC_SCOPES_COLUMN = '_sync_scopes';
 export const SYNC_PAYLOAD_COLUMN = '_sync_payload';
+export 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 function encodeColumnVersions(versions) {
+    const bytes = [];
+    const varint = (value) => {
+        let rest = value;
+        while (rest >= 0x80) {
+            bytes.push((rest & 0x7f) | 0x80);
+            rest = Math.floor(rest / 128);
+        }
+        bytes.push(rest);
+    };
+    for (const ordinal of [...versions.keys()].sort((a, b) => a - b)) {
+        const version = versions.get(ordinal) ?? 0;
+        if (version <= 1)
+            continue;
+        varint(ordinal);
+        varint(version);
+    }
+    return bytes.length === 0 ? undefined : Uint8Array.from(bytes);
+}
+export function decodeColumnVersions(blob) {
+    const versions = new Map();
+    if (blob === undefined || blob === null)
+        return versions;
+    let offset = 0;
+    const varint = () => {
+        let value = 0;
+        let shift = 1;
+        for (;;) {
+            const byte = blob[offset];
+            if (byte === undefined) {
+                throw new Error('truncated _sync_column_versions blob');
+            }
+            offset++;
+            value += (byte & 0x7f) * shift;
+            if ((byte & 0x80) === 0)
+                return value;
+            shift *= 128;
+        }
+    };
+    while (offset < blob.length) {
+        const ordinal = varint();
+        const version = varint();
+        if (version <= 1) {
+            throw new Error('corrupt _sync_column_versions blob: version at or below 1 is never stored');
+        }
+        versions.set(ordinal, version);
+    }
+    return versions;
+}
 /** SQL-standard identifier quoting (both dialects). */
 export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
@@ -106,6 +166,7 @@ export function tableColumnNames(table) {
         SYNC_VERSION_COLUMN,
         SYNC_SCOPES_COLUMN,
         SYNC_PAYLOAD_COLUMN,
+        SYNC_COLUMN_VERSIONS_COLUMN,
     ];
 }
 /** CREATE TABLE IF NOT EXISTS for one app table. */
@@ -125,6 +186,7 @@ export function createTableDdl(table, dialect) {
         `${quoteIdent(SYNC_VERSION_COLUMN)} ${versionType} NOT NULL`,
         `${quoteIdent(SYNC_SCOPES_COLUMN)} ${scopesType} NOT NULL`,
         `${quoteIdent(SYNC_PAYLOAD_COLUMN)} ${payloadType} NOT NULL`,
+        `${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} ${payloadType}`,
         `PRIMARY KEY (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)})`,
     ];
     return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${defs.join(', ')})`;
@@ -132,11 +194,17 @@ export function createTableDdl(table, dialect) {
 /**
  * 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 function addColumnDdl(table, existingColumns, dialect) {
-    if (!table.materialize)
-        return [];
     const out = [];
+    if (!existingColumns.has(SYNC_COLUMN_VERSIONS_COLUMN)) {
+        out.push(`ALTER TABLE ${quoteIdent(table.name)} ADD COLUMN ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} ${dialect === 'postgres' ? 'BYTEA' : 'BLOB'}`);
+    }
+    if (!table.materialize)
+        return out;
     for (const column of table.columns) {
         if (existingColumns.has(column.name))
             continue;
@@ -231,7 +299,7 @@ export function toSqlValue(column, value, dialect) {
  */
 export function upsertValues(table, partition, row, dialect) {
     // A non-materialized table skips the decode entirely — the upsert is a
-    // five-column meta write (the old blob-store cost).
+    // six-column meta write (the old blob-store cost).
     const projection = table.materialize
         ? decodeRow(table.columns, row.payload)
         : undefined;
@@ -244,6 +312,7 @@ export function upsertValues(table, partition, row, dialect) {
         row.serverVersion,
         JSON.stringify(row.scopes),
         row.payload,
+        row.columnVersions ?? null,
     ];
 }
 function placeholderList(count, dialect) {
@@ -273,7 +342,7 @@ export function upsertSql(table, dialect) {
  */
 export function selectRowSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
-    return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
+    return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
 }
 /**
  * Bounded exact lookup through one declared relational index. Unlike
@@ -300,7 +369,7 @@ export function indexRowPageStatement(table, index, values, partition, afterRowI
     params.push(limit);
     const pageLimit = placeholder();
     return {
-        sql: `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${dialect === 'sqlite' ? '?' : '$1'} AND ${predicates.join(' AND ')} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>${after} ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ${pageLimit}`,
+        sql: `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${dialect === 'sqlite' ? '?' : '$1'} AND ${predicates.join(' AND ')} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>${after} ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ${pageLimit}`,
         params,
     };
 }
@@ -332,7 +401,7 @@ export function scanRowPageSql(table, valueCount, dialect) {
     const after = p(4 + valueCount);
     const limit = p(5 + valueCount);
     const joinPartition = dialect === 'sqlite' ? '?' : '$1';
-    return `SELECT c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload
+    return `SELECT c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
      FROM (SELECT DISTINCT row_id FROM sync_row_scopes
        WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values.join(',')})
          AND row_id>${after}

package/dist/schema.d.ts

@@ -20,6 +20,30 @@ export interface IndexSchema {
     readonly columns: readonly string[];
     readonly unique?: boolean;
 }
+/** One declared reference (§6.11). Absent `onDelete` means `RESTRICT`. */
+export interface ReferenceSchema {
+    readonly column: string;
+    readonly parentTable: string;
+    readonly onDelete?: ReferenceOnDelete;
+}
+export type ReferenceOnDelete = 'RESTRICT' | 'CASCADE' | 'SET NULL';
+/** A compiled outgoing reference (§6.11). */
+export interface CompiledReference {
+    readonly column: string;
+    readonly columnIndex: number;
+    readonly parentTable: string;
+    readonly onDelete: ReferenceOnDelete;
+}
+/** A compiled INCOMING reference: rows of `table` whose `column` points at a
+ * row of the table that carries this entry. `index` is the declared
+ * single-column index the server probes through `scanRowsByIndex` (§6.8). */
+export interface CompiledIncomingReference {
+    readonly table: string;
+    readonly column: string;
+    readonly columnIndex: number;
+    readonly onDelete: ReferenceOnDelete;
+    readonly index: string;
+}
 export interface TableSchema {
     readonly name: string;
     /** Columns in schema-IR declaration order (the row-codec order, §2.4). */
@@ -30,6 +54,10 @@ export interface TableSchema {
     readonly scopes: readonly ScopePatternSpec[];
     /** User indexes (optional) — created on the server's relational tables. */
     readonly indexes?: readonly IndexSchema[];
+    /** Declared references (§6.11). Optional so pre-reference schemas stay
+     * valid; the reference index over each child column is declared in
+     * `indexes` (typegen emits it). */
+    readonly references?: readonly ReferenceSchema[];
     /**
      * Server-side column materialization
      * "optional materialization"). When `true` (the usual default) the server's
@@ -66,6 +94,10 @@ export interface CompiledTable {
     readonly scopePatterns: readonly CompiledScopePattern[];
     /** User indexes (validated: unique names, existing columns). */
     readonly indexes: readonly IndexSchema[];
+    /** Outgoing declared references (§6.11), resolved to column indices. */
+    readonly references: readonly CompiledReference[];
+    /** Incoming declared references: child rows to reach on a parent delete. */
+    readonly referencedBy: readonly CompiledIncomingReference[];
     /** Resolved materialization (see `TableSchema.materialize`). */
     readonly materialize: boolean;
     readonly columnIndex: ReadonlyMap<string, number>;

package/dist/schema.js

@@ -88,6 +88,19 @@ export function compileSchema(schema) {
         const blobRefColumnIndices = [];
         const crdtColumns = [];
         const encryptedColumnIndices = [];
+        const references = [];
+        for (const reference of table.references ?? []) {
+            const index = columnIndex.get(reference.column);
+            if (index === undefined) {
+                throw new Error(`table ${table.name}: reference column ${JSON.stringify(reference.column)} is not a column`);
+            }
+            references.push({
+                column: reference.column,
+                columnIndex: index,
+                parentTable: reference.parentTable,
+                onDelete: reference.onDelete ?? 'RESTRICT',
+            });
+        }
         table.columns.forEach((column, index) => {
             if (column.type === 'blob_ref')
                 blobRefColumnIndices.push(index);
@@ -118,6 +131,8 @@ export function compileSchema(schema) {
             primaryKeyIndex,
             scopePatterns,
             indexes,
+            references,
+            referencedBy: [],
             materialize,
             columnIndex,
             declaredVariables: variables,
@@ -126,6 +141,46 @@ export function compileSchema(schema) {
             encryptedColumnIndices,
         });
     }
+    // §6.11: resolve incoming references and enforce the declaration rules the
+    // generator enforces too, so a hand-written server schema fails loud.
+    for (const child of tables.values()) {
+        for (const reference of child.references) {
+            const parent = tables.get(reference.parentTable);
+            if (parent === undefined) {
+                throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} names unknown table ${JSON.stringify(reference.parentTable)}`);
+            }
+            const childColumn = child.columns[reference.columnIndex];
+            const parentKey = parent.columns[parent.primaryKeyIndex];
+            if (childColumn === undefined || parentKey === undefined) {
+                throw new Error(`unreachable: ${child.name}.${reference.column} or a missing primary key on ${parent.name}`);
+            }
+            if (childColumn.type !== parentKey.type) {
+                throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} has type ${JSON.stringify(childColumn.type)} but ${parent.name}.${parentKey.name} has type ${JSON.stringify(parentKey.type)} — the types must match (§6.11)`);
+            }
+            if (reference.onDelete === 'SET NULL' && !childColumn.nullable) {
+                throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} is not nullable but declares ON DELETE SET NULL (§6.11)`);
+            }
+            const patterns = (compiled) => compiled.scopePatterns
+                .map((pattern) => `${pattern.prefix}:{${pattern.variable}}`)
+                .sort()
+                .join('\u0000');
+            if (patterns(child) !== patterns(parent)) {
+                throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} targets ${parent.name}, whose scope patterns differ — a cascade MUST NOT cross an authorization boundary (§6.11)`);
+            }
+            const index = child.indexes.find((candidate) => candidate.columns.length === 1 &&
+                candidate.columns[0] === reference.column);
+            if (index === undefined) {
+                throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} needs a declared single-column index so the server reaches children through scanRowsByIndex (§6.11)`);
+            }
+            parent.referencedBy.push({
+                table: child.name,
+                column: reference.column,
+                columnIndex: reference.columnIndex,
+                onDelete: reference.onDelete,
+                index: index.name,
+            });
+        }
+    }
     const compiled = {
         version: schema.version,
         tables,

package/dist/seed.js

@@ -9,7 +9,7 @@
  * Idempotent by construction (§2.3): the commit id is stable, so re-running
  * the seed replays the cached push result and writes nothing twice.
  */
-import { decodeMessage, encodeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
+import { decodeMessage, encodeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
 import { SyncError } from './errors.js';
 import { composeEvents } from './events-ring.js';
 import { handleSyncRequest } from './handler.js';
@@ -102,7 +102,7 @@ export async function seedMutations(config, target, mutations) {
             table: mutation.table,
             rowId,
             op: 'upsert',
-            payload: encodeRow(table.columns, values),
+            payload: encodeSparseRow(table.columns, pkIndex, values),
         };
     });
     const requestContext = {

package/dist/sqlite-dialect.d.ts

@@ -30,7 +30,7 @@ import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './
  * the Postgres storage documents (§3.1, performance-by-
  * construction).
  */
-export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER 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 INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER 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 INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER 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 INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\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 INTEGER 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 TEXT 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 TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\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 INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER 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 SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER 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 INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER 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 INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER 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 INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\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 INTEGER 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 TEXT 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 TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\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 INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER 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);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export declare function sqliteDdlStatements(): string[];
 /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
@@ -44,6 +44,7 @@ export interface SqliteRowRecord {
     server_version: number;
     scopes: string;
     payload: Uint8Array;
+    column_versions: Uint8Array | null;
 }
 export interface SqliteChangeRecord {
     tbl: string;

package/dist/sqlite-dialect.js

@@ -89,6 +89,11 @@ CREATE TABLE IF NOT EXISTS sync_blob_refs(
 );
 CREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob
   ON sync_blob_refs(partition, blob_id);
+CREATE TABLE IF NOT EXISTS sync_tombstones(
+  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
+  commit_seq INTEGER NOT NULL,
+  PRIMARY KEY(partition, tbl, row_id)
+);
 `;
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export function sqliteDdlStatements() {
@@ -135,6 +140,7 @@ export function serializePushResult(result) {
                     message: record.message,
                     serverVersion: record.serverVersion,
                     serverRow: bytesToBase64(record.serverRow),
+                    conflictColumns: bytesToBase64(record.conflictColumns),
                 };
             }
             if (record.status === 'error') {
@@ -162,6 +168,7 @@ export function deserializePushResult(text) {
                 message: record.message ?? '',
                 serverVersion: record.serverVersion ?? 0,
                 serverRow: base64ToBytes(record.serverRow ?? ''),
+                conflictColumns: base64ToBytes(record.conflictColumns ?? ''),
             };
         }
         if (record.status === 'error') {
@@ -204,6 +211,9 @@ export function toStoredRow(record) {
         serverVersion: record.server_version,
         scopes: JSON.parse(record.scopes),
         payload: asUint8Array(record.payload),
+        ...(record.column_versions !== null
+            ? { columnVersions: asUint8Array(record.column_versions) }
+            : {}),
     };
 }
 export function toStoredChange(record) {

package/dist/sqlite-storage.js

@@ -62,6 +62,19 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.getRow(this.#partition, table, rowId);
     }
+    async getTombstoneSeq(table, rowId) {
+        this.#assertOpen();
+        const row = this.#storage.db
+            .query('SELECT commit_seq FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?')
+            .get(this.#partition, table, rowId);
+        return row?.commit_seq;
+    }
+    async clearTombstone(table, rowId) {
+        this.#assertOpen();
+        this.#storage.db
+            .query('DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?')
+            .run(this.#partition, table, rowId);
+    }
     getPushResult(clientId, clientCommitId) {
         this.#assertOpen();
         // One shared SQLite connection: this read runs inside this
@@ -136,6 +149,12 @@ class SqliteTransaction {
         db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms) VALUES (?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs);
         commit.changes.forEach((change, idx) => {
             db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
+            if (change.op === 'delete') {
+                // §5 delete precedence: every applied delete leaves a tombstone,
+                // pruned with the commit log (§4.6).
+                db.query(`INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
+           ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`).run(p, change.table, change.rowId, commitSeq);
+            }
             for (const [variable, value] of Object.entries(change.scopes)) {
                 db.query('INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)').run(p, change.table, variable, value, commitSeq);
             }
@@ -525,6 +544,10 @@ export class SqliteServerStorage {
                 this.db
                     .query('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
                     .run(partition, horizonSeq);
+                // §4.6: tombstones prune in the same pass as the commit log.
+                this.db
+                    .query('DELETE FROM sync_tombstones WHERE partition=? AND commit_seq<=?')
+                    .run(partition, horizonSeq);
                 this.db.exec('COMMIT');
                 return {
                     previousHorizonSeq,

package/dist/storage.d.ts

@@ -37,6 +37,13 @@ export interface StoredRow {
     readonly scopes: Record<string, string>;
     /** Row-codec payload (§2.4) for the server's schema version. */
     readonly payload: Uint8Array;
+    /**
+     * §2.2 per-column versions: the `_sync_column_versions` blob (LEB128
+     * (ordinal, version) pairs for columns above 1). Absent when no column
+     * exceeds 1, and for rows written before column versions existed — a row
+     * without the blob carries every column at `serverVersion`.
+     */
+    readonly columnVersions?: Uint8Array;
 }
 export interface NewChange {
     readonly table: string;
@@ -271,6 +278,20 @@ export interface AuthoritativeQueryResult {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * §5 delete-precedence tombstone read: the `commit_seq` of the newest
+     * applied delete of this row still within the pruning horizon, or
+     * `undefined` when no tombstone exists. Consulted only when an upsert's
+     * stored row is absent. Required: in-tree adapters implement it on the
+     * transaction's own connection with read-your-own-writes semantics.
+     */
+    getTombstoneSeq(table: string, rowId: string): Promise<number | undefined>;
+    /**
+     * Remove the row's tombstone because the row was recreated in this
+     * transaction (§5: an explicit insert recreates). Called on every insert
+     * over an absent row; a no-op when no tombstone exists.
+     */
+    clearTombstone(table: string, rowId: string): Promise<void>;
     /**
      * Optional transaction-scoped idempotency lookup (§2.3) with the same
      * semantics as `ServerStorage.getPushResult`, including the

package/package.json

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

package/src/context.ts

@@ -78,11 +78,14 @@ export interface ServerLimits {
   readonly maxOperationsPerRequest: number;
   /** Inline rows segments up to this size (§5.7 SHOULD: 256 KiB). */
   readonly inlineSegmentMaxBytes: number;
+  /** §6.11 declared-reference cascade cap per commit (reference default). */
+  readonly maxCascadeOperationsPerCommit: number;
 }
 
 export const DEFAULT_LIMITS: ServerLimits = {
   maxOperationsPerRequest: 500,
   inlineSegmentMaxBytes: 256 * 1024,
+  maxCascadeOperationsPerCommit: 1_000,
 };
 
 /** Receives applied commits for realtime fanout (§8.2). */

package/src/d1-storage.ts

@@ -271,6 +271,31 @@ class D1Transaction implements StorageTransaction {
     return record === null ? undefined : toStoredRow(record);
   }
 
+  async getTombstoneSeq(
+    table: string,
+    rowId: string,
+  ): Promise<number | undefined> {
+    this.#assertOpen();
+    // Persisted read, no #pending overlay: a delete buffered by this commit
+    // records its tombstone at appendCommit, matching the SQLite/Postgres
+    // adapters where the tombstone insert also runs at commit append.
+    const record = await this.#db
+      .prepare(
+        'SELECT commit_seq FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
+      )
+      .bind(this.#partition, table, rowId)
+      .first<{ commit_seq: number }>();
+    return record?.commit_seq;
+  }
+
+  async clearTombstone(table: string, rowId: string): Promise<void> {
+    this.#assertOpen();
+    this.#buffer_(
+      'DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
+      [this.#partition, table, rowId],
+    );
+  }
+
   async getPushResult(
     clientId: string,
     clientCommitId: string,
@@ -637,6 +662,15 @@ class D1Transaction implements StorageTransaction {
           change.payload ?? null,
         ],
       );
+      if (change.op === 'delete') {
+        // §5 delete precedence: every applied delete leaves a tombstone,
+        // pruned with the commit log (§4.6).
+        this.#buffer_(
+          `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
+           ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`,
+          [p, change.table, change.rowId, commitSeq],
+        );
+      }
       for (const [variable, value] of Object.entries(change.scopes)) {
         this.#buffer_(
           'INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)',
@@ -1501,7 +1535,12 @@ export class D1ServerStorage implements ServerStorage {
           `SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`,
         )
         .bind(partition, partition, partition),
-      ...['sync_commits', 'sync_changes', 'sync_change_scopes'].map((table) =>
+      ...[
+        'sync_commits',
+        'sync_changes',
+        'sync_change_scopes',
+        'sync_tombstones',
+      ].map((table) =>
         this.#db
           .prepare(
             `DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`,

package/src/errors.ts

@@ -119,6 +119,22 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
     recommendedAction: 'forceResync',
     httpStatus: 404,
   },
+  // §5 delete precedence: an unversioned upsert lost to a delete inside the
+  // tombstone horizon. The client drops the operation on rebuild.
+  'sync.row_deleted': {
+    category: 'not-found',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 404,
+  },
+  // §6.11 declared references: absent parent, RESTRICT delete with live
+  // children, or the cascade cap. A push operation-result error only.
+  'sync.reference_violation': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
   'sync.version_conflict': {
     category: 'conflict',
     retryable: false,
@@ -199,12 +215,6 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
     recommendedAction: 'upgradeClient',
     httpStatus: 400,
   },
-  'sync.client_wire_unsupported': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'upgradeClient',
-    httpStatus: 400,
-  },
   'sync.websocket_connection_limit': {
     category: 'rate-limited',
     retryable: true,