@syncular/core 0.59.0 → 0.60.0

package/dist/canonical-json.d.ts

@@ -1,10 +1,21 @@
-/**
- * Canonical JSON for digests (SPEC.md §11.2) — contractual across
- * implementations: UTF-8, no insignificant whitespace, object keys sorted
- * by code-unit, scope value lists sorted and deduplicated.
- *
- * Used for the scope digest (§3.5) and the `X-Syncular-Scopes` header
- * (§5.5). Hashing itself is the host's job; this module only produces the
- * canonical text.
- */
+import type { FencedRecord } from './message.js';
+/** A unit's scope map: one value per requested variable (§4.1). */
+export type UnitScopes = Readonly<Record<string, string>>;
 export declare function canonicalScopeJson(scopes: Readonly<Record<string, readonly string[]>>): string;
+/** §4.1: the canonical JSON of a unit's scope map. */
+export declare function canonicalUnitJson(scopes: UnitScopes): string;
+/** §4.1: lowercase hex of the first 16 bytes of SHA-256 over the canonical
+ * JSON of the unit's scope map. */
+export declare function unitId(scopes: UnitScopes): string;
+/** §4.1: SHA-256 over the canonical JSON array of the units' scope maps in
+ * registration order, as 32 raw bytes. */
+export declare function registrationDigest(units: readonly UnitScopes[]): Uint8Array;
+/** One unit of the effective list as the echo digest sees it (§4.4). */
+export interface UnitEcho {
+    id: string;
+    status: 'active' | 'revoked';
+    fenced: readonly FencedRecord[];
+}
+/** §4.4: SHA-256 over the canonical JSON array, in registration order, of
+ * `{"fenced":[…],"id":…,"status":…}` per unit, as 32 raw bytes. */
+export declare function echoDigest(units: readonly UnitEcho[]): Uint8Array;

package/dist/canonical-json.js

@@ -1,12 +1,13 @@
 /**
- * Canonical JSON for digests (SPEC.md §11.2) — contractual across
- * implementations: UTF-8, no insignificant whitespace, object keys sorted
- * by code-unit, scope value lists sorted and deduplicated.
+ * Canonical JSON for digests (SPEC.md §11.2) and the digests over it —
+ * contractual across implementations: UTF-8, no insignificant whitespace,
+ * object keys sorted by code-unit, scope value lists sorted and
+ * deduplicated, every other array in its stated order.
  *
- * Used for the scope digest (§3.5) and the `X-Syncular-Scopes` header
- * (§5.5). Hashing itself is the host's job; this module only produces the
- * canonical text.
+ * Used for the unit id and registration digest (§4.1), the echo digest
+ * (§4.4), the scope digest (§3.5) and the `X-Syncular-Scopes` header (§5.5).
  */
