@syncular/server 0.1.3 → 0.2.0

package/dist/sigv4.js

@@ -0,0 +1,161 @@
+/**
+ * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
+ * store needs (header-signed requests and presigned GET URLs), hand-rolled
+ * per the dependency-light doctrine (REVISE): SigV4 is small and
+ * well-specified, so no SDK.
+ *
+ * Runtime-neutral (TODO §4.2): the crypto primitives are Web Crypto
+ * (`crypto.subtle`), not `node:crypto`, so this module runs unchanged on
+ * Cloudflare Workers / Deno / browsers as well as Bun/Node. `crypto.subtle`
+ * is async, so signing is async throughout; the `S3SegmentStore` consumers
+ * are already async, and the `DelegatedPresignConfig.presign` seam already
+ * accepts a `Promise<SegmentUrlIssue>`.
+ *
+ * Pinned by the published AWS SigV4 example vectors in
+ * `test/sigv4.test.ts`; the hermetic S3 stub re-derives every signature
+ * from the incoming request, so an asymmetric signing bug fails tests.
+ */
+/** Hex SHA-256 of an empty body — the payload hash for GET/HEAD/DELETE. */
+export const EMPTY_PAYLOAD_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+/** The presigned-URL payload sentinel (S3 presigns never hash the body). */
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+const textEncoder = new TextEncoder();
+function toBytes(data) {
+    return typeof data === 'string' ? textEncoder.encode(data) : data;
+}
+function toHex(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** Web Crypto wants an `ArrayBuffer`; slice() gives an owned, exact-length one. */
+function bufferOf(bytes) {
+    return bytes.slice().buffer;
+}
+export async function sha256Hex(data) {
+    const digest = await crypto.subtle.digest('SHA-256', bufferOf(toBytes(data)));
+    return toHex(new Uint8Array(digest));
+}
+async function hmacSha256(key, data) {
+    const cryptoKey = await crypto.subtle.importKey('raw', bufferOf(toBytes(key)), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = await crypto.subtle.sign('HMAC', cryptoKey, bufferOf(toBytes(data)));
+    return new Uint8Array(mac);
+}
+/**
+ * AWS canonical URI-encoding: RFC 3986 unreserved characters only —
+ * stricter than `encodeURIComponent` (which leaves `!'()*` alone).
+ */
+export function uriEncode(value, encodeSlash) {
+    const encoded = encodeURIComponent(value).replace(/[!'()*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+    return encodeSlash ? encoded : encoded.replaceAll('%2F', '/');
+}
+/** `YYYYMMDD'T'HHMMSS'Z'` plus its date-only prefix, from epoch ms. */
+export function amzTimestamps(nowMs) {
+    const iso = new Date(nowMs).toISOString();
+    const amzDate = `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}T${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}Z`;
+    return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+/** Sorted, fully re-encoded canonical query string from *decoded* pairs. */
+export function canonicalQuery(params) {
+    return [...params]
+        .map(([k, v]) => [uriEncode(k, true), uriEncode(v, true)])
+        .sort(([ak, av], [bk, bv]) => ak < bk ? -1 : ak > bk ? 1 : av < bv ? -1 : av > bv ? 1 : 0)
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+}
+export function canonicalRequest(args) {
+    const entries = Object.entries(args.headers)
+        .map(([name, value]) => [name.toLowerCase(), value.trim().replace(/\s+/g, ' ')])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const signedHeaders = entries.map(([name]) => name).join(';');
+    const text = [
+        args.method.toUpperCase(),
+        args.canonicalPath,
+        canonicalQuery(args.query),
+        ...entries.map(([name, value]) => `${name}:${value}`),
+        '',
+        signedHeaders,
+        args.payloadHash,
+    ].join('\n');
+    return { text, signedHeaders };
+}
+export async function stringToSign(amzDate, scope, canonicalRequestText) {
+    return `AWS4-HMAC-SHA256\n${amzDate}\n${scope}\n${await sha256Hex(canonicalRequestText)}`;
+}
+export async function sigV4Signature(args) {
+    const kDate = await hmacSha256(`AWS4${args.secretAccessKey}`, args.dateStamp);
+    const kRegion = await hmacSha256(kDate, args.region);
+    const kService = await hmacSha256(kRegion, args.service);
+    const kSigning = await hmacSha256(kService, 'aws4_request');
+    return toHex(await hmacSha256(kSigning, args.stringToSign));
+}
+/**
+ * Headers for a header-authenticated request: the caller's headers plus
+ * `x-amz-date`, `x-amz-content-sha256`, optional `x-amz-security-token`,
+ * and `authorization`. `host` is signed but not returned — fetch derives
+ * it from the URL.
+ */
+export async function signRequest(args) {
+    const service = args.service ?? 's3';
+    const { amzDate, dateStamp } = amzTimestamps(args.nowMs);
+    const added = {
+        'x-amz-content-sha256': args.payloadHash,
+        'x-amz-date': amzDate,
+        ...(args.credentials.sessionToken !== undefined
+            ? { 'x-amz-security-token': args.credentials.sessionToken }
+            : {}),
+    };
+    const { text, signedHeaders } = canonicalRequest({
+        method: args.method,
+        canonicalPath: args.url.pathname,
+        query: args.url.searchParams,
+        headers: { ...args.headers, ...added, host: args.url.host },
+        payloadHash: args.payloadHash,
+    });
+    const scope = `${dateStamp}/${args.region}/${service}/aws4_request`;
+    const signature = await sigV4Signature({
+        secretAccessKey: args.credentials.secretAccessKey,
+        dateStamp,
+        region: args.region,
+        service,
+        stringToSign: await stringToSign(amzDate, scope, text),
+    });
+    return {
+        ...args.headers,
+        ...added,
+        authorization: `AWS4-HMAC-SHA256 Credential=${args.credentials.accessKeyId}/${scope},SignedHeaders=${signedHeaders},Signature=${signature}`,
+    };
+}
+/** Query-authenticated (presigned) URL; only the `host` header is signed. */
+export async function presignUrl(args) {
+    const service = args.service ?? 's3';
+    const method = args.method ?? 'GET';
+    const { amzDate, dateStamp } = amzTimestamps(args.nowMs);
+    const scope = `${dateStamp}/${args.region}/${service}/aws4_request`;
+    const url = new URL(args.url);
+    url.searchParams.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+    url.searchParams.set('X-Amz-Credential', `${args.credentials.accessKeyId}/${scope}`);
+    url.searchParams.set('X-Amz-Date', amzDate);
+    url.searchParams.set('X-Amz-Expires', String(args.expiresSeconds));
+    url.searchParams.set('X-Amz-SignedHeaders', 'host');
+    if (args.credentials.sessionToken !== undefined) {
+        url.searchParams.set('X-Amz-Security-Token', args.credentials.sessionToken);
+    }
+    const { text } = canonicalRequest({
+        method,
+        canonicalPath: url.pathname,
+        query: url.searchParams,
+        headers: { host: url.host },
+        payloadHash: UNSIGNED_PAYLOAD,
+    });
+    const signature = await sigV4Signature({
+        secretAccessKey: args.credentials.secretAccessKey,
+        dateStamp,
+        region: args.region,
+        service,
+        stringToSign: await stringToSign(amzDate, scope, text),
+    });
+    url.searchParams.set('X-Amz-Signature', signature);
+    return url;
+}

package/dist/sqlite-blob-store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SQLite-backed blob store via `bun:sqlite` (dev/bench convenience,
+ * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
+ * so it lives in its own module — the runtime-neutral `BlobStore` interface,
+ * `MemoryBlobStore`, `blobIdFor`, and `isBlobId` stay in `blob-store.ts` for
+ * the Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+import type { BlobRecord, BlobStore, BlobStoreStats } from './blob-store.js';
+export declare class SqliteBlobStore implements BlobStore {
+    readonly db: Database;
+    constructor(db?: Database | string);
+    put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    has(partition: string, blobId: string): Promise<boolean>;
+    get(partition: string, blobId: string): Promise<{
+        record: BlobRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    stats(partition: string): Promise<BlobStoreStats>;
+}

package/dist/sqlite-blob-store.js

@@ -0,0 +1,86 @@
+/**
+ * SQLite-backed blob store via `bun:sqlite` (dev/bench convenience,
+ * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
+ * so it lives in its own module — the runtime-neutral `BlobStore` interface,
+ * `MemoryBlobStore`, `blobIdFor`, and `isBlobId` stay in `blob-store.ts` for
+ * the Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+export class SqliteBlobStore {
+    db;
+    constructor(db = ':memory:') {
+        this.db = typeof db === 'string' ? new Database(db) : db;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_blobs(
+        partition TEXT NOT NULL, blob_id TEXT NOT NULL,
+        byte_length INTEGER NOT NULL, media_type TEXT,
+        created_at_ms INTEGER NOT NULL, bytes BLOB NOT NULL,
+        PRIMARY KEY (partition, blob_id)
+      );
+    `);
+    }
+    async put(partition, blobId, bytes, nowMs, mediaType) {
+        const existing = await this.get(partition, blobId);
+        if (existing !== undefined)
+            return existing.record;
+        const record = {
+            blobId,
+            partition,
+            byteLength: bytes.length,
+            ...(mediaType !== undefined ? { mediaType } : {}),
+            createdAtMs: nowMs,
+        };
+        this.db
+            .query(`INSERT OR IGNORE INTO sync_blobs(
+          partition, blob_id, byte_length, media_type, created_at_ms, bytes
+        ) VALUES (?,?,?,?,?,?)`)
+            .run(partition, blobId, bytes.length, mediaType ?? null, nowMs, bytes);
+        return record;
+    }
+    async has(partition, blobId) {
+        const row = this.db
+            .query('SELECT 1 AS n FROM sync_blobs WHERE partition=? AND blob_id=?')
+            .get(partition, blobId);
+        return row !== null;
+    }
+    async get(partition, blobId) {
+        const row = this.db
+            .query(`SELECT byte_length, media_type, created_at_ms, bytes
+         FROM sync_blobs WHERE partition=? AND blob_id=?`)
+            .get(partition, blobId);
+        if (row === null)
+            return undefined;
+        return {
+            record: {
+                blobId,
+                partition,
+                byteLength: row.byte_length,
+                ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
+                createdAtMs: row.created_at_ms,
+            },
+            bytes: new Uint8Array(row.bytes),
+        };
+    }
+    async sweepOrphans(partition, olderThanMs, referencedBlobIds) {
+        const candidates = this.db
+            .query(`SELECT blob_id FROM sync_blobs
+         WHERE partition=? AND created_at_ms < ?`)
+            .all(partition, olderThanMs);
+        const swept = [];
+        const del = this.db.query('DELETE FROM sync_blobs WHERE partition=? AND blob_id=?');
+        for (const { blob_id } of candidates) {
+            if (!referencedBlobIds.has(blob_id)) {
+                del.run(partition, blob_id);
+                swept.push(blob_id);
+            }
+        }
+        return swept;
+    }
+    async stats(partition) {
+        const row = this.db
+            .query('SELECT count(*) AS count, sum(byte_length) AS bytes FROM sync_blobs WHERE partition=?')
+            .get(partition);
+        return { count: row?.count ?? 0, bytes: row?.bytes ?? 0 };
+    }
+}

package/dist/sqlite-dialect.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared SQLite dialect for the two SQLite-family storages: `bun:sqlite`
+ * (synchronous, `SqliteServerStorage`) and Cloudflare D1 (async,
+ * `D1ServerStorage`). D1 *is* SQLite — same DDL, same statement grammar,
+ * same `?` positional placeholders, same `INSERT OR REPLACE` / `INSERT OR
+ * IGNORE` upsert idioms — so the schema and the value (de)serialization are
+ * genuinely common ground and live here.
+ *
+ * What is NOT shared: statement *execution*. `bun:sqlite` is sync
+ * (`db.query(sql).get(...)`) and D1 is async (`await
+ * db.prepare(sql).bind(...).all()`); a shared execution layer would have to
+ * pick one calling convention and adapt the other, which is uglier than two
+ * thin storage classes that each speak their driver's native shape while
+ * importing the same SQL text and codecs from here (TODO §4.2 judgment
+ * call — "clean parallel implementation against the storage contract").
+ * Both classes run the identical `test/storage-contract.ts`, so the
+ * behavior is held key-for-key regardless.
+ */
+import type { ScopeMap } from '@syncular/core';
+import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+/**
+ * Schema DDL — one statement per `;`-delimited chunk. `bun:sqlite` applies
+ * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
+ * separately (its `prepare`/`batch` API is one statement per call). Types
+ * are SQLite's: `INTEGER`/`TEXT`/`BLOB`. Scopes are stored as JSON `TEXT`
+ * (no JSONB on SQLite), payloads as `BLOB`.
+ *
+ * The inverted scope index carries the ordered column (`commit_seq` /
+ * `row_id`) last in the PRIMARY KEY, so the candidate scan is an index
+ * range that returns already-ordered rows — the same covering-index shape
+ * the Postgres storage documents (§3.1, REVISE B2 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_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_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\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";
+/** 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. */
+export declare function placeholders(count: number): string;
+/** Serialize a push result to the JSON `TEXT` stored in `sync_push_results`. */
+export declare function serializePushResult(result: StoredPushResult): string;
+export declare function deserializePushResult(text: string): StoredPushResult;
+/** Row-record shape the SQLite `SELECT`s in both storages return. */
+export interface SqliteRowRecord {
+    row_id: string;
+    server_version: number;
+    scopes: string;
+    payload: Uint8Array;
+}
+export interface SqliteChangeRecord {
+    tbl: string;
+    row_id: string;
+    op: number;
+    row_version: number | null;
+    scopes: string;
+    payload: Uint8Array | null;
+}
+/** `bun:sqlite` returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
+export declare function asUint8Array(value: unknown): Uint8Array;
+export declare function toStoredRow(record: SqliteRowRecord): StoredRow;
+export declare function toStoredChange(record: SqliteChangeRecord): StoredChange;
+/**
+ * One result row of `commitWindowPageSql` (candidate LEFT JOIN commit meta
+ * LEFT JOIN changes): meta/change columns are NULL when the joined row
+ * vanished (see the builder's LEFT JOIN contract). `payload` is a BLOB —
+ * `bun:sqlite` hands back `Uint8Array`, D1 `ArrayBuffer`; `toStoredChange`
+ * normalizes via `asUint8Array`.
+ */
+export interface SqliteCommitWindowRecord {
+    commit_seq: number;
+    actor_id: string | null;
+    created_at_ms: number | null;
+    tbl: string | null;
+    row_id: string | null;
+    op: number | null;
+    row_version: number | null;
+    scopes: string | null;
+    payload: Uint8Array | null;
+}
+/**
+ * Fold one `commitWindowPageSql` page into commits, preserving the exact
+ * semantics of the old per-candidate loop:
+ *
+ *   - rows arrive ordered (commit_seq, idx); consecutive rows with the same
+ *     `commit_seq` are one candidate commit;
+ *   - every candidate advances the cursor (`lastSeq`) — including vanished
+ *     commits (NULL meta) and commits whose changes all fail the exact
+ *     multi-variable scope verification (`matchesEffective`);
+ *   - a commit is emitted only with its matching changes, in `idx` order;
+ *   - stops after the commit that accumulates at least `remaining` matching
+ *     changes (never splitting a commit).
+ *
+ * `candidateCount` counts the processed candidates so the caller can detect
+ * a short page (window exhausted) exactly as it did with the old candidate
+ * query.
+ */
+export declare function collectCommitWindowPage(records: readonly SqliteCommitWindowRecord[], scopeFilter: ScopeMap, remaining: number): {
+    commits: StoredCommit[];
+    delivered: number;
+    lastSeq: number;
+    candidateCount: number;
+};

package/dist/sqlite-dialect.js

@@ -0,0 +1,250 @@
+import { matchesEffective } from './scopes.js';
+/**
+ * Schema DDL — one statement per `;`-delimited chunk. `bun:sqlite` applies
+ * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
+ * separately (its `prepare`/`batch` API is one statement per call). Types
+ * are SQLite's: `INTEGER`/`TEXT`/`BLOB`. Scopes are stored as JSON `TEXT`
+ * (no JSONB on SQLite), payloads as `BLOB`.
+ *
+ * The inverted scope index carries the ordered column (`commit_seq` /
+ * `row_id`) last in the PRIMARY KEY, so the candidate scan is an index
+ * range that returns already-ordered rows — the same covering-index shape
+ * the Postgres storage documents (§3.1, REVISE B2 performance-by-
+ * construction).
+ */
+export const SQLITE_DDL = `
+CREATE TABLE IF NOT EXISTS sync_partitions(
+  partition TEXT PRIMARY KEY,
+  max_commit_seq INTEGER NOT NULL DEFAULT 0,
+  horizon_seq INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS sync_row_scopes(
+  partition TEXT NOT NULL, tbl TEXT NOT NULL,
+  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
+  PRIMARY KEY(partition, tbl, var, value, row_id)
+);
+CREATE TABLE IF NOT EXISTS sync_commits(
+  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,
+  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
+  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY(partition, commit_seq)
+);
+CREATE INDEX IF NOT EXISTS sync_commits_by_time
+  ON sync_commits(partition, created_at_ms);
+CREATE TABLE IF NOT EXISTS sync_changes(
+  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,
+  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,
+  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,
+  PRIMARY KEY(partition, commit_seq, idx)
+);
+CREATE INDEX IF NOT EXISTS sync_changes_by_table
+  ON sync_changes(partition, commit_seq, tbl, idx);
+CREATE TABLE IF NOT EXISTS sync_change_scopes(
+  partition TEXT NOT NULL, tbl TEXT NOT NULL,
+  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,
+  PRIMARY KEY(partition, tbl, var, value, commit_seq)
+);
+CREATE TABLE IF NOT EXISTS sync_push_results(
+  partition TEXT NOT NULL, client_id TEXT NOT NULL,
+  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,
+  PRIMARY KEY(partition, client_id, client_commit_id)
+);
+CREATE TABLE IF NOT EXISTS sync_clients(
+  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
+  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY(partition, client_id)
+);
+CREATE TABLE IF NOT EXISTS sync_blob_refs(
+  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
+  blob_id TEXT NOT NULL,
+  PRIMARY KEY(partition, tbl, row_id, blob_id)
+);
+CREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob
+  ON sync_blob_refs(partition, blob_id);
+`;
+/** Split the DDL into individual statements (D1 applies them one by one). */
+export function sqliteDdlStatements() {
+    return SQLITE_DDL.split(';')
+        .map((statement) => statement.trim())
+        .filter((statement) => statement.length > 0);
+}
+/** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
+export function placeholders(count) {
+    return new Array(count).fill('?').join(',');
+}
+// -- value (de)serialization, shared by both SQLite storages ----------------
+/** Runtime-neutral base64 (no `Buffer` — Workers-safe) for push results. */
+function bytesToBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function base64ToBytes(text) {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/** Serialize a push result to the JSON `TEXT` stored in `sync_push_results`. */
+export function serializePushResult(result) {
+    return JSON.stringify({
+        status: result.status,
+        ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
+        results: result.results.map((record) => {
+            if (record.status === 'conflict') {
+                return {
+                    opIndex: record.opIndex,
+                    status: record.status,
+                    code: record.code,
+                    message: record.message,
+                    serverVersion: record.serverVersion,
+                    serverRow: bytesToBase64(record.serverRow),
+                };
+            }
+            if (record.status === 'error') {
+                return {
+                    opIndex: record.opIndex,
+                    status: record.status,
+                    code: record.code,
+                    message: record.message,
+                    retryable: record.retryable,
+                };
+            }
+            return { opIndex: record.opIndex, status: record.status };
+        }),
+    });
+}
+export function deserializePushResult(text) {
+    const parsed = JSON.parse(text);
+    const results = parsed.results.map((record) => {
+        if (record.status === 'conflict') {
+            return {
+                opIndex: record.opIndex,
+                status: 'conflict',
+                code: record.code ?? '',
+                message: record.message ?? '',
+                serverVersion: record.serverVersion ?? 0,
+                serverRow: base64ToBytes(record.serverRow ?? ''),
+            };
+        }
+        if (record.status === 'error') {
+            return {
+                opIndex: record.opIndex,
+                status: 'error',
+                code: record.code ?? '',
+                message: record.message ?? '',
+                retryable: record.retryable ?? false,
+            };
+        }
+        return { opIndex: record.opIndex, status: 'applied' };
+    });
+    return {
+        status: parsed.status,
+        ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+        results,
+    };
+}
+/** `bun:sqlite` returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
+export function asUint8Array(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (Array.isArray(value))
+        return new Uint8Array(value);
+    throw new Error(`expected a BLOB column, got ${typeof value}`);
+}
+export function toStoredRow(record) {
+    return {
+        rowId: record.row_id,
+        serverVersion: record.server_version,
+        scopes: JSON.parse(record.scopes),
+        payload: asUint8Array(record.payload),
+    };
+}
+export function toStoredChange(record) {
+    return {
+        table: record.tbl,
+        rowId: record.row_id,
+        op: record.op === 1 ? 'upsert' : 'delete',
+        ...(record.row_version !== null ? { rowVersion: record.row_version } : {}),
+        scopes: JSON.parse(record.scopes),
+        ...(record.payload !== null
+            ? { payload: asUint8Array(record.payload) }
+            : {}),
+    };
+}
+/**
+ * Fold one `commitWindowPageSql` page into commits, preserving the exact
+ * semantics of the old per-candidate loop:
+ *
+ *   - rows arrive ordered (commit_seq, idx); consecutive rows with the same
+ *     `commit_seq` are one candidate commit;
+ *   - every candidate advances the cursor (`lastSeq`) — including vanished
+ *     commits (NULL meta) and commits whose changes all fail the exact
+ *     multi-variable scope verification (`matchesEffective`);
+ *   - a commit is emitted only with its matching changes, in `idx` order;
+ *   - stops after the commit that accumulates at least `remaining` matching
+ *     changes (never splitting a commit).
+ *
+ * `candidateCount` counts the processed candidates so the caller can detect
+ * a short page (window exhausted) exactly as it did with the old candidate
+ * query.
+ */
+export function collectCommitWindowPage(records, scopeFilter, remaining) {
+    const commits = [];
+    let delivered = 0;
+    let lastSeq = 0;
+    let candidateCount = 0;
+    let i = 0;
+    while (i < records.length) {
+        const head = records[i];
+        if (head === undefined)
+            break;
+        const seq = head.commit_seq;
+        candidateCount += 1;
+        lastSeq = seq;
+        const changes = [];
+        for (; i < records.length; i++) {
+            const record = records[i];
+            if (record === undefined || record.commit_seq !== seq)
+                break;
+            // NULL tbl: a candidate with no change rows for the table (LEFT JOIN
+            // contract) — it still advanced the cursor above.
+            if (record.tbl === null ||
+                record.row_id === null ||
+                record.op === null ||
+                record.scopes === null) {
+                continue;
+            }
+            const change = toStoredChange({
+                tbl: record.tbl,
+                row_id: record.row_id,
+                op: record.op,
+                row_version: record.row_version,
+                scopes: record.scopes,
+                payload: record.payload,
+            });
+            if (matchesEffective(change.scopes, scopeFilter))
+                changes.push(change);
+        }
+        // NULL meta: the commit vanished — cursor advanced, nothing emitted.
+        if (head.actor_id === null || head.created_at_ms === null)
+            continue;
+        if (changes.length === 0)
+            continue;
+        commits.push({
+            commitSeq: seq,
+            createdAtMs: head.created_at_ms,
+            actorId: head.actor_id,
+            changes,
+        });
+        delivered += changes.length;
+        if (delivered >= remaining)
+            break;
+    }
+    return { commits, delivered, lastSeq, candidateCount };
+}

package/dist/sqlite-image.d.ts

@@ -0,0 +1,27 @@
+import type { CompiledTable } from './schema.js';
+import type { StoredRow } from './storage.js';
+/** The §5.6 version column as it appears inside a sqlite image (§5.3). */
+export declare const IMAGE_VERSION_COLUMN = "_syncular_version";
+/** The §5.3 metadata table name. */
+export declare const IMAGE_METADATA_TABLE = "_syncular_segment";
+export interface SqliteImageInput {
+    readonly table: CompiledTable;
+    readonly schemaVersion: number;
+    readonly asOfCommitSeq: number;
+    readonly scopeDigest: string;
+    readonly rows: readonly StoredRow[];
+}
+/**
+ * The §5.3 image-builder capability, injected through
+ * `SyncServerConfig.sqliteImageBuilder` (TODO §4.2). Building an image needs
+ * a real SQLite engine (`bun:sqlite` here), which is not available on every
+ * runtime — Cloudflare Workers has none. So the core takes the builder as an
+ * optional capability rather than importing `bun:sqlite` on the pull path:
+ * a Bun/Node host passes `buildSqliteImage`; a Workers host omits it and the
+ * pull serves the rows lane (§5.3 clients advertise sqlite as an *accept*,
+ * never a requirement — the host chooses the served format from what it can
+ * produce; this is a support floor, not a fallback).
+ */
+export type SqliteImageBuilder = (input: SqliteImageInput) => Uint8Array;
+/** Build the §5.3 image bytes for a whole-table snapshot. */
+export declare const buildSqliteImage: SqliteImageBuilder;