@quereus/sync 4.4.0 → 4.4.1

package/dist/src/metadata/column-version.js

@@ -5,19 +5,23 @@
  * When merging changes, the column with the higher HLC wins.
  */
 import { serializeHLC, deserializeHLC, compareHLC, hlcToJson, hlcFromJson } from '../clock/hlc.js';
-import { buildColumnVersionKey, buildColumnVersionScanBounds } from './keys.js';
+import { buildColumnVersionKey, buildColumnVersionRowPrefix, buildColumnVersionScanBounds, encodePkIdentity } from './keys.js';
 /**
  * Serialize a column version for storage.
- * Format: 30 bytes HLC + JSON payload `{ v, pv?, ph? }`.
+ * Format: 30 bytes HLC + JSON payload `{ v, k, pv?, ph? }`.
  *
  * Uint8Array values are encoded as `{"__bin":"<base64>"}` (bigint as
  * `{"__bigint":"..."}`) so they survive the JSON round-trip; the same encoding
- * covers the before-image (`pv`). The before-image fields are omitted entirely
- * when the version has no prior, keeping first-writes and snapshot cells compact.
+ * covers the pk cells and the before-image (`pv`). The before-image fields are
+ * omitted entirely when the version has no prior, keeping first-writes and
+ * snapshot cells compact.
  */
 export function serializeColumnVersion(cv) {
     const hlcBytes = serializeHLC(cv.hlc);
-    const payload = { v: encodeSqlValue(cv.value) };
+    const payload = {
+        v: encodeSqlValue(cv.value),
+        k: cv.pk.map(encodeSqlValue),
+    };
     if (cv.priorHlc !== undefined) {
         payload.ph = hlcToJson(cv.priorHlc);
         payload.pv = encodeSqlValue(cv.priorValue ?? null);
@@ -35,7 +39,7 @@ export function serializeColumnVersion(cv) {
 export function deserializeColumnVersion(buffer) {
     const hlc = deserializeHLC(buffer.slice(0, 30));
     const payload = JSON.parse(new TextDecoder().decode(buffer.slice(30)));
-    const cv = { hlc, value: decodeSqlValue(payload.v) };
+    const cv = { hlc, value: decodeSqlValue(payload.v), pk: payload.k.map(decodeSqlValue) };
     if (payload.ph !== undefined) {
         cv.priorHlc = hlcFromJson(payload.ph);
         cv.priorValue = decodeSqlValue(payload.pv);
@@ -100,17 +104,33 @@ export function decodeSqlValue(v) {
 }
 /**
  * Column version store operations.
+ *
+ * Every pk-taking method derives the record key's pk IDENTITY through the
+ * per-table {@link PkKeyingResolver} passed at construction, so callers keep
+ * addressing rows by raw pk while the storage keys collapse spellings.
  */
 export class ColumnVersionStore {
     kv;
-    constructor(kv) {
+    keying;
+    constructor(kv, keying) {
         this.kv = kv;
+        this.keying = keying;
+    }
+    identity(schemaName, tableName, pk) {
+        return encodePkIdentity(pk, this.keying(schemaName, tableName));
     }
     /**
      * Get the version of a specific column.
      */
     async getColumnVersion(schemaName, tableName, pk, column) {
-        const key = buildColumnVersionKey(schemaName, tableName, pk, column);
+        return this.getColumnVersionByIdentity(schemaName, tableName, this.identity(schemaName, tableName, pk), column);
+    }
+    /**
+     * Get the version of a specific column by pk IDENTITY (as recovered from a
+     * parsed `cv:`/`cl:` key — no raw pk needed).
+     */
+    async getColumnVersionByIdentity(schemaName, tableName, identity, column) {
+        const key = buildColumnVersionKey(schemaName, tableName, identity, column);
         const data = await this.kv.get(key);
         if (!data)
             return undefined;
@@ -120,41 +140,75 @@ export class ColumnVersionStore {
      * Set the version of a specific column.
      */
     async setColumnVersion(schemaName, tableName, pk, column, version) {
-        const key = buildColumnVersionKey(schemaName, tableName, pk, column);
-        await this.kv.put(key, serializeColumnVersion(version));
+        const key = buildColumnVersionKey(schemaName, tableName, this.identity(schemaName, tableName, pk), column);
+        await this.kv.put(key, serializeColumnVersion({ ...version, pk }));
     }
     /**
-     * Set column version in a batch.
+     * Set column version in a batch. The key's pk IDENTITY is always derived
+     * locally through this store's keying resolver — there is deliberately no
+     * caller-supplied-identity variant (a snapshot receiver trusting a sender's
+     * identity was the bug fixed by deriving on ingress; see docs/sync.md
+     * § Row identity vs. address).
      */
     setColumnVersionBatch(batch, schemaName, tableName, pk, column, version) {
-        const key = buildColumnVersionKey(schemaName, tableName, pk, column);
-        batch.put(key, serializeColumnVersion(version));
+        const key = buildColumnVersionKey(schemaName, tableName, this.identity(schemaName, tableName, pk), column);
+        batch.put(key, serializeColumnVersion({ ...version, pk }));
     }
     /**
      * Get all column versions for a row.
      */
     async getRowVersions(schemaName, tableName, pk) {
-        const bounds = buildColumnVersionScanBounds(schemaName, tableName, pk);
+        const identity = this.identity(schemaName, tableName, pk);
+        const bounds = buildColumnVersionScanBounds(schemaName, tableName, identity);
+        const prefix = buildColumnVersionRowPrefix(schemaName, tableName, identity);
+        const decoder = new TextDecoder();
         const versions = new Map();
         for await (const entry of this.kv.iterate(bounds)) {
-            // Extract column name from key
-            const keyStr = new TextDecoder().decode(entry.key);
-            const lastColon = keyStr.lastIndexOf(':');
-            const column = keyStr.slice(lastColon + 1);
+            // The scan bounds are exactly [prefix, prefix+1), so every key here starts
+            // with `prefix` and everything after it is the column name verbatim —
+            // including a name containing `:`, which a last-colon split would truncate.
+            const keyStr = decoder.decode(entry.key);
+            const column = keyStr.slice(prefix.length);
             versions.set(column, deserializeColumnVersion(entry.value));
         }
         return versions;
     }
     /**
-     * Delete all column versions for a row.
+     * Queue deletion of ONE column's cell record into `batch`, whether or not a
+     * committed record exists — the caller may be removing a record that is only
+     * STAGED in this same batch (the local-capture delete cleanup; see
+     * `deleteRowVersionsAndLogEntries`).
      */
-    async deleteRowVersions(schemaName, tableName, pk) {
-        const bounds = buildColumnVersionScanBounds(schemaName, tableName, pk);
-        const batch = this.kv.batch();
-        for await (const entry of this.kv.iterate(bounds)) {
-            batch.delete(entry.key);
+    deleteColumnVersionBatch(batch, schemaName, tableName, pk, column) {
+        batch.delete(buildColumnVersionKey(schemaName, tableName, this.identity(schemaName, tableName, pk), column));
+    }
+    /**
+     * Queue deletion of every column version of a row into `batch`, returning the
+     * versions that were removed (column → version). A column in `keepColumns` is
+     * skipped entirely — neither staged for deletion nor included in the returned
+     * map (its paired `cl:` entry must survive too; see
+     * `deleteRowVersionsAndLogEntries`).
+     *
+     * The returned map is what lets a caller drop the paired `cl:` change-log
+     * entries in the SAME batch — each entry's key embeds the version's HLC, which
+     * is only recoverable from the record being deleted.
+     *
+     * NOTE: this fully deserializes each cell (a JSON parse of the value) when the
+     * change-log caller only needs the 30-byte HLC prefix. If deleting wide rows or
+     * rows with large blob cells ever shows up as slow, read just the HLC prefix
+     * here instead of reusing `getRowVersions`.
+     */
+    async deleteRowVersionsBatch(batch, schemaName, tableName, pk, keepColumns) {
+        const identity = this.identity(schemaName, tableName, pk);
+        const versions = await this.getRowVersions(schemaName, tableName, pk);
+        for (const column of [...versions.keys()]) {
+            if (keepColumns?.has(column)) {
+                versions.delete(column);
+                continue;
+            }
+            batch.delete(buildColumnVersionKey(schemaName, tableName, identity, column));
         }
-        await batch.write();
+        return versions;
     }
     /**
      * Check if a column write should be applied (LWW comparison).

package/dist/src/metadata/column-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"column-version.js","sourceRoot":"","sources":["../../../src/metadata/column-version.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"column-version.js","sourceRoot":"","sources":["../../../src/metadata/column-version.ts"],"names":[],"mappings":"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"}

package/dist/src/metadata/index.d.ts

@@ -2,6 +2,7 @@
  * Metadata module exports.
  */
 export * from './keys.js';
+export * from './pk-identity.js';
 export * from './column-version.js';
 export * from './tombstones.js';
 export * from './peer-state.js';

package/dist/src/metadata/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/src/metadata/index.js

@@ -2,6 +2,7 @@
  * Metadata module exports.
  */
 export * from './keys.js';
+export * from './pk-identity.js';
 export * from './column-version.js';
 export * from './tombstones.js';
 export * from './peer-state.js';

package/dist/src/metadata/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/src/metadata/keys.d.ts

@@ -13,6 +13,7 @@
  *   cl: - Change log (HLC-indexed for efficient delta queries)
  *   qt: - Quarantine (held out-of-basis straggler changes)
  *   bl: - Basis-table lifecycle (mapped/derivation-source/unreferenced/detached bookkeeping)
+ *   fv: - Sync-metadata format version (single record; see SYNC_METADATA_FORMAT_VERSION)
  */
 import type { SqlValue } from '@quereus/quereus';
 import { type SiteId } from '../clock/site.js';
@@ -30,26 +31,68 @@ export declare const SYNC_KEY_PREFIX: {
     readonly CHANGE_LOG: Uint8Array<ArrayBuffer>;
     readonly QUARANTINE: Uint8Array<ArrayBuffer>;
     readonly BASIS_LIFECYCLE: Uint8Array<ArrayBuffer>;
+    readonly FORMAT_VERSION: Uint8Array<ArrayBuffer>;
 };
 /**
- * Encode a primary key as a string for use in metadata keys.
- * Uses JSON for simplicity and determinism.
+ * Current sync-metadata storage format version, persisted under the `fv:` key.
+ *
+ * Version 2: per-row records (`cv:`/`tb:`/`cl:`) are keyed by the pk IDENTITY
+ * (collation- and semantic-transform-normalized, via {@link encodePkIdentity})
+ * and carry the raw pk in the record VALUE. Version-1 metadata (raw
+ * `JSON.stringify(pk)` keys, no pk in values) is unreadable under this layout;
+ * a replica whose stored version mismatches must re-bootstrap from a peer
+ * snapshot (see docs/sync.md § Metadata format version).
+ */
+export declare const SYNC_METADATA_FORMAT_VERSION = 2;
+/**
+ * Per-pk-column normalization for one table, resolved once from its schema
+ * (see `metadata/pk-identity.ts`). Mirrors the engine's row-identity rule:
+ * each pk column's KEY COLLATION normalizer plus its logical type's semantic
+ * key transform (TIMESPAN → total seconds), so two spellings of one row
+ * ('apple'/'APPLE' under nocase, 'PT1H'/'PT60M') produce ONE identity.
  */
-export declare function encodePK(pk: SqlValue[]): string;
+export interface PkKeying {
+    readonly normalizers: ReadonlyArray<(s: string) => string>;
+    readonly transforms: ReadonlyArray<((v: SqlValue) => SqlValue) | undefined>;
+}
 /**
- * Decode a primary key from its string representation.
+ * Keying that applies NO collation and NO semantic transform — raw value
+ * identity. Used where no table schema can exist: quarantine keys (out-of-basis
+ * by definition) and relay-only deployments with no schema oracle, where the
+ * raw identity is stable for the replica's whole life (an oracle can never
+ * appear later, so the identity can never flip).
  */
-export declare function decodePK(encoded: string): SqlValue[];
+export declare const RAW_PK_KEYING: PkKeying;
+/**
+ * Encode a primary key's IDENTITY — the string a row's sync bookkeeping is filed
+ * under. Built on the engine's type-tagged `serializeKeyNullGrouping`, so:
+ *  - numerics share one tag (`5n` and `5` key alike — bigint-safe, unlike the
+ *    former `JSON.stringify` encoding which threw on bigint);
+ *  - string values run through the column's key-collation normalizer;
+ *  - semantic-ordering types (TIMESPAN) run through their `groupKey` first.
+ *
+ * The result is LOSSY and never decoded back — the raw pk (the row's ADDRESS,
+ * what goes on the wire) lives in the record VALUE instead.
+ */
+export declare function encodePkIdentity(pk: SqlValue[], keying: PkKeying): string;
+/** Raw (no-collation, no-transform) pk identity — see {@link RAW_PK_KEYING}. */
+export declare function encodeRawPkIdentity(pk: SqlValue[]): string;
 /**
  * Build a column version key.
- * Format: cv:{schema}.{table}:{pk_json}:{column}
+ * Format: cv:{schema}.{table}:{identity_length}:{identity}:{column}
+ *
+ * The identity is LENGTH-PREFIXED (code units of the decoded key string) because
+ * it freely contains `:` (type tags) and `\0` (member separator) — no separator
+ * character is guaranteed absent, so an explicit length is the only unambiguous
+ * split between identity and column.
  */
-export declare function buildColumnVersionKey(schemaName: string, tableName: string, pk: SqlValue[], column: string): Uint8Array;
+export declare function buildColumnVersionKey(schemaName: string, tableName: string, identity: string, column: string): Uint8Array;
 /**
  * Build a tombstone key.
- * Format: tb:{schema}.{table}:{pk_json}
+ * Format: tb:{schema}.{table}:{identity}
+ * (No length prefix — the identity is the final component.)
  */
-export declare function buildTombstoneKey(schemaName: string, tableName: string, pk: SqlValue[]): Uint8Array;
+export declare function buildTombstoneKey(schemaName: string, tableName: string, identity: string): Uint8Array;
 /**
  * Build a transaction record key.
  * Format: tx:{transactionId}
@@ -85,11 +128,21 @@ export declare function buildTableColumnVersionScanBounds(schemaName: string, ta
     gte: Uint8Array;
     lt: Uint8Array;
 };
+/**
+ * The key prefix shared by every column version of one row:
+ * `cv:{schema}.{table}:{identity_length}:{identity}:`.
+ *
+ * Exported so a row scan can recover each entry's column name by stripping this
+ * exact prefix, rather than splitting the key at its last `:` — the column name
+ * is the only unbounded, separator-bearing component, so only the prefix is
+ * unambiguous (see {@link parseColumnVersionKey}, which has no pk to anchor on).
+ */
+export declare function buildColumnVersionRowPrefix(schemaName: string, tableName: string, identity: string): string;
 /**
  * Build scan bounds for all column versions of a row.
- * Returns keys to scan cv:{schema}.{table}:{pk_json}:*
+ * Returns keys to scan cv:{schema}.{table}:{identity_length}:{identity}:*
  */
-export declare function buildColumnVersionScanBounds(schemaName: string, tableName: string, pk: SqlValue[]): {
+export declare function buildColumnVersionScanBounds(schemaName: string, tableName: string, identity: string): {
     gte: Uint8Array;
     lt: Uint8Array;
 };
@@ -130,22 +183,30 @@ export declare function buildAllSchemaMigrationsScanBounds(): {
 };
 /**
  * Parse a column version key to extract components.
- * Key format: cv:{schema}.{table}:{pk_json}:{column}
+ * Key format: cv:{schema}.{table}:{identity_length}:{identity}:{column}
+ *
+ * Returns the pk IDENTITY string — the identity is lossy and cannot be decoded
+ * back to values; the raw pk lives in the record VALUE (`ColumnVersion.pk`).
+ * The length prefix makes the identity/column split unambiguous regardless of
+ * what characters either contains.
  */
 export declare function parseColumnVersionKey(key: Uint8Array): {
     schema: string;
     table: string;
-    pk: SqlValue[];
+    identity: string;
     column: string;
 } | null;
 /**
  * Parse a tombstone key to extract components.
- * Key format: tb:{schema}.{table}:{pk_json}
+ * Key format: tb:{schema}.{table}:{identity}
+ *
+ * Returns the pk IDENTITY string; the raw pk lives in the record VALUE
+ * (`Tombstone.pk`).
  */
 export declare function parseTombstoneKey(key: Uint8Array): {
     schema: string;
     table: string;
-    pk: SqlValue[];
+    identity: string;
 } | null;
 /**
  * Parse a schema migration key to extract components.
@@ -172,12 +233,13 @@ export declare function serializeHLCForKey(hlc: HLC): Uint8Array;
 export declare function deserializeHLCFromKey(buffer: Uint8Array): HLC;
 /**
  * Build a change log key.
- * Format: cl:{hlc_bytes}{type_byte}{schema}.{table}:{pk_json}:{column?}
+ * Format: cl:{hlc_bytes}{type_byte}{schema}.{table}:{identity_length}:{identity}[:{column}]
  *
  * The HLC comes first to enable efficient range scans by time.
  * type_byte: 0x01 for column change, 0x02 for delete
+ * The identity is length-prefixed for the same reason as {@link buildColumnVersionKey}.
  */
-export declare function buildChangeLogKey(hlc: HLC, entryType: ChangeLogEntryType, schemaName: string, tableName: string, pk: SqlValue[], column?: string): Uint8Array;
+export declare function buildChangeLogKey(hlc: HLC, entryType: ChangeLogEntryType, schemaName: string, tableName: string, identity: string, column?: string): Uint8Array;
 /**
  * Build scan bounds for change log entries after a given HLC.
  * Returns keys to scan cl:{sinceHLC}* to end of change log.
@@ -201,19 +263,23 @@ export declare function parseChangeLogKey(key: Uint8Array): {
     entryType: ChangeLogEntryType;
     schema: string;
     table: string;
-    pk: SqlValue[];
+    identity: string;
     column?: string;
 } | null;
 /**
  * Build a quarantine key for a held out-of-basis straggler change.
- * Format: qt:{schema}.{table}: + hlc_bytes(30) + type_byte(1) + :{pk_json}[:{column}]
+ * Format: qt:{schema}.{table}: + hlc_bytes(30) + type_byte(1) + :{raw_identity}[:{column}]
  *
  * Unlike the change log (`cl:`), the table prefix comes BEFORE the HLC so the
  * range scans by `(schema, table)` for operator inspection. The HLC + type + pk
  * (+ column) suffix make the key idempotent: re-applying the same straggler
- * change (same HLC) overwrites its own entry rather than accumulating. Reuses
- * {@link serializeHLCForKey} / {@link encodePK} for parity with the change-log
- * encoding.
+ * change (same HLC) overwrites its own entry rather than accumulating.
+ *
+ * The pk component uses the RAW identity encoding ({@link encodeRawPkIdentity})
+ * deliberately: a quarantined table is out of the local basis, so no schema —
+ * and hence no collation/transform keying — can exist for it. Raw is sound here
+ * because the `(hlc, type)` component already makes the key unique per change,
+ * and it is bigint-safe (the former `JSON.stringify` threw on a bigint pk).
  *
  * The value (not the key) carries the serialized change verbatim, so quarantine
  * keys are written and pruned but never parsed back.

package/dist/src/metadata/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/metadata/keys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/metadata/keys.ts"],"names":[],"mappings":"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"}