+import { utf8Encode } from './bytes.js';
 export function canonicalScopeJson(scopes) {
     const keys = Object.keys(scopes).sort();
     const parts = keys.map((key) => {
@@ -16,3 +17,104 @@ export function canonicalScopeJson(scopes) {
     });
     return `{${parts.join(',')}}`;
 }
+/** §4.1: the canonical JSON of a unit's scope map. */
+export function canonicalUnitJson(scopes) {
+    const keys = Object.keys(scopes).sort();
+    const parts = keys.map((key) => `${JSON.stringify(key)}:${JSON.stringify(scopes[key])}`);
+    return `{${parts.join(',')}}`;
+}
+/** §4.1: lowercase hex of the first 16 bytes of SHA-256 over the canonical
+ * JSON of the unit's scope map. */
+export function unitId(scopes) {
+    let hex = '';
+    for (const byte of sha256(utf8Encode(canonicalUnitJson(scopes))).subarray(0, 16)) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/** §4.1: SHA-256 over the canonical JSON array of the units' scope maps in
+ * registration order, as 32 raw bytes. */
+export function registrationDigest(units) {
+    return sha256(utf8Encode(`[${units.map(canonicalUnitJson).join(',')}]`));
+}
+/** §4.4: SHA-256 over the canonical JSON array, in registration order, of
+ * `{"fenced":[…],"id":…,"status":…}` per unit, as 32 raw bytes. */
+export function echoDigest(units) {
+    const entries = units.map((unit) => {
+        const fenced = unit.fenced.map((record) => `{"scopes":${canonicalScopeJson(record.scopes)},"status":${JSON.stringify(record.status)},"table":${JSON.stringify(record.table)}}`);
+        return `{"fenced":[${fenced.join(',')}],"id":${JSON.stringify(unit.id)},"status":${JSON.stringify(unit.status)}}`;
+    });
+    return sha256(utf8Encode(`[${entries.join(',')}]`));
+}
+// FIPS 180-4 SHA-256. Synchronous so the unit id is a plain function of the
+// scope map on every runtime (WebCrypto digests are async only).
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+    0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+    0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+    0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function sha256(data) {
+    const padded = new Uint8Array(((data.length + 72) >>> 6) << 6);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(data.length / 0x20000000));
+    view.setUint32(padded.length - 4, (data.length * 8) >>> 0);
+    const h = [
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+        0x1f83d9ab, 0x5be0cd19,
+    ];
+    const w = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            w[i] =
+                (rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10)) +
+                    w[i - 7] +
+                    (rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3)) +
+                    w[i - 16];
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i++) {
+            const t1 = hh +
+                (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) +
+                ((e & f) ^ (~e & g)) +
+                K[i] +
+                w[i];
+            const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) +
+                ((a & b) ^ (a & c) ^ (b & c));
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d) | 0;
+        h[4] = (h[4] + e) | 0;
+        h[5] = (h[5] + f) | 0;
+        h[6] = (h[6] + g) | 0;
+        h[7] = (h[7] + hh) | 0;
+    }
+    const out = new Uint8Array(32);
+    const outView = new DataView(out.buffer);
+    h.forEach((word, i) => outView.setUint32(i * 4, word));
+    return out;
+}

package/dist/constants.d.ts

