@syncular/server 0.1.3 → 0.2.1

package/dist/relational-rows.js

@@ -0,0 +1,514 @@
+/**
+ * Relational current-row storage (DESIGN-relational-server-storage.md).
+ *
+ * Every synced table is a REAL table in the server database — the app's
+ * columns with proper type affinities, queryable with plain SQL/joins/BI —
+ * plus five `_sync_*` meta columns:
+ *
+ *   _sync_partition       TEXT      partition key (multi-partition servers
+ *                                   share one database; same app PK in two
+ *                                   partitions must coexist)
+ *   _sync_row_id          TEXT      the change rowId (§2.2) — the string
+ *                                   rendering of the app PK. The storage key
+ *                                   stays TEXT so lookup and scan-pagination
+ *                                   semantics are byte-identical to the old
+ *                                   generic store regardless of the PK's type.
+ *   _sync_server_version  INTEGER   §2.2 server version
+ *   _sync_scopes          TEXT/JSONB the stored-scope map the §3.4 authz read
+ *                                   consumes (also present as real columns;
+ *                                   the map is cheaper to read back)
+ *   _sync_payload         BLOB/BYTEA the verbatim row-codec bytes — the wire
+ *                                   source of truth. The serve path reads
+ *                                   THIS, never re-encodes from typed columns,
+ *                                   so sync round-trips are byte-identical by
+ *                                   construction. Typed columns are a
+ *                                   queryable projection.
+ *
+ * PRIMARY KEY (_sync_partition, _sync_row_id).
+ *
+ * The typed columns are written from `decodeRow(payload)` in the same
+ * statement as the payload, so projection and payload cannot drift except
+ * through a codec bug — which the round-trip contract tests would catch.
+ *
+ * Dialect notes:
+ * - postgres maps `json` → JSONB (queryable: `->>`, GIN). JSONB normalizes
+ *   bytes, which is safe because the wire never reads typed columns.
+ *   A json value that fails to parse binds NULL on postgres (the payload
+ *   still holds it verbatim); sqlite stores the text as-is.
+ * - D1's JSON transport represents integers as JS doubles; app integer
+ *   columns beyond 2^53 lose precision in the PROJECTION only — the
+ *   payload is exact, sync is unaffected.
+ * - Migration-added columns (ALTER TABLE ADD COLUMN) are always nullable at
+ *   the DB layer: SQLite cannot add a NOT NULL column without a default, and
+ *   the row codec — not the DB — is the type authority. Fresh CREATEs carry
+ *   NOT NULL per the schema.
+ */
+import { decodeRow, encodeRow, } from '@syncular/core';
+export const SYNC_PARTITION_COLUMN = '_sync_partition';
+export const SYNC_ROW_ID_COLUMN = '_sync_row_id';
+export const SYNC_VERSION_COLUMN = '_sync_server_version';
+export const SYNC_SCOPES_COLUMN = '_sync_scopes';
+export const SYNC_PAYLOAD_COLUMN = '_sync_payload';
+/** SQL-standard identifier quoting (both dialects). */
+export function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** §5.3-style type affinities, per dialect (DESIGN type-mapping table). */
+export function columnSqlType(column, dialect) {
+    if (dialect === 'postgres') {
+        switch (column.type) {
+            case 'string':
+            case 'blob_ref':
+                return 'TEXT';
+            case 'json':
+                return 'JSONB';
+            case 'integer':
+                return 'BIGINT';
+            case 'float':
+                return 'DOUBLE PRECISION';
+            case 'boolean':
+                return 'BOOLEAN';
+            case 'bytes':
+            case 'crdt':
+                return 'BYTEA';
+            default:
+                throw new Error(`unsupported column type: ${String(column.type)}`);
+        }
+    }
+    switch (column.type) {
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            return 'TEXT';
+        case 'integer':
+            return 'INTEGER';
+        case 'float':
+            return 'REAL';
+        case 'boolean':
+            return 'INTEGER';
+        case 'bytes':
+        case 'crdt':
+            return 'BLOB';
+        default:
+            throw new Error(`unsupported column type: ${String(column.type)}`);
+    }
+}
+/**
+ * The full column list of a relational row table, in INSERT order:
+ * partition, row id, app columns (schema order; only when the table is
+ * materialized), version, scopes, payload.
+ */
+export function tableColumnNames(table) {
+    return [
+        SYNC_PARTITION_COLUMN,
+        SYNC_ROW_ID_COLUMN,
+        ...(table.materialize ? table.columns.map((column) => column.name) : []),
+        SYNC_VERSION_COLUMN,
+        SYNC_SCOPES_COLUMN,
+        SYNC_PAYLOAD_COLUMN,
+    ];
+}
+/** CREATE TABLE IF NOT EXISTS for one app table. */
+export function createTableDdl(table, dialect) {
+    const versionType = dialect === 'postgres' ? 'BIGINT' : 'INTEGER';
+    const scopesType = dialect === 'postgres' ? 'JSONB' : 'TEXT';
+    const payloadType = dialect === 'postgres' ? 'BYTEA' : 'BLOB';
+    const defs = [
+        `${quoteIdent(SYNC_PARTITION_COLUMN)} TEXT NOT NULL`,
+        `${quoteIdent(SYNC_ROW_ID_COLUMN)} TEXT NOT NULL`,
+        ...(table.materialize
+            ? table.columns.map((column) => {
+                const notNull = column.nullable ? '' : ' NOT NULL';
+                return `${quoteIdent(column.name)} ${columnSqlType(column, dialect)}${notNull}`;
+            })
+            : []),
+        `${quoteIdent(SYNC_VERSION_COLUMN)} ${versionType} NOT NULL`,
+        `${quoteIdent(SYNC_SCOPES_COLUMN)} ${scopesType} NOT NULL`,
+        `${quoteIdent(SYNC_PAYLOAD_COLUMN)} ${payloadType} NOT NULL`,
+        `PRIMARY KEY (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)})`,
+    ];
+    return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${defs.join(', ')})`;
+}
+/**
+ * ALTER TABLE ADD COLUMN statements for schema columns missing from
+ * `existingColumns` (introspected). Added columns are nullable (header note).
+ */
+export function addColumnDdl(table, existingColumns, dialect) {
+    if (!table.materialize)
+        return [];
+    const out = [];
+    for (const column of table.columns) {
+        if (existingColumns.has(column.name))
+            continue;
+        out.push(`ALTER TABLE ${quoteIdent(table.name)} ADD COLUMN ${quoteIdent(column.name)} ${columnSqlType(column, dialect)}`);
+    }
+    return out;
+}
+/**
+ * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
+ * (DESIGN "user indexes" — the same names/columns the client materializes;
+ * cross-table index-name uniqueness is the user's schema concern, exactly
+ * as it is client-side).
+ */
+export function createIndexDdl(table) {
+    // User indexes name app columns — nothing to index without the projection.
+    if (!table.materialize)
+        return [];
+    return table.indexes.map((index) => {
+        const unique = index.unique ? 'UNIQUE ' : '';
+        const columns = index.columns
+            .map((column) => quoteIdent(column))
+            .join(', ');
+        return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)} (${columns})`;
+    });
+}
+/**
+ * Convert one decoded row value to its SQL bind value.
+ * - boolean → 0/1 on sqlite (INTEGER affinity), native on postgres;
+ * - json → the raw string on sqlite; on postgres, NULL if unparseable
+ *   (JSONB would reject the INSERT — the payload keeps the verbatim value);
+ * - everything else binds naturally (Uint8Array → BLOB/BYTEA).
+ */
+export function toSqlValue(column, value, dialect) {
+    if (value === null)
+        return null;
+    if (column.type === 'boolean' && dialect === 'sqlite') {
+        return value === true ? 1 : 0;
+    }
+    if (column.type === 'json' && dialect === 'postgres') {
+        if (typeof value !== 'string')
+            return null;
+        try {
+            JSON.parse(value);
+            return value;
+        }
+        catch {
+            return null;
+        }
+    }
+    return value;
+}
+/**
+ * Bind values for an upsert, in `tableColumnNames` order. Decodes the
+ * payload once; the typed columns and the verbatim payload land in one
+ * statement, so they cannot drift.
+ */
+export function upsertValues(table, partition, row, dialect) {
+    // A non-materialized table skips the decode entirely — the upsert is a
+    // five-column meta write (the old blob-store cost).
+    const projection = table.materialize
+        ? decodeRow(table.columns, row.payload)
+        : undefined;
+    return [
+        partition,
+        row.rowId,
+        ...(projection !== undefined
+            ? table.columns.map((column, index) => toSqlValue(column, projection[index] ?? null, dialect))
+            : []),
+        row.serverVersion,
+        JSON.stringify(row.scopes),
+        row.payload,
+    ];
+}
+function placeholderList(count, dialect) {
+    if (dialect === 'sqlite')
+        return new Array(count).fill('?').join(',');
+    const out = [];
+    for (let i = 1; i <= count; i++)
+        out.push(`$${i}`);
+    return out.join(',');
+}
+/** Upsert statement text (bind with `upsertValues`). */
+export function upsertSql(table, dialect) {
+    const names = tableColumnNames(table);
+    const quoted = names.map((name) => quoteIdent(name)).join(', ');
+    const values = placeholderList(names.length, dialect);
+    if (dialect === 'sqlite') {
+        // INSERT OR REPLACE keys on the (_sync_partition, _sync_row_id) PK.
+        return `INSERT OR REPLACE INTO ${quoteIdent(table.name)} (${quoted}) VALUES (${values})`;
+    }
+    const updates = names
+        .slice(2) // partition + row id are the conflict key
+        .map((name) => `${quoteIdent(name)}=EXCLUDED.${quoteIdent(name)}`)
+        .join(', ');
+    return `INSERT INTO ${quoteIdent(table.name)} (${quoted}) VALUES (${values})
+     ON CONFLICT (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)}) DO UPDATE SET ${updates}`;
+}
+/**
+ * SELECT one stored row. Aliased to the legacy record shape
+ * (`row_id`/`server_version`/`scopes`/`payload`) so the existing
+ * `toStoredRow` converters keep working. Params: [partition, rowId].
+ */
+export function selectRowSql(table, dialect) {
+    const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
+    return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
+}
+/**
+ * One-round-trip page scan for `scanRows`: candidates from the inverted
+ * scope index (ordered + LIMITed at the covering `sync_row_scopes` PK —
+ * exactly the old candidate query, so the index-first posture is unchanged)
+ * LEFT JOINed to the row table, so a whole page arrives in ONE statement
+ * instead of one lookup per candidate. That per-candidate lookup was the
+ * cold-bootstrap hot path: a 100k-row snapshot on Postgres paid ~100k
+ * network round-trips (~10 s at 0.1 ms each) before this join.
+ *
+ * LEFT JOIN (not INNER): a candidate whose row vanished (index entry
+ * without a row) must still reach the caller — its `row_id` advances the
+ * keyset cursor — so it comes back with NULL payload rather than
+ * disappearing from the page.
+ *
+ * Bind order:
+ *   - postgres: [partition, tbl, var, ...values, afterRowId, limit]
+ *     (the join reuses `$1` for the partition);
+ *   - sqlite:   [partition, tbl, var, ...values, afterRowId, limit,
+ *     partition] (positional `?` — the partition binds again for the join).
+ */
+export function scanRowPageSql(table, valueCount, dialect) {
+    const p = (n) => (dialect === 'sqlite' ? '?' : `$${n}`);
+    const values = [];
+    for (let i = 0; i < valueCount; i++)
+        values.push(p(4 + i));
+    const after = p(4 + valueCount);
+    const limit = p(5 + valueCount);
+    const joinPartition = dialect === 'sqlite' ? '?' : '$1';
+    return `SELECT c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload
+     FROM (SELECT DISTINCT row_id FROM sync_row_scopes
+       WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values.join(',')})
+         AND row_id>${after}
+       ORDER BY row_id LIMIT ${limit}) c
+     LEFT JOIN ${quoteIdent(table.name)} r
+       ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=${joinPartition} AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=c.row_id
+     ORDER BY c.row_id`;
+}
+/**
+ * One-round-trip page read for `readCommitWindow` (sync_* tables only; it
+ * lives here beside `scanRowPageSql` because it is the same join-the-index
+ * posture, dialect-parameterized the same way): candidates from the inverted
+ * change-scope index (ordered + LIMITed at the covering `sync_change_scopes`
+ * PK — exactly the old candidate query, so the index-first invariant of
+ * `CommitWindowQuery` is unchanged) LEFT JOINed to the commit metadata and
+ * to the commit's changes for the table, so a whole window page arrives in
+ * ONE statement instead of 1 + 2×candidates round trips. This is the
+ * incremental-pull hot path — it runs on every sync round; before the join a
+ * 500-candidate catch-up window on Postgres paid ~1000 network round trips.
+ *
+ * LEFT JOIN (not INNER): a candidate whose commit vanished (scope-index
+ * entry without a commit/changes row) must still reach the caller — its
+ * `commit_seq` advances the window cursor — so it comes back with NULL
+ * meta/change columns rather than disappearing from the page.
+ *
+ * Rows arrive ordered (commit_seq, idx): oldest-first commits, each commit's
+ * change rows consecutive in `idx` order — the caller groups consecutive
+ * rows and verifies the full multi-variable scope match in JS.
+ *
+ * Bind order:
+ *   - postgres: [partition, tbl, var, ...values, afterSeq, throughSeq,
+ *     limit] (the joins reuse `$1`/`$2`);
+ *   - sqlite:   [partition, tbl, var, ...values, afterSeq, throughSeq,
+ *     limit, partition, partition, tbl] (positional `?` — partition/tbl bind
+ *     again for the joins).
+ */
+export function commitWindowPageSql(valueCount, dialect) {
+    const p = (n) => (dialect === 'sqlite' ? '?' : `$${n}`);
+    const values = [];
+    for (let i = 0; i < valueCount; i++)
+        values.push(p(4 + i));
+    const after = p(4 + valueCount);
+    const through = p(5 + valueCount);
+    const limit = p(6 + valueCount);
+    const joinPartition = dialect === 'sqlite' ? '?' : '$1';
+    const joinTbl = dialect === 'sqlite' ? '?' : '$2';
+    return `SELECT c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,
+       ch.tbl AS tbl, ch.row_id AS row_id, ch.op AS op, ch.row_version AS row_version, ch.scopes AS scopes, ch.payload AS payload
+     FROM (SELECT DISTINCT commit_seq FROM sync_change_scopes
+       WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values.join(',')})
+         AND commit_seq>${after} AND commit_seq<=${through}
+       ORDER BY commit_seq LIMIT ${limit}) c
+     LEFT JOIN sync_commits m
+       ON m.partition=${joinPartition} AND m.commit_seq=c.commit_seq
+     LEFT JOIN sync_changes ch
+       ON ch.partition=${joinPartition} AND ch.commit_seq=c.commit_seq AND ch.tbl=${joinTbl}
+     ORDER BY c.commit_seq, ch.idx`;
+}
+/** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
+export function selectRowScopesSql(table, dialect) {
+    const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
+    return `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
+}
+/** DELETE one stored row. Params: [partition, rowId]. */
+export function deleteRowSql(table, dialect) {
+    const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
+    return `DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
+}
+/**
+ * The schema-version marker table gating DDL work (DESIGN "server-side
+ * schema migration"): `ensureSchema` compares the stored version and skips
+ * all introspection/DDL when it matches — one cheap read per storage
+ * instance (relevant for D1's per-request instantiation).
+ *
+ * `layouts` persists each table's column layout (name/type/nullable, the
+ * exact inputs the row codec's byte layout depends on) as of the LAST
+ * applied schema version. The codec is strict — a payload only decodes
+ * under the column list it was encoded with — so a version bump MUST
+ * re-encode stored payloads (append trailing NULLs for added columns);
+ * decoding the old bytes requires the old layout, and this column is where
+ * it lives.
+ */
+export const SCHEMA_META_DDL_SQLITE = `CREATE TABLE IF NOT EXISTS sync_schema_meta(
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  schema_version INTEGER NOT NULL,
+  layouts TEXT NOT NULL DEFAULT '{}'
+)`;
+export const SCHEMA_META_DDL_POSTGRES = `CREATE TABLE IF NOT EXISTS sync_schema_meta(
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  schema_version BIGINT NOT NULL,
+  layouts TEXT NOT NULL DEFAULT '{}'
+)`;
+/** The layouts JSON persisted alongside the schema version marker. */
+export function layoutsOf(schema) {
+    const out = {};
+    for (const table of schema.tables.values()) {
+        out[table.name] = table.columns.map((column) => ({
+            name: column.name,
+            type: column.type,
+            nullable: column.nullable,
+        }));
+    }
+    return JSON.stringify(out);
+}
+export function parseLayouts(json) {
+    if (json === null || json === undefined || json.length === 0)
+        return {};
+    return JSON.parse(json);
+}
+/**
+ * Enforce the migration subset on a table's column list: the old layout
+ * must be an exact prefix (same name, type, nullability) of the new one,
+ * and appended columns must be nullable (there is no default to backfill).
+ * Returns `true` iff columns were appended.
+ */
+export function assertAppendOnlyMigration(tableName, oldLayout, table) {
+    if (oldLayout.length > table.columns.length) {
+        throw new Error(`table ${JSON.stringify(tableName)}: the schema removed columns — only CREATE TABLE / ADD COLUMN / CREATE INDEX migrations are supported`);
+    }
+    for (let i = 0; i < oldLayout.length; i++) {
+        const before = oldLayout[i];
+        const after = table.columns[i];
+        if (before === undefined ||
+            after === undefined ||
+            before.name !== after.name ||
+            before.type !== after.type ||
+            before.nullable !== after.nullable) {
+            throw new Error(`table ${JSON.stringify(tableName)}: column ${i} changed (${JSON.stringify(before)} → ${JSON.stringify({ name: after?.name, type: after?.type, nullable: after?.nullable })}) — only appending nullable columns is supported`);
+        }
+    }
+    for (let i = oldLayout.length; i < table.columns.length; i++) {
+        const added = table.columns[i];
+        if (added !== undefined && !added.nullable) {
+            throw new Error(`table ${JSON.stringify(tableName)}: added column ${JSON.stringify(added.name)} must be nullable — existing rows have no value to backfill`);
+        }
+    }
+    return oldLayout.length < table.columns.length;
+}
+/**
+ * Re-encode an old-layout payload under the current columns: decode with
+ * the layout it was written under, append NULLs for the added columns,
+ * encode with the current column list. The write path (§3.4 scope-strip,
+ * CRDT merge, conflict serverRow) and the bootstrap serve path both decode
+ * stored payloads under the CURRENT schema, so this migration is a
+ * correctness requirement of the version bump, not an optimization.
+ */
+export function migratePayload(oldLayout, table, payload) {
+    const values = decodeRow(oldLayout, payload);
+    while (values.length < table.columns.length)
+        values.push(null);
+    return encodeRow(table.columns, values);
+}
+/**
+ * Keyset-paged scan of a row table for the migration rewrite.
+ * Params: [afterPartition, afterRowId, limit].
+ */
+export function selectRowsForRewriteSql(table, dialect) {
+    const p = dialect === 'sqlite' ? ['?', '?', '?'] : ['$1', '$2', '$3'];
+    return `SELECT ${quoteIdent(SYNC_PARTITION_COLUMN)} AS partition, ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload
+     FROM ${quoteIdent(table.name)}
+     WHERE (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)}) > (${p[0]}, ${p[1]})
+     ORDER BY ${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)}
+     LIMIT ${p[2]}`;
+}
+/**
+ * Rewrite one row during a migration: refresh the projection columns (when
+ * materialized) and the payload. Bind with `rewriteValues`.
+ */
+export function rewriteRowSql(table, dialect) {
+    const sets = [];
+    let i = 1;
+    if (table.materialize) {
+        for (const column of table.columns) {
+            sets.push(`${quoteIdent(column.name)}=${dialect === 'sqlite' ? '?' : `$${i}`}`);
+            i++;
+        }
+    }
+    sets.push(`${quoteIdent(SYNC_PAYLOAD_COLUMN)}=${dialect === 'sqlite' ? '?' : `$${i}`}`);
+    i++;
+    const wherePartition = dialect === 'sqlite' ? '?' : `$${i}`;
+    const whereRowId = dialect === 'sqlite' ? '?' : `$${i + 1}`;
+    return `UPDATE ${quoteIdent(table.name)} SET ${sets.join(', ')} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${wherePartition} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${whereRowId}`;
+}
+/** Bind values for `rewriteRowSql` from the (already migrated) payload. */
+export function rewriteValues(table, partition, rowId, payload, dialect) {
+    const out = [];
+    if (table.materialize) {
+        const values = decodeRow(table.columns, payload);
+        for (let i = 0; i < table.columns.length; i++) {
+            const column = table.columns[i];
+            if (column === undefined)
+                continue;
+            out.push(toSqlValue(column, values[i] ?? null, dialect));
+        }
+    }
+    out.push(payload, partition, rowId);
+    return out;
+}
+/**
+ * What the migration rewrite phase must do for one table, derived from the
+ * persisted layouts + the physical columns present before this run.
+ *
+ * - `migrate`: the layout gained columns — every stored payload re-encodes
+ *   under the new column list (correctness; see `migratePayload`).
+ * - `backfill`: the table just gained physical projection columns whose
+ *   values exist in stored payloads (materialization flipped on) — the
+ *   projection refreshes from the payload, no re-encode.
+ */
+export function rewritePlan(table, oldLayout, physicalColumnsBefore) {
+    if (oldLayout === undefined || physicalColumnsBefore === undefined) {
+        // Fresh table (or a pre-layout database, which cannot be reasoned
+        // about): nothing stored to rewrite.
+        return { migrate: false, backfill: false };
+    }
+    const migrate = assertAppendOnlyMigration(table.name, oldLayout, table);
+    const backfill = table.materialize &&
+        table.columns.some((column, index) => index < oldLayout.length && // value exists in old payloads
+            !physicalColumnsBefore.has(column.name));
+    return { migrate, backfill };
+}
+/**
+ * Every DDL statement to bring a database from `existingColumnsByTable`
+ * (introspected; a missing key = table absent) to `schema`: CREATE TABLE
+ * for absent tables, ADD COLUMN for missing columns, CREATE INDEX for the
+ * declared user indexes — exactly the migration subset.
+ */
+export function schemaDdl(schema, existingColumnsByTable, dialect) {
+    const out = [];
+    for (const table of schema.tables.values()) {
+        const existing = existingColumnsByTable.get(table.name);
+        if (existing === undefined) {
+            out.push(createTableDdl(table, dialect));
+        }
+        else {
+            out.push(...addColumnDdl(table, existing, dialect));
+        }
+        out.push(...createIndexDdl(table));
+    }
+    return out;
+}

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

@@ -0,0 +1,142 @@
+/**
+ * S3-compatible blob store (SPEC.md §5.9.2 durable objects, §5.9.5 delegated
+ * presign) — AWS S3, Cloudflare R2, MinIO. The blob twin of
+ * `s3-segment-store.ts`: same hand-rolled SigV4 over `fetch` (sigv4.ts), same
+ * content-addressed key layout, same LIST-free-on-the-hot-path CAS stats
+ * accumulator. Zero dependencies.
+ *
+ * Key layout (deterministic — every point lookup is a GET/HEAD, never a LIST):
+ *
+ *   {keyPrefix}blob/sha256/{hex}
+ *     The blob bytes, VERBATIM (the object body MUST be exactly the
+ *     content-addressed bytes so a presigned GET serves them directly and the
+ *     client's §5.9.1 hash check passes — blobs are never re-compressed at
+ *     rest, §5.8/§5.9.5). The `byteLength` + optional `mediaType` ride along
+ *     as object user metadata `x-amz-meta-syncular-blob` = base64url(JSON), so
+ *     `get` is a single GET. `createdAtMs` is stored there too so the orphan
+ *     sweep (§5.9.2) can read the upload age without a separate index.
+ *
+ * DURABILITY vs SEGMENT TTL — the honest interface difference (§5.9.2): a
+ * blob referenced by a live row must stay downloadable INDEFINITELY. So,
+ * unlike `S3SegmentStore`, this store writes **no `expiresAtMs`, no S3
+ * lifecycle-expiration mapping, and no TTL config**. Expiry is
+ * REFERENCE-driven, not time-driven: reclamation is the host-scheduled
+ * `sweepOrphanBlobs` (blob-store.ts) deleting only objects no live row
+ * references after a grace period — never a bucket lifecycle rule. Do NOT
+ * put a lifecycle expiration on the `blob/` prefix; it would delete
+ * still-referenced attachments.
+ *
+ * The orphan sweep is the ONLY operation that LISTs: `sweepOrphans` pages
+ * `ListObjectsV2` over the `blob/` prefix (an admin/GC path, off the hot
+ * path) to find candidates, reads each object's `createdAtMs` from its
+ * metadata for the grace check, and DELETEs the unreferenced-and-old ones.
+ */
+import type { BlobRecord, BlobStore, BlobStoreStats } from './blob-store.js';
+import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlIssue } from './signed-url.js';
+export interface S3BlobStoreConfig {
+    /**
+     * Endpoint origin, no bucket, no trailing slash:
+     * AWS `https://s3.<region>.amazonaws.com`,
+     * R2 `https://<account-id>.r2.cloudflarestorage.com`,
+     * MinIO `http://127.0.0.1:9000`. Requests are path-style
+     * (`{endpoint}/{bucket}/{key}`), which all three accept.
+     */
+    readonly endpoint: string;
+    /** AWS region; R2 uses `auto`. */
+    readonly region: string;
+    readonly bucket: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    /** Optional STS session token. */
+    readonly sessionToken?: string;
+    /** Key namespace inside the bucket, e.g. `syncular/`. Default: none. */
+    readonly keyPrefix?: string;
+}
+export declare class S3BlobStore implements BlobStore {
+    #private;
+    constructor(config: S3BlobStoreConfig);
+    /**
+     * `{keyPrefix}blob/{partition}/sha256/{hex}` — the §5.9.5 "signed key embeds
+     * the blobId". Blobs are content-addressed, but download authorization and
+     * the reference index are per-partition, so the same bytes uploaded under
+     * two partitions are two objects (a partition MUST NOT read another's
+     * attachment by guessing a content address). The partition is folded into
+     * the key as a path segment.
+     */
+    objectKeyFor(partition: string, blobId: string): 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>;
+    /**
+     * §5.9.2 orphan sweep — the ONLY LISTing operation. Page `ListObjectsV2`
+     * over `{prefix}blob/{partition}/`, HEAD each object for its `createdAtMs`,
+     * and DELETE the ones both older than `olderThanMs` AND absent from
+     * `referencedBlobIds`. Returns the deleted blobIds. Never deletes a
+     * referenced blob (§5.9.2). Off the hot path — a host-scheduled GC job.
+     */
+    sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    /**
+     * Store-wide counters from the pointer-object accumulator (never a LIST on
+     * the read path). `approximate: true` for the same reasons `S3SegmentStore`
+     * documents: best-effort ETag-CAS maintenance and sweep deletes that may
+     * miss the decrement. Exact within a single writer; a health gauge under
+     * concurrency. Note this is store-WIDE, not partition-scoped, so a shared
+     * bucket reports the whole bucket — the parameter is accepted for interface
+     * parity but the accumulator is one object per store.
+     */
+    stats(_partition: string): Promise<BlobStoreStats>;
+    /**
+     * SigV4 presigned GET for a blob object (§5.9.5 delegated presign). The
+     * signed key embeds the `blobId`; `urlExpiresAtMs` is the provider-enforced
+     * expiry (`X-Amz-Date + X-Amz-Expires`). Issued ONLY after the row-derived
+     * authorization check (§5.9.5) — the caller (blob-handlers) resolves scopes
+     * and tests referencing rows first; the URL is then a short-TTL bearer
+     * grant to exactly those immutable bytes. TTL SHOULD be ≤ 15 minutes;
+     * default 900 s.
+     */
+    presignBlobGet(partition: string, blobId: string, options?: {
+        readonly ttlSeconds?: number;
+        readonly nowMs?: number;
+    }): Promise<SegmentUrlIssue>;
+    /**
+     * SigV4 presigned PUT for a blob object (§5.9.3 direct-to-storage upload).
+     * The blob twin of `presignBlobGet`: the signed key embeds the `blobId`, so
+     * the grant places bytes at exactly the content-addressed key. The store
+     * does NOT recompute the SHA-256 (it is the object store, not the sync
+     * server); integrity is enforced at REFERENCE time — the §5.9.6 push
+     * existence check verifies the object exists (`has`) and every consumer
+     * re-verifies the content address over the received bytes (§5.9.5/§5.1). A
+     * client PUTting bytes that do not hash to `{blobId}` poisons only its own
+     * upload; no honest reference resolves to it. Issued by the upload-grant
+     * handler after host authentication; TTL SHOULD be ≤ 15 min (default 900).
+     */
+    presignBlobPut(partition: string, blobId: string, options?: {
+        readonly ttlSeconds?: number;
+        readonly nowMs?: number;
+    }): Promise<SegmentUrlIssue>;
+}
+/**
+ * Wire an `S3BlobStore` into `SyncServerConfig.blobSignedUrls` as the §5.9.5
+ * delegated-presign scheme for blob downloads:
+ * `blobSignedUrls: s3PresignedBlobUrls(blobStore, { ttlSeconds: 900 })`.
+ * The presigned URL is issued only after the row-derived authorization check
+ * (blob-handlers) — never as a bearer capability minted from the id alone.
+ */
+export declare function s3PresignedBlobUrls(store: S3BlobStore, options?: {
+    readonly ttlSeconds?: number;
+}): BlobPresignConfig;
+/**
+ * Wire an `S3BlobStore` into `SyncServerConfig.blobUploadUrls` as the §5.9.3
+ * presigned-upload (direct-to-storage) scheme:
+ * `blobUploadUrls: s3PresignedBlobUploads(blobStore, { ttlSeconds: 900 })`.
+ * The upload-grant handler issues the presigned PUT only after host
+ * authentication + the size-cap check; the client PUTs bytes straight to the
+ * object store with no host auth (§5.9.3). Integrity stays the content-address
+ * check at reference/download time — never a store-side hash recompute.
+ */
+export declare function s3PresignedBlobUploads(store: S3BlobStore, options?: {
+    readonly ttlSeconds?: number;
+}): BlobUploadPresignConfig;