@syncular/server 0.34.0 → 0.36.0

package/dist/postgres-storage.js

@@ -6,7 +6,7 @@ import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQ
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
 import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
-import { matchesEffective } from './scopes.js';
+import { matchesEffective, sha256Hex } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 /**
@@ -794,23 +794,24 @@ export class PostgresServerStorage {
     #schemaVersion;
     /**
      * Page reads waiting for the end of the current microtask turn, keyed by
-     * statement and fixed params. A pull starts the window read (or first
+     * statement and partition. A pull starts the window read (or first
      * snapshot page) of every subscription before awaiting any of them, so the
-     * reads of one table leave as ONE set-based statement instead of one round
-     * trip per subscription (SYNCULAR-PULL-ROUNDTRIPS-001).
+     * window reads of all tables leave as ONE set-based statement (snapshot
+     * pages as one per table, whose SQL names the table) instead of one round
+     * trip per subscription or table (SYNCULAR-PULL-ROUNDTRIPS-001).
      */
     #pageBatches = new Map();
     constructor(exec) {
         this.#exec = exec;
     }
     /**
-     * Queue one page read into the batch for (`sql`, `partition`, `table`).
-     * The batch runs as a single statement with the queued specs bound as a
-     * JSON array (`$2`); each spec gets its position as `i`, and the result
-     * rows are split back by their `sub` column.
+     * Queue one page read into the batch for (`sql`, `partition`). The batch
+     * runs as a single statement with the queued specs bound as a JSON array
+     * (`$2`); each spec gets its position as `i`, and the result rows are
+     * split back by their `sub` column.
      */
-    #batchedPage(sql, partition, table, spec) {
-        const key = `${sql}\u0000${partition}\u0000${table}`;
+    #batchedPage(sql, partition, spec) {
+        const key = `${sql}\u0000${partition}`;
         let batch = this.#pageBatches.get(key);
         if (batch === undefined) {
             const queued = [];
@@ -819,7 +820,7 @@ export class PostgresServerStorage {
             queueMicrotask(() => {
                 this.#pageBatches.delete(key);
                 const specs = JSON.stringify(queued.map((entry, i) => ({ ...entry.spec, i })));
-                this.#exec.query(sql, [partition, specs, table]).then(({ rows }) => {
+                this.#exec.query(sql, [partition, specs]).then(({ rows }) => {
                     const grouped = queued.map(() => []);
                     for (const row of rows)
                         grouped[asNumber(row.sub)]?.push(row);
@@ -839,22 +840,27 @@ export class PostgresServerStorage {
             });
         });
     }
-    /** Apply the schema DDL (idempotent). Call once before use. */
+    /**
+     * Apply the schema DDL (idempotent). Call once before use. The last
+     * statement records a fingerprint of the applied DDL as the comment of
+     * `sync_schema_meta`; a database that carries the current fingerprint
+     * costs one catalog read instead of the DDL round trips, so a new storage
+     * instance (a Worker isolate, a Durable Object wake) starts fast.
+     */
     async migrate() {
         // Split on the statement boundary so drivers that reject multi-statement
         // query strings (node-postgres extended protocol) still apply each DDL.
-        const statements = POSTGRES_DDL.split(';')
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-        for (const statement of statements) {
-            await this.#exec.query(statement);
-        }
-        await this.#exec.query('ALTER TABLE sync_commits ADD COLUMN IF NOT EXISTS writer_version BIGINT');
-        // Database-side fence: an old binary's INSERT never reaches JS. An absent
-        // `sync_writer_fence` row makes the EXISTS false, so a partition with no
-        // barrier behaves exactly as before. Sent as separate statements because
-        // the dollar-quoted body contains `;`.
-        await this.#exec.query(`CREATE OR REPLACE FUNCTION syncular_writer_fence()
+        // The fence function is sent whole because its dollar-quoted body
+        // contains `;`.
+        const statements = [
+            ...POSTGRES_DDL.split(';')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0),
+            'ALTER TABLE sync_commits ADD COLUMN IF NOT EXISTS writer_version BIGINT',
+            // Database-side fence: an old binary's INSERT never reaches JS. An
+            // absent `sync_writer_fence` row makes the EXISTS false, so a partition
+            // with no barrier behaves exactly as before.
+            `CREATE OR REPLACE FUNCTION syncular_writer_fence()
 RETURNS trigger AS $$
 BEGIN
   IF EXISTS (
@@ -867,11 +873,31 @@ BEGIN
   END IF;
   RETURN NEW;
 END;
-$$ LANGUAGE plpgsql`);
-        await this.#exec.query('DROP TRIGGER IF EXISTS sync_commits_writer_fence ON sync_commits');
-        await this.#exec.query(`CREATE TRIGGER sync_commits_writer_fence
+$$ LANGUAGE plpgsql`,
+            'DROP TRIGGER IF EXISTS sync_commits_writer_fence ON sync_commits',
+            `CREATE TRIGGER sync_commits_writer_fence
 BEFORE INSERT ON sync_commits
-FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
+FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
+            SCHEMA_META_DDL_POSTGRES,
+        ];
+        const fingerprint = `syncular.storage:${await sha256Hex(new TextEncoder().encode(statements.join('\u0000')))}`;
+        // `obj_description` and `to_regclass` of a missing table are NULL, so
+        // the probe never fails. A core table dropped out of band reapplies the
+        // DDL even under the current fingerprint.
+        const { rows } = await this.#exec.query(`SELECT obj_description(to_regclass('sync_schema_meta'), 'pg_class') AS storage,
+              (SELECT count(*)::int
+                 FROM jsonb_array_elements_text($1::text::jsonb) AS core(name)
+                WHERE to_regclass(core.name) IS NULL) AS missing`, [
+            JSON.stringify(statements.flatMap((statement) => /^CREATE TABLE IF NOT EXISTS (\w+)/.exec(statement)?.[1] ?? [])),
+        ]);
+        if (rows[0]?.storage === fingerprint && rows[0].missing === 0)
+            return;
+        for (const statement of statements) {
+            await this.#exec.query(statement);
+        }
+        // The fingerprint is lowercase hex, safe to inline (COMMENT takes no
+        // bound parameter).
+        await this.#exec.query(`COMMENT ON TABLE sync_schema_meta IS '${fingerprint}'`);
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -886,51 +912,71 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         if (this.#schemaVersion === schema.version)
             return;
         await this.migrate();
+        // One statement reads the marker, the incomplete checkpoints of this
+        // version and the physical columns of every app table. The aggregates
+        // leave as text so every driver hands back the same JSON strings.
+        // Columns resolve through `to_regclass`, which follows the session's
+        // `search_path` exactly as the unqualified row queries do:
+        // `current_schema()` names only the first existing schema, so it would
+        // reject a table that resolves later in the path.
+        const { rows: probe } = await this.#exec.query(`SELECT meta.schema_version AS schema_version, meta.layouts AS layouts,
+              (SELECT coalesce(json_agg(json_build_object(
+                        'partition', checkpoint.partition,
+                        'name', checkpoint.name)), '[]'::json)::text
+                 FROM sync_backfill_checkpoints checkpoint
+                WHERE checkpoint.schema_version=$1
+                  AND checkpoint.state<>'activated') AS incomplete,
+              (SELECT coalesce(json_agg(json_build_object(
+                        'tbl', tables.name,
+                        'name', attribute.attname,
+                        'type', format_type(attribute.atttypid, attribute.atttypmod),
+                        'not_null', attribute.attnotnull,
+                        'pk', (SELECT key.position::int
+                                 FROM pg_index pk,
+                                      unnest(pk.indkey::int2[]) WITH ORDINALITY
+                                        AS key(attnum, position)
+                                WHERE pk.indrelid = attribute.attrelid
+                                  AND pk.indisprimary
+                                  AND key.attnum = attribute.attnum))
+                        ORDER BY tables.name, attribute.attnum), '[]'::json)::text
+                 FROM jsonb_array_elements_text($2::text::jsonb) AS tables(name)
+                 JOIN pg_attribute attribute
+                   ON attribute.attrelid = to_regclass(tables.name)
+                WHERE attribute.attnum > 0
+                  AND NOT attribute.attisdropped) AS columns
+         FROM (SELECT 1) AS one
+         LEFT JOIN sync_schema_meta meta ON meta.id=1`, [schema.version, JSON.stringify([...schema.tables.keys()])]);
+        const marker = probe[0];
+        if (marker === undefined) {
+            throw new Error('schema probe returned no row');
+        }
         // The barrier reads stored state: a checkpoint at this schema version that
         // is not activated and that this caller did not declare means this process
         // must not serve. An omitted or empty declaration set declares nothing and
         // is refused here, never treated as a bypass.
         const declarations = checkpoints ?? [];
-        const incomplete = await this.#exec.query(`SELECT partition, name FROM sync_backfill_checkpoints
-        WHERE schema_version=$1 AND state<>'activated'`, [schema.version]);
-        if (incomplete.rows.some((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
+        const incomplete = JSON.parse(marker.incomplete);
+        if (incomplete.some((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
             declaration.name === row.name))) {
             throw new StorageQueryError('sync.storage.checkpoint_incomplete');
         }
-        await this.#exec.query(SCHEMA_META_DDL_POSTGRES);
-        const marker = await this.#exec.query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1');
-        const stored = marker.rows[0] === undefined
+        const stored = marker.schema_version === null || marker.schema_version === undefined
             ? undefined
-            : asNumber(marker.rows[0].schema_version);
+            : asNumber(marker.schema_version);
         if (stored !== undefined && stored > schema.version) {
             throw new Error(`stored schema version ${stored} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
         }
         if (stored !== undefined && stored === schema.version) {
-            assertStoredLayouts(schema, typeof marker.rows[0]?.layouts === 'string'
-                ? marker.rows[0].layouts
-                : undefined);
-            // Resolve through `to_regclass`, which follows the session's
-            // `search_path` exactly as the unqualified row queries do:
-            // `current_schema()` names only the first existing schema, so it would
-            // reject a table that resolves later in the path.
+            assertStoredLayouts(schema, typeof marker.layouts === 'string' ? marker.layouts : undefined);
+            const columns = JSON.parse(marker.columns);
             for (const table of schema.tables.values()) {
-                const { rows } = await this.#exec.query(`SELECT attribute.attname AS name,
-                  format_type(attribute.atttypid, attribute.atttypmod) AS type,
-                  attribute.attnotnull AS not_null,
-                  (SELECT key.position::int
-                     FROM pg_index pk,
-                          unnest(pk.indkey::int2[]) WITH ORDINALITY
-                            AS key(attnum, position)
-                    WHERE pk.indrelid = attribute.attrelid AND pk.indisprimary
-                      AND key.attnum = attribute.attnum) AS pk
-           FROM pg_attribute attribute
-           WHERE attribute.attrelid = to_regclass($1)
-             AND attribute.attnum > 0 AND NOT attribute.attisdropped`, [table.name]);
-                assertPhysicalColumns(table, rows.map((row) => ({
-                    name: row.name,
-                    type: row.type,
-                    notNull: row.not_null,
-                    primaryKeyPosition: row.pk ?? 0,
+                assertPhysicalColumns(table, columns
+                    .filter((column) => column.tbl === table.name)
+                    .map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                    notNull: column.not_null,
+                    primaryKeyPosition: column.pk ?? 0,
                 })), 'postgres');
             }
         }
@@ -941,9 +987,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             // backfill for flipped-on materialization) — all inside one
             // transaction (Postgres DDL is transactional — a failed bump leaves
             // no half-state).
-            const layouts = parseLayouts(typeof marker.rows[0]?.layouts === 'string'
-                ? marker.rows[0].layouts
-                : undefined);
+            const layouts = parseLayouts(typeof marker.layouts === 'string' ? marker.layouts : undefined);
             const retiredTables = retiredTableNames(schema, layouts);
             await this.#exec.transaction(async (client) => {
                 // RFC 0007 migration barrier: `LOCK TABLE ... EXCLUSIVE` is the FIRST
@@ -1431,8 +1475,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             : (query.scopeFilter[firstVariable] ?? []);
         if (firstVariable === undefined || values.length === 0)
             return 0;
-        // Concurrent reads of one table in a pull share one statement.
-        const [row] = await this.#batchedPage(LATEST_SCOPED_CHANGE_BATCH_SQL, partition, query.table, { var: firstVariable, vals: values });
+        // Concurrent reads of a pull share one statement across tables.
+        const [row] = await this.#batchedPage(LATEST_SCOPED_CHANGE_BATCH_SQL, partition, { tbl: query.table, var: firstVariable, vals: values });
         return row === undefined ? 0 : asNumber(row.seq);
     }
     async readCommitWindow(partition, query) {
@@ -1447,7 +1491,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         // var, value, commit_seq) PK makes the candidate subquery an index range
         // scan returning commit_seq already ascending (see postgres-explain
         // .test.ts), LEFT JOINed to the commit meta + the table's changes. Pages
-        // of concurrent window reads on the same table share one statement (see
+        // of concurrent window reads share one statement across tables (see
         // `COMMIT_WINDOW_BATCH_SQL`). Exact multi-variable verification against
         // the stored scope map happens below.
         const commits = [];
@@ -1455,7 +1499,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         let afterSeq = query.afterSeq;
         const batchSize = Math.max(64, query.limitChanges);
         while (deliveredChanges < query.limitChanges) {
-            const records = await this.#batchedPage(COMMIT_WINDOW_BATCH_SQL, partition, query.table, {
+            const records = await this.#batchedPage(COMMIT_WINDOW_BATCH_SQL, partition, {
+                tbl: query.table,
                 var: firstVariable,
                 vals: firstValues,
                 after: afterSeq,
@@ -1535,7 +1580,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         let afterRowId = query.afterRowId ?? '';
         const batchSize = Math.max(64, query.limit);
         while (rows.length < query.limit) {
-            const records = await this.#batchedPage(sql, partition, query.table, {
+            const records = await this.#batchedPage(sql, partition, {
+                tbl: query.table,
                 var: firstVariable,
                 vals: firstValues,
                 after: afterRowId,
@@ -1644,6 +1690,46 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         const { rows } = await this.#exec.query('SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=$1', [partition]);
         return rows.map((r) => r.blob_id);
     }
+    async listScopeValueRows(partition, query) {
+        const { rows } = await this.#exec.query(`SELECT row_id FROM sync_row_scopes
+        WHERE partition=$1 AND tbl=$2 AND var=$3 AND value=$4
+        ORDER BY row_id LIMIT $5`, [partition, query.table, query.variable, query.value, query.limit]);
+        return rows.map((row) => row.row_id);
+    }
+    async eraseScopeValueHistory(partition, query) {
+        const params = [
+            partition,
+            query.table,
+            query.variable,
+            query.value,
+            query.throughSeq,
+            query.limit,
+        ];
+        return this.#exec.transaction(async (client) => {
+            await lockPartitionOn(client, partition);
+            // Upsert change records of the binding, then the change scope entries
+            // whose commit no longer holds a change of the binding.
+            const changes = await client.query(`DELETE FROM sync_changes c USING (
+           SELECT c2.commit_seq, c2.idx FROM sync_change_scopes s
+             JOIN sync_changes c2 ON c2.partition=s.partition
+              AND c2.commit_seq=s.commit_seq AND c2.tbl=s.tbl
+            WHERE s.partition=$1 AND s.tbl=$2 AND s.var=$3 AND s.value=$4
+              AND s.commit_seq<=$5 AND c2.op=1 AND c2.scopes->>$3=s.value
+            LIMIT $6) d
+         WHERE c.partition=$1 AND c.commit_seq=d.commit_seq AND c.idx=d.idx`, params);
+            const scopes = await client.query(`DELETE FROM sync_change_scopes cs USING (
+           SELECT s.commit_seq FROM sync_change_scopes s
+            WHERE s.partition=$1 AND s.tbl=$2 AND s.var=$3 AND s.value=$4
+              AND s.commit_seq<=$5 AND NOT EXISTS (
+                SELECT 1 FROM sync_changes c
+                 WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
+                   AND c.tbl=s.tbl AND c.scopes->>$3=s.value)
+            LIMIT $6) d
+         WHERE cs.partition=$1 AND cs.tbl=$2 AND cs.var=$3 AND cs.value=$4
+           AND cs.commit_seq=d.commit_seq`, params);
+            return changes.rowCount + scopes.rowCount;
+        });
+    }
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);

package/dist/push.d.ts

@@ -17,11 +17,17 @@
  * merge); a validator throw rejects the whole commit atomically with a
  * host code.
  */
-import { type PushCommitFrame, type PushOperation, type PushResultFrame } from '@syncular/core';
+import { type PushCommitFrame, type PushOperation, type PushResultFrame, type RowValue } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
-import type { CompiledSchema } from './schema.js';
+import type { CompiledSchema, CompiledTable } from './schema.js';
 import type { ResolvedScopes } from './scopes.js';
 import type { StorageTransaction, StoredCommit } from './storage.js';
+/**
+ * Extract the blobIds a decoded row references through its `blob_ref`
+ * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
+ * row-codec decode (§5.9.1), so `parseBlobRef` here is total.
+ */
+export declare function blobIdsInRow(table: CompiledTable, values: readonly RowValue[]): string[];
 export interface ProcessedPushCommit {
     readonly frame: PushResultFrame;
     /** True when this request observed an already-recorded idempotency outcome. */

package/dist/push.js

@@ -35,7 +35,7 @@ import { CommitValidationRejection, toValidateRow, ValidationRejection, } from '
  * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
  * row-codec decode (§5.9.1), so `parseBlobRef` here is total.
  */
-function blobIdsInRow(table, values) {
+export function blobIdsInRow(table, values) {
     const ids = [];
     for (const index of table.blobRefColumnIndices) {
         const value = values[index];

package/dist/relational-rows.d.ts

@@ -228,27 +228,27 @@ export declare function commitWindowPageSql(valueCount: number, dialect: Relatio
 /**
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
  * page of every subscription scanning `table` in a pull. `$2` is a JSON array
- * of `{i, var, vals, after, lim}` records; each record runs the same
+ * of `{i, tbl, var, vals, after, lim}` records; each record runs the same
  * index-first candidate subquery through a LATERAL join, so every
  * subscription keeps its own keyset cursor and LIMIT. Rows arrive ordered
  * by (i, row_id).
  *
- * Params: [partition, specs (JSON text), tbl]. The specs bind as text before
+ * Params: [partition, specs (JSON text)]. The specs bind as text before
  * the JSONB cast, so a driver that JSON-encodes a string bound to a `jsonb`
  * parameter (Bun.sql) cannot turn the array into a JSON string.
  */
 export declare function scanRowBatchSql(table: CompiledTable): string;
 /**
  * PostgreSQL set-based form of `commitWindowPageSql`: one statement answers
- * the window page of every subscription reading `tbl` in a pull. `$2` is a
- * JSON array of `{i, var, vals, after, through, lim}` records, each running
- * the same index-first candidate subquery through a LATERAL join. Rows
- * arrive ordered by (i, commit_seq, idx).
+ * the window page of every subscription in a pull, across all tables. `$2`
+ * is a JSON array of `{i, tbl, var, vals, after, through, lim}` records, each
+ * running the same index-first candidate subquery through a LATERAL join.
+ * Rows arrive ordered by (i, commit_seq, idx).
  *
- * Params: [partition, specs (JSON text), tbl], the specs bound as text like
+ * Params: [partition, specs (JSON text)], the specs bound as text like
  * `scanRowBatchSql`.
  */
-export declare const COMMIT_WINDOW_BATCH_SQL = "SELECT s.i AS sub, c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,\n       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\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals text[], after bigint, through bigint, lim int)\n     CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes\n       WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=ANY(s.vals)\n         AND commit_seq>s.after AND commit_seq<=s.through\n       ORDER BY commit_seq LIMIT s.lim) c\n     LEFT JOIN sync_commits m\n       ON m.partition=$1 AND m.commit_seq=c.commit_seq\n     LEFT JOIN sync_changes ch\n       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3\n     ORDER BY s.i, c.commit_seq, ch.idx";
+export declare const COMMIT_WINDOW_BATCH_SQL = "SELECT s.i AS sub, c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,\n       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\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals text[], after bigint, through bigint, lim int)\n     CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes\n       WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=ANY(s.vals)\n         AND commit_seq>s.after AND commit_seq<=s.through\n       ORDER BY commit_seq LIMIT s.lim) c\n     LEFT JOIN sync_commits m\n       ON m.partition=$1 AND m.commit_seq=c.commit_seq\n     LEFT JOIN sync_changes ch\n       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=s.tbl\n     ORDER BY s.i, c.commit_seq, ch.idx";
 /**
  * PostgreSQL push read-ahead: every requested row id with its stored row
  * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
@@ -267,10 +267,10 @@ export declare function prefetchRowsSql(table: CompiledTable): string;
 export declare const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = "SELECT max((SELECT max(commit_seq) FROM sync_change_scopes\n           WHERE partition=? AND tbl=? AND var=? AND value=v.value)) AS seq\n     FROM json_each(?) AS v";
 /**
  * PostgreSQL set-based form of `LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL` for the
- * subscriptions of one table in a pull. `$2` is a JSON array of
- * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
+ * subscriptions of a pull, across all tables. `$2` is a JSON array of
+ * `{i, tbl, var, vals}` records. Params: [partition, specs (JSON text)].
  */
-export declare const LATEST_SCOPED_CHANGE_BATCH_SQL = "SELECT s.i AS sub,\n       (SELECT max(latest.seq) FROM (\n          SELECT (SELECT max(commit_seq) FROM sync_change_scopes\n                   WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=v.value) AS seq\n            FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals jsonb)\n    ORDER BY s.i";
+export declare const LATEST_SCOPED_CHANGE_BATCH_SQL = "SELECT s.i AS sub,\n       (SELECT max(latest.seq) FROM (\n          SELECT (SELECT max(commit_seq) FROM sync_change_scopes\n                   WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=v.value) AS seq\n            FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals jsonb)\n    ORDER BY s.i";
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
 /** DELETE one stored row. Params: [partition, rowId]. */

package/dist/relational-rows.js

@@ -551,20 +551,20 @@ export function commitWindowPageSql(valueCount, dialect) {
 /**
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
  * page of every subscription scanning `table` in a pull. `$2` is a JSON array
- * of `{i, var, vals, after, lim}` records; each record runs the same
+ * of `{i, tbl, var, vals, after, lim}` records; each record runs the same
  * index-first candidate subquery through a LATERAL join, so every
  * subscription keeps its own keyset cursor and LIMIT. Rows arrive ordered
  * by (i, row_id).
  *
- * Params: [partition, specs (JSON text), tbl]. The specs bind as text before
+ * Params: [partition, specs (JSON text)]. The specs bind as text before
  * the JSONB cast, so a driver that JSON-encodes a string bound to a `jsonb`
  * parameter (Bun.sql) cannot turn the array into a JSON string.
  */
 export function scanRowBatchSql(table) {
     return `SELECT s.i AS sub, 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, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
-     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals text[], after text, lim int)
+     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals text[], after text, lim int)
      CROSS JOIN LATERAL (SELECT DISTINCT row_id FROM sync_row_scopes
-       WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=ANY(s.vals)
+       WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=ANY(s.vals)
          AND row_id>s.after
        ORDER BY row_id LIMIT s.lim) c
      LEFT JOIN ${quoteIdent(table.name)} r