@@ -1,10 +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 = 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;
+export declare const PROTOCOL_WIRE_VERSION = 4;
+/** Oldest SSP2 envelope wire version accepted. Wire version 4 replaced
+ * per-table subscriptions with units and the replica cursor (§4); earlier
+ * versions are rejected as unknown (§9). */
+export declare const MINIMUM_PROTOCOL_WIRE_VERSION = 4;
 /** 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,10 +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 = 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;
+export const PROTOCOL_WIRE_VERSION = 4;
+/** Oldest SSP2 envelope wire version accepted. Wire version 4 replaced
+ * per-table subscriptions with units and the replica cursor (§4); earlier
+ * versions are rejected as unknown (§9). */
+export const MINIMUM_PROTOCOL_WIRE_VERSION = 4;
 /** 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/frames.d.ts

@@ -1,11 +1,12 @@
-/** Frame type registry for wire versions 1 and 2 (SPEC.md §1.2). */
+/** Frame type registry for wire version 4 (SPEC.md §1.2). */
 export declare const FrameType: {
     readonly END: 0;
     readonly REQ_HEADER: 1;
     readonly PUSH_COMMIT: 2;
     readonly PULL_HEADER: 3;
-    readonly SUBSCRIPTION: 4;
+    readonly UNIT: 4;
     readonly ROUND_FAILURE: 5;
+    readonly PROGRESS: 6;
     readonly RESP_HEADER: 16;
     readonly PUSH_RESULT: 17;
     readonly SUB_START: 18;
@@ -15,6 +16,8 @@ export declare const FrameType: {
     readonly SUB_END: 22;
     readonly LEASE: 25;
     readonly PUSH_RESULT_DETAILS: 27;
+    readonly LIVE_START: 28;
+    readonly LIVE_END: 29;
     readonly ERROR: 31;
 };
 export type FrameTypeName = keyof typeof FrameType;
@@ -22,5 +25,5 @@ export type FrameTypeName = keyof typeof FrameType;
 export declare const REQUEST_FRAME_TYPES: ReadonlySet<number>;
 /** Known response frame types (excluding END). */
 export declare const RESPONSE_FRAME_TYPES: ReadonlySet<number>;
-/** Every frame type with a defined layout in wire versions 1 and 2. */
+/** Every frame type with a defined layout in wire version 4. */
 export declare const KNOWN_FRAME_TYPES: ReadonlySet<number>;

package/dist/frames.js

@@ -1,11 +1,12 @@
-/** Frame type registry for wire versions 1 and 2 (SPEC.md §1.2). */
+/** Frame type registry for wire version 4 (SPEC.md §1.2). */
 export const FrameType = {
     END: 0x00,
     REQ_HEADER: 0x01,
     PUSH_COMMIT: 0x02,
     PULL_HEADER: 0x03,
-    SUBSCRIPTION: 0x04,
+    UNIT: 0x04,
     ROUND_FAILURE: 0x05,
+    PROGRESS: 0x06,
     RESP_HEADER: 0x10,
     PUSH_RESULT: 0x11,
     SUB_START: 0x12,
@@ -15,6 +16,8 @@ export const FrameType = {
     SUB_END: 0x16,
     LEASE: 0x19,
     PUSH_RESULT_DETAILS: 0x1b,
+    LIVE_START: 0x1c,
+    LIVE_END: 0x1d,
     ERROR: 0x1f,
 };
 /** Known request frame types (excluding END). */
@@ -22,8 +25,9 @@ export const REQUEST_FRAME_TYPES = new Set([
     FrameType.REQ_HEADER,
     FrameType.PUSH_COMMIT,
     FrameType.PULL_HEADER,
-    FrameType.SUBSCRIPTION,
+    FrameType.UNIT,
     FrameType.ROUND_FAILURE,
+    FrameType.PROGRESS,
 ]);
 /** Known response frame types (excluding END). */
 export const RESPONSE_FRAME_TYPES = new Set([
@@ -36,9 +40,11 @@ export const RESPONSE_FRAME_TYPES = new Set([
     FrameType.SUB_END,
     FrameType.LEASE,
     FrameType.PUSH_RESULT_DETAILS,
+    FrameType.LIVE_START,
+    FrameType.LIVE_END,
     FrameType.ERROR,
 ]);
-/** Every frame type with a defined layout in wire versions 1 and 2. */
+/** Every frame type with a defined layout in wire version 4. */
 export const KNOWN_FRAME_TYPES = new Set([
     FrameType.END,
     ...REQUEST_FRAME_TYPES,

package/dist/message.d.ts

@@ -6,6 +6,9 @@ export interface ReqHeaderFrame {
     schemaVersion: number;
     /** Partition log identity; absent requests epoch acquisition. */
     logEpoch?: string;
+    /** Identity of the sender's outbox sequence (§6.3.2, §7.1); absent for a
+     * sender without an outbox. Non-empty, at most 64 bytes. */
+    outboxId?: string;
 }
 export interface PushOperation {
     table: string;
@@ -19,6 +22,8 @@ export interface PushOperation {
 export interface PushCommitFrame {
     type: 'PUSH_COMMIT';
     clientCommitId: string;
+    /** Outbox sequence number (§6.3.2, §7.1); `0` without an outbox. */
+    clientSeq: number;
     operations: PushOperation[];
 }
 export interface PullHeaderFrame {
@@ -28,14 +33,24 @@ export interface PullHeaderFrame {
     maxSnapshotPages: number;
     /** Bitmask (§4.2): bit 0 inline rows, 1 external rows, 2 sqlite, 3 signed URLs. */
     accept: number;
+    /** The replica cursor (§4.5); `-1` when no unit is live. */
+    cursor: number;
+    /** §4.1 registration digest: exactly 32 bytes. */
+    registrationDigest: Uint8Array;
+    /** The last processed `LIVE_END.echoDigest`: empty or 32 bytes (§4.2). */
+    echoDigest: Uint8Array;
+}
+/** §4.3: one unit of a traveling registration list. */
+export interface UnitFrame {
+    type: 'UNIT';
+    scopes: Record<string, string>;
 }
-export interface SubscriptionFrame {
-    type: 'SUBSCRIPTION';
+/** §4.3: the progress of one catching-up unit. */
+export interface ProgressFrame {
+    type: 'PROGRESS';
+    /** The unit id (§4.1): 32 lowercase hex characters. */
     id: string;
-    table: string;
-    scopes: ScopeMap;
-    /** Host-opaque JSON document, preserved verbatim. */
-    params?: string;
+    /** `-1`, the §4.7 pin while a resume token is held, or the unit cursor. */
     cursor: number;
     /** Opaque resume token JSON, round-tripped byte-for-byte (§4.7). */
     bootstrapState?: string;
@@ -53,7 +68,7 @@ export interface RoundFailureFrame {
     type: 'ROUND_FAILURE';
     code: string;
 }
-export type RequestFrame = ReqHeaderFrame | RoundFailureFrame | PushCommitFrame | PullHeaderFrame | SubscriptionFrame | UnknownFrame;
+export type RequestFrame = ReqHeaderFrame | RoundFailureFrame | PushCommitFrame | PullHeaderFrame | UnitFrame | ProgressFrame | UnknownFrame;
 export interface RespHeaderFrame {
     type: 'RESP_HEADER';
     requiredSchemaVersion?: number;
@@ -118,20 +133,43 @@ export interface PushResultDetailsFrame {
         details: RejectionDetails;
     }>;
 }
+/** §4.4: one (unit, table) pair the wildcard fence touched. */
+export interface FencedRecord {
+    table: string;
+    status: 'active' | 'revoked';
+    /** Effective lists of the variables the fence added; empty when revoked. */
+    scopes: ScopeMap;
+}
 export interface SubStartFrame {
     type: 'SUB_START';
+    /** The unit id (§4.1): 32 lowercase hex characters. */
     id: string;
     status: 'active' | 'revoked' | 'reset';
     reasonCode: string;
-    effectiveScopes: ScopeMap;
     bootstrap: boolean;
+    /** The unit's echo, in ascending table order (§4.4). */
+    fenced: FencedRecord[];
+}
+export interface LiveStartFrame {
+    type: 'LIVE_START';
+    status: 'active' | 'reset' | 'unregistered';
+    reasonCode: string;
+}
+export interface LiveEndFrame {
+    type: 'LIVE_END';
+    /** Highest commitSeq the live section is complete through; `-1` for
+     * `reset` and `unregistered` (§4.4). */
+    throughSeq: number;
+    /** Echo digest of the request: empty or 32 bytes (§4.4). */
+    echoDigest: Uint8Array;
 }
 export interface CommitChange {
     tableIndex: number;
     rowId: string;
     op: 'upsert' | 'delete';
-    /** Present iff `op` is `upsert` (§4.5). */
-    rowVersion?: number;
+    /** The row's `server_version` after the write, ≥ 1; a delete's is the
+     * version its tombstone records (§2.2, §4.5). */
+    rowVersion: number;
     scopes: Record<string, string>;
     /** Generated-row-codec bytes; present iff `op` is `upsert` (§4.5). */
     row?: Uint8Array;
@@ -167,7 +205,7 @@ export interface SegmentInlineFrame {
 export interface SubEndFrame {
     type: 'SUB_END';
     nextCursor: number;
-    /** Present iff the bootstrap is incomplete (§4.4). */
+    /** Present iff the unit's bootstrap is incomplete (§4.4). */
     bootstrapState?: string;
 }
 export interface ErrorFrame {
@@ -179,7 +217,7 @@ export interface ErrorFrame {
     recommendedAction: string;
     details?: string;
 }
-export type ResponseFrame = RespHeaderFrame | LeaseFrame | PushResultFrame | PushResultDetailsFrame | SubStartFrame | CommitFrame | SegmentRefFrame | SegmentInlineFrame | SubEndFrame | ErrorFrame | UnknownFrame;
+export type ResponseFrame = RespHeaderFrame | LeaseFrame | PushResultFrame | PushResultDetailsFrame | SubStartFrame | CommitFrame | SegmentRefFrame | SegmentInlineFrame | SubEndFrame | LiveStartFrame | LiveEndFrame | ErrorFrame | UnknownFrame;
 export interface RequestMessage {
     wireVersion: number;
     msgKind: 'request';
@@ -193,6 +231,9 @@ export interface ResponseMessage {
 export type SyncMessage = RequestMessage | ResponseMessage;
 /** §1.5: `code` is a legal `ROUND_FAILURE` code (grammar and byte length). */
 export declare function isRoundFailureCode(code: string): boolean;
-export declare function validateFrameSequence(message: SyncMessage): void;
+export declare function encodeRequest(message: RequestMessage): Uint8Array;
+export declare function encodeResponse(message: ResponseMessage): Uint8Array;
 export declare function encodeMessage(message: SyncMessage): Uint8Array;
+export declare function decodeRequest(bytes: Uint8Array): RequestMessage;
+export declare function decodeResponse(bytes: Uint8Array): ResponseMessage;
 export declare function decodeMessage(bytes: Uint8Array): SyncMessage;