@syncular/core 0.20.1 → 0.21.1

package/dist/constants.d.ts

@@ -1,8 +1,10 @@
 /** Protocol constants (SPEC.md §1.2, §9 are normative). */
 /** Latest SSP2 envelope wire version emitted by current clients. */
-export declare const PROTOCOL_WIRE_VERSION = 2;
-/** Oldest SSP2 envelope wire version accepted during the epoch rollout. */
-export declare const MINIMUM_PROTOCOL_WIRE_VERSION = 1;
+export declare const PROTOCOL_WIRE_VERSION = 3;
+/** Oldest SSP2 envelope wire version accepted. Wire version 3 changed the
+ * push payload to the sparse row codec (§2.4) and the conflict record shape
+ * (§6.3); versions 1 and 2 are rejected as unknown (§9). */
+export declare const MINIMUM_PROTOCOL_WIRE_VERSION = 3;
 /** Wire versions implemented by the reference codec, oldest first. */
 export declare const SUPPORTED_PROTOCOL_WIRE_VERSIONS: readonly number[];
 /** Whether the reference codec implements this exact wire version. */

package/dist/constants.js

@@ -1,8 +1,10 @@
 /** Protocol constants (SPEC.md §1.2, §9 are normative). */
 /** Latest SSP2 envelope wire version emitted by current clients. */