@@ -573,25 +573,25 @@ export function scanRowBatchSql(table) {
 }
 /**
  * PostgreSQL set-based form of `commitWindowPageSql`: one statement answers
- * the window page of every subscription reading `tbl` in a pull. `$2` is a
- * JSON array of `{i, var, vals, after, through, lim}` records, each running
- * the same index-first candidate subquery through a LATERAL join. Rows
- * arrive ordered by (i, commit_seq, idx).
+ * the window page of every subscription in a pull, across all tables. `$2`
+ * is a JSON array of `{i, tbl, var, vals, after, through, lim}` records, each
+ * running the same index-first candidate subquery through a LATERAL join.
+ * Rows arrive ordered by (i, commit_seq, idx).
  *
- * Params: [partition, specs (JSON text), tbl], the specs bound as text like
+ * Params: [partition, specs (JSON text)], the specs bound as text like
  * `scanRowBatchSql`.
  */
 export const COMMIT_WINDOW_BATCH_SQL = `SELECT s.i AS sub, 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 jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals text[], after bigint, through bigint, lim int)
+     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals text[], after bigint, through bigint, lim int)
      CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes
-       WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=ANY(s.vals)
+       WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=ANY(s.vals)
          AND commit_seq>s.after AND commit_seq<=s.through
        ORDER BY commit_seq LIMIT s.lim) c
      LEFT JOIN sync_commits m
        ON m.partition=$1 AND m.commit_seq=c.commit_seq
      LEFT JOIN sync_changes ch
-       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3
+       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=s.tbl
      ORDER BY s.i, c.commit_seq, ch.idx`;
 /**
  * PostgreSQL push read-ahead: every requested row id with its stored row
@@ -620,15 +620,15 @@ export const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = `SELECT max((SELECT max(commi
      FROM json_each(?) AS v`;
 /**
  * PostgreSQL set-based form of `LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL` for the
- * subscriptions of one table in a pull. `$2` is a JSON array of
- * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
+ * subscriptions of a pull, across all tables. `$2` is a JSON array of
+ * `{i, tbl, var, vals}` records. Params: [partition, specs (JSON text)].
  */
 export const LATEST_SCOPED_CHANGE_BATCH_SQL = `SELECT s.i AS sub,
        (SELECT max(latest.seq) FROM (
           SELECT (SELECT max(commit_seq) FROM sync_change_scopes
-                   WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=v.value) AS seq
+                   WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=v.value) AS seq
             FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq
-     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals jsonb)
+     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals jsonb)
     ORDER BY s.i`;
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export function selectRowScopesSql(table, dialect) {

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

@@ -7,6 +7,7 @@ export declare class SqliteBlobStore implements BlobStore {
     readonly db: SqliteDatabase;
     constructor(db?: SqliteDatabase | string);
     put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    delete(partition: string, blobId: string): Promise<void>;
     has(partition: string, blobId: string): Promise<boolean>;
     get(partition: string, blobId: string): Promise<{
         record: BlobRecord;

package/dist/sqlite-blob-store.js

@@ -17,8 +17,15 @@ export class SqliteBlobStore {
     }
     async put(partition, blobId, bytes, nowMs, mediaType) {
         const existing = await this.get(partition, blobId);
-        if (existing !== undefined)
-            return existing.record;
+        if (existing !== undefined) {
+            if (existing.record.mediaType !== undefined || mediaType === undefined)
+                return existing.record;
+            // A re-upload names the media type an earlier upload left out.
+            this.db
+                .query('UPDATE sync_blobs SET media_type=? WHERE partition=? AND blob_id=? AND media_type IS NULL')
+                .run(mediaType, partition, blobId);
+            return { ...existing.record, mediaType };
+        }
         const record = {
             blobId,
             partition,
@@ -33,6 +40,11 @@ export class SqliteBlobStore {
             .run(partition, blobId, bytes.length, mediaType ?? null, nowMs, bytes);
         return record;
     }
+    async delete(partition, blobId) {
+        this.db
+            .query('DELETE FROM sync_blobs WHERE partition=? AND blob_id=?')
+            .run(partition, blobId);
+    }
     async has(partition, blobId) {
         const row = this.db
             .query('SELECT 1 AS n FROM sync_blobs WHERE partition=? AND blob_id=?')

package/dist/sqlite-dialect.d.ts

@@ -16,7 +16,7 @@
  * behavior is held key-for-key regardless.
  */
 import type { ScopeMap } from '@syncular/core';
-import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+import type { ScopeValueHistoryQuery, StoredChange, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
 /**
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
  * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
@@ -39,6 +39,16 @@ import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './
 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_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER NOT NULL\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 INDEX IF NOT EXISTS sync_row_scopes_by_row\n  ON sync_row_scopes(partition, tbl, row_id);\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  writer_version INTEGER,\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_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\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);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n  partition TEXT NOT NULL, name TEXT NOT NULL,\n  schema_version INTEGER NOT NULL,\n  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n  watermark INTEGER NOT NULL DEFAULT 0,\n  owner_epoch INTEGER NOT NULL DEFAULT 0,\n  observed_rows INTEGER NOT NULL DEFAULT 0,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n  partition TEXT PRIMARY KEY,\n  required_writer_version INTEGER NOT NULL\n);\n";
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export declare function sqliteDdlStatements(): string[];
+/** §4.6.1: rowIds of one table bound to one scope value, budgeted. */
+export declare const LIST_SCOPE_VALUE_ROWS_SQLITE_SQL = "SELECT row_id FROM sync_row_scopes WHERE partition=? AND tbl=? AND var=? AND value=? ORDER BY row_id LIMIT ?";
+/**
+ * §4.6.1 history scrub, bound by `eraseScopeValueHistoryParams`: upsert change
+ * records of the binding first, then the change scope entries whose commit
+ * no longer holds a change of the binding. Each returns one row per removed
+ * record (D1 batch results carry no reliable change count).
+ */
+export declare const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL: readonly ["DELETE FROM sync_changes WHERE rowid IN (\n     SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c\n       ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl\n     WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4\n       AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value\n     LIMIT ?7) RETURNING 1 AS removed", "DELETE FROM sync_change_scopes WHERE rowid IN (\n     SELECT s.rowid FROM sync_change_scopes s\n     WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4\n       AND s.commit_seq<=?5 AND NOT EXISTS (\n         SELECT 1 FROM sync_changes c\n         WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq\n           AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)\n     LIMIT ?7) RETURNING 1 AS removed"];
+export declare function eraseScopeValueHistoryParams(partition: string, query: ScopeValueHistoryQuery): [string, string, string, string, number, string, number];
 /** `?,?,…` 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`. */

package/dist/sqlite-dialect.js

@@ -124,6 +124,41 @@ export function sqliteDdlStatements() {
         .map((statement) => statement.trim())
         .filter((statement) => statement.length > 0);
 }
+/** §4.6.1: rowIds of one table bound to one scope value, budgeted. */
+export const LIST_SCOPE_VALUE_ROWS_SQLITE_SQL = 'SELECT row_id FROM sync_row_scopes WHERE partition=? AND tbl=? AND var=? AND value=? ORDER BY row_id LIMIT ?';
+/**
+ * §4.6.1 history scrub, bound by `eraseScopeValueHistoryParams`: upsert change
+ * records of the binding first, then the change scope entries whose commit
+ * no longer holds a change of the binding. Each returns one row per removed
+ * record (D1 batch results carry no reliable change count).
+ */
+export const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL = [
+    `DELETE FROM sync_changes WHERE rowid IN (
+     SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c
+       ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl
+     WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
+       AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value
+     LIMIT ?7) RETURNING 1 AS removed`,
+    `DELETE FROM sync_change_scopes WHERE rowid IN (
+     SELECT s.rowid FROM sync_change_scopes s
+     WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
+       AND s.commit_seq<=?5 AND NOT EXISTS (
+         SELECT 1 FROM sync_changes c
+         WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
+           AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)
+     LIMIT ?7) RETURNING 1 AS removed`,
+];
+export function eraseScopeValueHistoryParams(partition, query) {
+    return [
+        partition,
+        query.table,
+        query.variable,
+        query.value,
+        query.throughSeq,
+        `$.${JSON.stringify(query.variable)}`,
+        query.limit,
+    ];
+}
 /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
 export function placeholders(count) {
     return new Array(count).fill('?').join(',');

package/dist/sqlite-storage.d.ts

@@ -2,7 +2,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
@@ -67,6 +67,8 @@ export declare class SqliteServerStorage implements ServerStorage {
         readonly scopes: Record<string, string>;
     }[]>;
     listReferencedBlobIds(partition: string): Promise<string[]>;
+    listScopeValueRows(partition: string, query: ScopeValueQuery): Promise<string[]>;
+    eraseScopeValueHistory(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
     listClientRecords(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
     getCommit(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;