-export const PROTOCOL_WIRE_VERSION = 2;
-/** Oldest SSP2 envelope wire version accepted during the epoch rollout. */
-export const MINIMUM_PROTOCOL_WIRE_VERSION = 1;
+export const PROTOCOL_WIRE_VERSION = 3;
+/** Oldest SSP2 envelope wire version accepted. Wire version 3 changed the
+ * push payload to the sparse row codec (§2.4) and the conflict record shape
+ * (§6.3); versions 1 and 2 are rejected as unknown (§9). */
+export const MINIMUM_PROTOCOL_WIRE_VERSION = 3;
 /** Wire versions implemented by the reference codec, oldest first. */
 export const SUPPORTED_PROTOCOL_WIRE_VERSIONS = Object.freeze(Array.from({
     length: PROTOCOL_WIRE_VERSION - MINIMUM_PROTOCOL_WIRE_VERSION + 1,

package/dist/crypto.d.ts

@@ -19,6 +19,18 @@ export declare class DecryptError extends Error {
     readonly code = "client.decrypt_failed";
     readonly retryable = false;
 }
+/**
+ * Client-local encrypt failure (SPEC.md §5.11, §10.3). Never on the wire.
+ * Raised at the encode-at-send seam when the key id cannot be resolved
+ * from the present columns or the stored local row, or the selected key
+ * is unknown. Not retryable unmodified. Distinct from {@link DecryptError},
+ * which is apply-seam only.
+ */
+export declare class EncryptError extends Error {
+    readonly name = "EncryptError";
+    readonly code = "client.encrypt_failed";
+    readonly retryable = false;
+}
 /**
  * Injectable nonce source (SPEC.md §5.11 nonce discipline). Production uses
  * {@link secureRandomNonce}; crypto golden vectors inject a fixed nonce. A

package/dist/crypto.js

@@ -30,6 +30,18 @@ export class DecryptError extends Error {
     code = 'client.decrypt_failed';
     retryable = false;
 }
+/**
+ * Client-local encrypt failure (SPEC.md §5.11, §10.3). Never on the wire.
+ * Raised at the encode-at-send seam when the key id cannot be resolved
+ * from the present columns or the stored local row, or the selected key
+ * is unknown. Not retryable unmodified. Distinct from {@link DecryptError},
+ * which is apply-seam only.
+ */
+export class EncryptError extends Error {
+    name = 'EncryptError';
+    code = 'client.encrypt_failed';
+    retryable = false;
+}
 export function secureRandomNonce() {
     const nonce = new Uint8Array(NONCE_LENGTH);
     crypto.getRandomValues(nonce);

package/dist/message.d.ts

@@ -71,6 +71,13 @@ export type PushOperationResult = {
     message: string;
     serverVersion: number;
     serverRow: Uint8Array;
+    /**
+     * §6.3 (wire version 3): presence-bitmap layout over the row's columns,
+     * marking the present columns whose `column_version` exceeded the
+     * operation's `baseVersion`. A `baseVersion = 0` lost-insert conflict
+     * marks every present non-crdt column.
+     */
+    conflictColumns: Uint8Array;
 } | {
     opIndex: number;
     status: 'error';

package/dist/message.js

@@ -185,6 +185,7 @@ function decodePushResult(r) {
                 message: r.str(),
                 serverVersion: r.i64(),
                 serverRow: r.bytes(),
+                conflictColumns: r.bytes(),
             });
         }
         else if (recordStatus === 3) {
@@ -709,6 +710,7 @@ function encodeFrame(frame, wireVersion) {
                     w.str(result.message);
                     w.i64(result.serverVersion);
                     w.bytes(result.serverRow);
+                    w.bytes(result.conflictColumns);
                 }
                 else {
                     w.u8(3);

package/dist/render.d.ts

@@ -8,6 +8,7 @@
  * fields embedded as parsed JSON.
  */
 import type { SyncMessage } from './message.js';
+import type { RowColumn, SparseRowValue } from './row-codec.js';
 import type { RowsSegment } from './segment.js';
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -20,3 +21,9 @@ export declare function renderMessage(bytes: Uint8Array): JsonValue;
 export declare function renderRowsSegmentValue(segment: RowsSegment): JsonValue;
 /** `render(bytes) → json` for standalone SSG2 rows segments (§11 rule 8). */
 export declare function renderRowsSegment(bytes: Uint8Array): JsonValue;
+/**
+ * Render a decoded sparse row (RFC §6.1, §11 rule 11): the column table plus
+ * `values` keyed by column name, carrying only the present columns, so an
+ * absent column has no key and a present NULL renders as JSON `null`.
+ */
+export declare function renderSparseRowValue(columns: readonly RowColumn[], values: readonly SparseRowValue[]): JsonValue;

package/dist/render.js

@@ -67,6 +67,7 @@ function renderResult(result) {
             message: result.message,
             serverVersion: result.serverVersion,
             serverRow: bytesToBase64(result.serverRow),
+            conflictColumns: bytesToBase64(result.conflictColumns),
         };
     }
     return {
@@ -274,17 +275,20 @@ function renderRowValue(column, value) {
     }
     return value;
 }
+function renderColumnTable(columns) {
+    return columns.map((column) => ({
+        name: column.name,
+        type: column.type,
+        nullable: column.nullable,
+    }));
+}
 export function renderRowsSegmentValue(segment) {
     return {
         magic: 'SSG2',
         formatVersion: ROWS_SEGMENT_FORMAT_VERSION,
         table: segment.table,
         schemaVersion: segment.schemaVersion,
-        columns: segment.columns.map((column) => ({
-            name: column.name,
-            type: column.type,
-            nullable: column.nullable,
-        })),
+        columns: renderColumnTable(segment.columns),
         blocks: segment.blocks.map((block) => block.map((row) => ({
             serverVersion: row.serverVersion,
             values: Object.fromEntries(segment.columns.map((column, i) => [
@@ -298,3 +302,22 @@ export function renderRowsSegmentValue(segment) {
 export function renderRowsSegment(bytes) {
     return renderRowsSegmentValue(decodeRowsSegment(bytes));
 }
+/**
+ * Render a decoded sparse row (RFC §6.1, §11 rule 11): the column table plus
+ * `values` keyed by column name, carrying only the present columns, so an
+ * absent column has no key and a present NULL renders as JSON `null`.
+ */
+export function renderSparseRowValue(columns, values) {
+    const present = [];
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        const value = values[i];
+        if (column === undefined || value === undefined)
+            continue;
+        present.push([column.name, renderRowValue(column, value)]);
+    }
+    return {
+        columns: renderColumnTable(columns),
+        values: Object.fromEntries(present),
+    };
+}

package/dist/row-codec.d.ts

@@ -31,6 +31,27 @@ export interface RowColumn {
 export type RowValue = string | number | boolean | Uint8Array | null;
 export declare function columnTypeTag(type: ColumnType): number;
 export declare function columnTypeFromTag(tag: number): ColumnType;
+/**
+ * A sparse-row slot (RFC §6.1): `undefined` when the column is absent from
+ * the payload (an apply leaves the stored value untouched), `null` when the
+ * column is present and NULL.
+ */
+export type SparseRowValue = RowValue | undefined;
+/**
+ * Encode one standalone sparse row (RFC §6.1, SPEC.md §2.4).
+ *
+ * `primaryKeyIndex` is the row's primary-key column; a payload without it is
+ * encoder misuse and throws, like a NULL in a non-nullable column.
+ */
+export declare function encodeSparseRow(columns: readonly RowColumn[], primaryKeyIndex: number, values: readonly SparseRowValue[]): Uint8Array;
+/**
+ * Decode one standalone sparse row; the bytes must contain exactly one row.
+ *
+ * Decode checks, in order (each a decode error, RFC §6.1): a set presence
+ * padding bit, an absent primary-key column, a set null-bitmap padding bit
+ * (a null for an absent column), a null bit for a non-nullable column.
+ */
+export declare function decodeSparseRow(columns: readonly RowColumn[], primaryKeyIndex: number, bytes: Uint8Array): SparseRowValue[];
 export declare function writeRow(writer: ByteWriter, columns: readonly RowColumn[], values: readonly RowValue[]): void;
 export declare function readRow(reader: ByteReader, columns: readonly RowColumn[]): RowValue[];
 /** Encode one standalone row (e.g. a push payload or conflict serverRow). */

package/dist/row-codec.js

@@ -4,8 +4,13 @@
  * A row is a null bitmap of ceil(columnCount / 8) bytes (bit i set =
  * column i is NULL; LSB-first within each byte, byte i/8), followed by the
  * non-null values encoded positionally in schema-IR declaration order.
- * Used for `COMMIT` change payloads, rows-segment row data, push operation
- * payloads, and conflict `serverRow` values.
+ * Used for `COMMIT` change payloads, rows-segment row data, and conflict
+ * `serverRow` values; push operation payloads use the sparse row codec
+ * (`encodeSparseRow` / `decodeSparseRow`) instead.
+ *
+ * A sparse row (RFC §6.1) is the column subset a push operation writes: a
+ * presence bitmap over all columns, a null bitmap over the present columns,
+ * then the non-null present values. Absent columns keep their stored value.
  */
 import { parseBlobRef } from './blob-ref.js';
 import { ByteReader, ByteWriter } from './bytes.js';
@@ -109,6 +114,120 @@ function readValue(reader, column) {
             return reader.bytes();
     }
 }
+/** One bit of a bitmap: LSB-first within byte `index / 8`. */
+function bitmapBit(bitmap, index) {
+    return (((bitmap[index >> 3] ?? 0) >> (index & 7)) & 1) !== 0;
+}
+/**
+ * Encode one standalone sparse row (RFC §6.1, SPEC.md §2.4).
+ *
+ * `primaryKeyIndex` is the row's primary-key column; a payload without it is
+ * encoder misuse and throws, like a NULL in a non-nullable column.
+ */
+export function encodeSparseRow(columns, primaryKeyIndex, values) {
+    if (values.length !== columns.length) {
+        throw new Error(`row value count ${values.length} does not match column count ${columns.length}`);
+    }
+    const presence = new Uint8Array(Math.ceil(columns.length / 8));
+    let presentCount = 0;
+    for (let i = 0; i < columns.length; i++) {
+        if (values[i] === undefined)
+            continue;
+        presence[i >> 3] = (presence[i >> 3] ?? 0) | (1 << (i & 7));
+        presentCount++;
+    }
+    const primaryKey = columns[primaryKeyIndex];
+    if (primaryKey === undefined) {
+        throw new Error(`primary-key column index ${primaryKeyIndex} is outside the column table`);
+    }
+    if (!bitmapBit(presence, primaryKeyIndex)) {
+        throw new Error(`sparse row is missing the primary-key column ${primaryKey.name}`);
+    }
+    const nulls = new Uint8Array(Math.ceil(presentCount / 8));
+    let present = 0;
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        const value = values[i];
+        if (column === undefined || value === undefined)
+            continue;
+        if (value === null) {
+            if (!column.nullable) {
+                throw new Error(`column ${column.name} is not nullable`);
+            }
+            nulls[present >> 3] = (nulls[present >> 3] ?? 0) | (1 << (present & 7));
+        }
+        present++;
+    }
+    const writer = new ByteWriter();
+    writer.raw(presence);
+    writer.raw(nulls);
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        const value = values[i];
+        if (column === undefined || value === undefined || value === null) {
+            continue;
+        }
+        writeValue(writer, column, value);
+    }
+    return writer.finish();
+}
+/**
+ * Decode one standalone sparse row; the bytes must contain exactly one row.
+ *
+ * Decode checks, in order (each a decode error, RFC §6.1): a set presence
+ * padding bit, an absent primary-key column, a set null-bitmap padding bit
+ * (a null for an absent column), a null bit for a non-nullable column.
+ */
+export function decodeSparseRow(columns, primaryKeyIndex, bytes) {
+    const reader = new ByteReader(bytes);
+    const presenceLength = Math.ceil(columns.length / 8);
+    const presence = reader.raw(presenceLength);
+    for (let bit = columns.length; bit < presenceLength * 8; bit++) {
+        if (bitmapBit(presence, bit)) {
+            throw new DecodeError('sync.invalid_request', 'sparse row presence bitmap has a set padding bit (non-canonical encoding)');
+        }
+    }
+    const primaryKey = columns[primaryKeyIndex];
+    if (primaryKey === undefined) {
+        throw new DecodeError('sync.invalid_request', `primary-key column index ${primaryKeyIndex} is outside the column table`);
+    }
+    if (!bitmapBit(presence, primaryKeyIndex)) {
+        throw new DecodeError('sync.invalid_request', `sparse row is missing the primary-key column ${primaryKey.name}`);
+    }
+    let presentCount = 0;
+    for (let i = 0; i < columns.length; i++) {
+        if (bitmapBit(presence, i))
+            presentCount++;
+    }
+    const nullLength = Math.ceil(presentCount / 8);
+    const nulls = reader.raw(nullLength);
+    for (let bit = presentCount; bit < nullLength * 8; bit++) {
+        if (bitmapBit(nulls, bit)) {
+            throw new DecodeError('sync.invalid_request', 'sparse row null bitmap sets a null bit for an absent column');
+        }
+    }
+    const values = [];
+    let present = 0;
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        if (column === undefined || !bitmapBit(presence, i)) {
+            values.push(undefined);
+            continue;
+        }
+        const isNull = bitmapBit(nulls, present);
+        present++;
+        if (!isNull) {
+            values.push(readValue(reader, column));
+            continue;
+        }
+        if (!column.nullable) {
+            throw new DecodeError('sync.invalid_request', `null bit set for non-nullable column ${column.name}`);
+        }
+        values.push(null);
+    }
+    reader.expectFullyConsumed('sparse row payload');
+    return values;
+}
 export function writeRow(writer, columns, values) {
     if (values.length !== columns.length) {
         throw new Error(`row value count ${values.length} does not match column count ${columns.length}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",

package/src/constants.ts

@@ -1,10 +1,12 @@
 /** Protocol constants (SPEC.md §1.2, §9 are normative). */
 
 /** Latest SSP2 envelope wire version emitted by current clients. */
-export const PROTOCOL_WIRE_VERSION = 2;
+export const PROTOCOL_WIRE_VERSION = 3;
 
-/** Oldest SSP2 envelope wire version accepted during the epoch rollout. */
-export const MINIMUM_PROTOCOL_WIRE_VERSION = 1;
+/** Oldest SSP2 envelope wire version accepted. Wire version 3 changed the
+ * push payload to the sparse row codec (§2.4) and the conflict record shape
+ * (§6.3); versions 1 and 2 are rejected as unknown (§9). */
+export const MINIMUM_PROTOCOL_WIRE_VERSION = 3;
 
 /** Wire versions implemented by the reference codec, oldest first. */
 export const SUPPORTED_PROTOCOL_WIRE_VERSIONS: readonly number[] =

package/src/crypto.ts

@@ -48,6 +48,19 @@ export class DecryptError extends Error {
   readonly retryable = false;
 }
 
+/**
+ * Client-local encrypt failure (SPEC.md §5.11, §10.3). Never on the wire.
+ * Raised at the encode-at-send seam when the key id cannot be resolved
+ * from the present columns or the stored local row, or the selected key
+ * is unknown. Not retryable unmodified. Distinct from {@link DecryptError},
+ * which is apply-seam only.
+ */
+export class EncryptError extends Error {
+  override readonly name = 'EncryptError';
+  readonly code = 'client.encrypt_failed';
+  readonly retryable = false;
+}
+
 /**
  * Injectable nonce source (SPEC.md §5.11 nonce discipline). Production uses
  * {@link secureRandomNonce}; crypto golden vectors inject a fixed nonce. A

package/src/message.ts

@@ -122,6 +122,13 @@ export type PushOperationResult =
       message: string;
       serverVersion: number;
       serverRow: Uint8Array;
+      /**
+       * §6.3 (wire version 3): presence-bitmap layout over the row's columns,
+       * marking the present columns whose `column_version` exceeded the
+       * operation's `baseVersion`. A `baseVersion = 0` lost-insert conflict
+       * marks every present non-crdt column.
+       */
+      conflictColumns: Uint8Array;
     }
   | {
       opIndex: number;
@@ -422,6 +429,7 @@ function decodePushResult(r: ByteReader): PushResultFrame {
         message: r.str(),
         serverVersion: r.i64(),
         serverRow: r.bytes(),
+        conflictColumns: r.bytes(),
       });
     } else if (recordStatus === 3) {
       results.push({
@@ -971,6 +979,7 @@ function encodeFrame(
           w.str(result.message);
           w.i64(result.serverVersion);
           w.bytes(result.serverRow);
+          w.bytes(result.conflictColumns);
         } else {
           w.u8(3);
           w.str(result.code);

package/src/render.ts

@@ -16,7 +16,7 @@ import type {
   SyncMessage,
 } from './message';
 import { decodeMessage } from './message';
-import type { RowColumn, RowValue } from './row-codec';
+import type { RowColumn, RowValue, SparseRowValue } from './row-codec';
 import type { RowsSegment } from './segment';
 import { decodeRowsSegment, ROWS_SEGMENT_FORMAT_VERSION } from './segment';
 
@@ -106,6 +106,7 @@ function renderResult(result: PushOperationResult): JsonValue {
       message: result.message,
       serverVersion: result.serverVersion,
       serverRow: bytesToBase64(result.serverRow),
+      conflictColumns: bytesToBase64(result.conflictColumns),
     };
   }
   return {
@@ -321,17 +322,21 @@ function renderRowValue(column: RowColumn, value: RowValue): JsonValue {
   return value;
 }
 
+function renderColumnTable(columns: readonly RowColumn[]): JsonValue {
+  return columns.map((column) => ({
+    name: column.name,
+    type: column.type,
+    nullable: column.nullable,
+  }));
+}
+
 export function renderRowsSegmentValue(segment: RowsSegment): JsonValue {
   return {
     magic: 'SSG2',
     formatVersion: ROWS_SEGMENT_FORMAT_VERSION,
     table: segment.table,
     schemaVersion: segment.schemaVersion,
-    columns: segment.columns.map((column) => ({
-      name: column.name,
-      type: column.type,
-      nullable: column.nullable,
-    })),
+    columns: renderColumnTable(segment.columns),
     blocks: segment.blocks.map((block) =>
       block.map((row) => ({
         serverVersion: row.serverVersion,
@@ -350,3 +355,25 @@ export function renderRowsSegmentValue(segment: RowsSegment): JsonValue {
 export function renderRowsSegment(bytes: Uint8Array): JsonValue {
   return renderRowsSegmentValue(decodeRowsSegment(bytes));
 }
+
+/**
+ * Render a decoded sparse row (RFC §6.1, §11 rule 11): the column table plus
+ * `values` keyed by column name, carrying only the present columns, so an
+ * absent column has no key and a present NULL renders as JSON `null`.
+ */
+export function renderSparseRowValue(
+  columns: readonly RowColumn[],
+  values: readonly SparseRowValue[],
+): JsonValue {
+  const present: Array<[string, JsonValue]> = [];
+  for (let i = 0; i < columns.length; i++) {
+    const column = columns[i];
+    const value = values[i];
+    if (column === undefined || value === undefined) continue;
+    present.push([column.name, renderRowValue(column, value)]);
+  }
+  return {
+    columns: renderColumnTable(columns),
+    values: Object.fromEntries(present),
+  };
+}

package/src/row-codec.ts

@@ -4,8 +4,13 @@
  * A row is a null bitmap of ceil(columnCount / 8) bytes (bit i set =
  * column i is NULL; LSB-first within each byte, byte i/8), followed by the
  * non-null values encoded positionally in schema-IR declaration order.
- * Used for `COMMIT` change payloads, rows-segment row data, push operation
- * payloads, and conflict `serverRow` values.
+ * Used for `COMMIT` change payloads, rows-segment row data, and conflict
+ * `serverRow` values; push operation payloads use the sparse row codec
+ * (`encodeSparseRow` / `decodeSparseRow`) instead.
+ *
+ * A sparse row (RFC §6.1) is the column subset a push operation writes: a
+ * presence bitmap over all columns, a null bitmap over the present columns,
+ * then the non-null present values. Absent columns keep their stored value.
  */
 import { parseBlobRef } from './blob-ref';
 import { ByteReader, ByteWriter } from './bytes';
@@ -178,6 +183,156 @@ function readValue(reader: ByteReader, column: RowColumn): RowValue {
   }
 }
 
+/** One bit of a bitmap: LSB-first within byte `index / 8`. */
+function bitmapBit(bitmap: Uint8Array, index: number): boolean {
+  return (((bitmap[index >> 3] ?? 0) >> (index & 7)) & 1) !== 0;
+}
+
+/**
+ * A sparse-row slot (RFC §6.1): `undefined` when the column is absent from
+ * the payload (an apply leaves the stored value untouched), `null` when the
+ * column is present and NULL.
+ */
+export type SparseRowValue = RowValue | undefined;
+
+/**
+ * Encode one standalone sparse row (RFC §6.1, SPEC.md §2.4).
+ *
+ * `primaryKeyIndex` is the row's primary-key column; a payload without it is
+ * encoder misuse and throws, like a NULL in a non-nullable column.
+ */
+export function encodeSparseRow(
+  columns: readonly RowColumn[],
+  primaryKeyIndex: number,
+  values: readonly SparseRowValue[],
+): Uint8Array {
+  if (values.length !== columns.length) {
+    throw new Error(
+      `row value count ${values.length} does not match column count ${columns.length}`,
+    );
+  }
+  const presence = new Uint8Array(Math.ceil(columns.length / 8));
+  let presentCount = 0;
+  for (let i = 0; i < columns.length; i++) {
+    if (values[i] === undefined) continue;
+    presence[i >> 3] = (presence[i >> 3] ?? 0) | (1 << (i & 7));
+    presentCount++;
+  }
+  const primaryKey = columns[primaryKeyIndex];
+  if (primaryKey === undefined) {
+    throw new Error(
+      `primary-key column index ${primaryKeyIndex} is outside the column table`,
+    );
+  }
+  if (!bitmapBit(presence, primaryKeyIndex)) {
+    throw new Error(
+      `sparse row is missing the primary-key column ${primaryKey.name}`,
+    );
+  }
+  const nulls = new Uint8Array(Math.ceil(presentCount / 8));
+  let present = 0;
+  for (let i = 0; i < columns.length; i++) {
+    const column = columns[i];
+    const value = values[i];
+    if (column === undefined || value === undefined) continue;
+    if (value === null) {
+      if (!column.nullable) {
+        throw new Error(`column ${column.name} is not nullable`);
+      }
+      nulls[present >> 3] = (nulls[present >> 3] ?? 0) | (1 << (present & 7));
+    }
+    present++;
+  }
+  const writer = new ByteWriter();
+  writer.raw(presence);
+  writer.raw(nulls);
+  for (let i = 0; i < columns.length; i++) {
+    const column = columns[i];
+    const value = values[i];
+    if (column === undefined || value === undefined || value === null) {
+      continue;
+    }
+    writeValue(writer, column, value);
+  }
+  return writer.finish();
+}
+
+/**
+ * Decode one standalone sparse row; the bytes must contain exactly one row.
+ *
+ * Decode checks, in order (each a decode error, RFC §6.1): a set presence
+ * padding bit, an absent primary-key column, a set null-bitmap padding bit
+ * (a null for an absent column), a null bit for a non-nullable column.
+ */
+export function decodeSparseRow(
+  columns: readonly RowColumn[],
+  primaryKeyIndex: number,
+  bytes: Uint8Array,
+): SparseRowValue[] {
+  const reader = new ByteReader(bytes);
+  const presenceLength = Math.ceil(columns.length / 8);
+  const presence = reader.raw(presenceLength);
+  for (let bit = columns.length; bit < presenceLength * 8; bit++) {
+    if (bitmapBit(presence, bit)) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        'sparse row presence bitmap has a set padding bit (non-canonical encoding)',
+      );
+    }
+  }
+  const primaryKey = columns[primaryKeyIndex];
+  if (primaryKey === undefined) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      `primary-key column index ${primaryKeyIndex} is outside the column table`,
+    );
+  }
+  if (!bitmapBit(presence, primaryKeyIndex)) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      `sparse row is missing the primary-key column ${primaryKey.name}`,
+    );
+  }
+  let presentCount = 0;
+  for (let i = 0; i < columns.length; i++) {
+    if (bitmapBit(presence, i)) presentCount++;
+  }
+  const nullLength = Math.ceil(presentCount / 8);
+  const nulls = reader.raw(nullLength);
+  for (let bit = presentCount; bit < nullLength * 8; bit++) {
+    if (bitmapBit(nulls, bit)) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        'sparse row null bitmap sets a null bit for an absent column',
+      );
+    }
+  }
+  const values: SparseRowValue[] = [];
+  let present = 0;
+  for (let i = 0; i < columns.length; i++) {
+    const column = columns[i];
+    if (column === undefined || !bitmapBit(presence, i)) {
+      values.push(undefined);
+      continue;
+    }
+    const isNull = bitmapBit(nulls, present);
+    present++;
+    if (!isNull) {
+      values.push(readValue(reader, column));
+      continue;
+    }
+    if (!column.nullable) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `null bit set for non-nullable column ${column.name}`,
+      );
+    }
+    values.push(null);
+  }
+  reader.expectFullyConsumed('sparse row payload');
+  return values;
+}
+
 export function writeRow(
   writer: ByteWriter,
   columns: readonly RowColumn[],