@syncular/server 0.34.0 → 0.36.0

package/src/postgres-storage.ts

@@ -90,7 +90,7 @@ import {
   upsertValues,
 } from './relational-rows';
 import type { CompiledSchema, CompiledTable } from './schema';
-import { matchesEffective } from './scopes';
+import { matchesEffective, sha256Hex } from './scopes';
 import type {
   AuthoritativeQueryRequest,
   AuthoritativeQueryResult,
@@ -121,6 +121,8 @@ import type {
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
+  ScopeValueHistoryQuery,
+  ScopeValueQuery,
   ServerStorage,
   ServeGate,
   StorageTransaction,
@@ -1277,10 +1279,11 @@ export class PostgresServerStorage implements ServerStorage {
   #schemaVersion: number | undefined;
   /**
    * 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).
    */
   readonly #pageBatches = new Map<string, PendingPage[]>();
 
@@ -1289,18 +1292,17 @@ export class PostgresServerStorage implements ServerStorage {
   }
 
   /**
-   * 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<Row>(
     sql: string,
     partition: string,
-    table: string,
     spec: Record<string, unknown>,
   ): Promise<Row[]> {
-    const key = `${sql}\u0000${partition}\u0000${table}`;
+    const key = `${sql}\u0000${partition}`;
     let batch = this.#pageBatches.get(key);
     if (batch === undefined) {
       const queued: PendingPage[] = [];
@@ -1311,7 +1313,7 @@ export class PostgresServerStorage implements ServerStorage {
         const specs = JSON.stringify(
           queued.map((entry, i) => ({ ...entry.spec, i })),
         );
-        this.#exec.query<PgRow>(sql, [partition, specs, table]).then(
+        this.#exec.query<PgRow>(sql, [partition, specs]).then(
           ({ rows }) => {
             const grouped = queued.map((): PgRow[] => []);
             for (const row of rows) grouped[asNumber(row.sub)]?.push(row);
@@ -1333,24 +1335,27 @@ export class PostgresServerStorage implements ServerStorage {
     });
   }
 
-  /** 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(): Promise<void> {
     // 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(
+    // 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. Sent as separate statements because
-    // the dollar-quoted body contains `;`.
-    await this.#exec.query(`CREATE OR REPLACE FUNCTION syncular_writer_fence()
+      // 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 (
@@ -1363,13 +1368,45 @@ BEGIN
   END IF;
   RETURN NEW;
 END;
-$$ LANGUAGE plpgsql`);
-    await this.#exec.query(
+$$ LANGUAGE plpgsql`,
       'DROP TRIGGER IF EXISTS sync_commits_writer_fence ON sync_commits',
-    );
-    await this.#exec.query(`CREATE TRIGGER sync_commits_writer_fence
+      `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<{
+      storage: string | null;
+      missing: number;
+    }>(
+      `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`. */
@@ -1390,21 +1427,63 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     // Memoized fast path: same instance, same schema version.
     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<{
+      schema_version: unknown;
+      layouts: unknown;
+      incomplete: string;
+      columns: string;
+    }>(
+      `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<{
+    const incomplete = JSON.parse(marker.incomplete) as {
       partition: string;
       name: string;
-    }>(
-      `SELECT partition, name FROM sync_backfill_checkpoints
-        WHERE schema_version=$1 AND state<>'activated'`,
-      [schema.version],
-    );
+    }[];
     if (
-      incomplete.rows.some(
+      incomplete.some(
         (row) =>
           !declarations.some(
             (declaration) =>
@@ -1415,15 +1494,10 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     ) {
       throw new StorageQueryError('sync.storage.checkpoint_incomplete');
     }
-    await this.#exec.query(SCHEMA_META_DDL_POSTGRES);
-    const marker = await this.#exec.query<{
-      schema_version: unknown;
-      layouts: unknown;
-    }>('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1');
     const stored =
-      marker.rows[0] === undefined
+      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`,
@@ -1432,43 +1506,26 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     if (stored !== undefined && stored === schema.version) {
       assertStoredLayouts(
         schema,
-        typeof marker.rows[0]?.layouts === 'string'
-          ? marker.rows[0].layouts
-          : undefined,
+        typeof marker.layouts === 'string' ? marker.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.
+      const columns = JSON.parse(marker.columns) as {
+        tbl: string;
+        name: string;
+        type: string;
+        not_null: boolean;
+        pk: number | null;
+      }[];
       for (const table of schema.tables.values()) {
-        const { rows } = await this.#exec.query<{
-          name: string;
-          type: string;
-          not_null: boolean;
-          pk: number | null;
-        }>(
-          `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,
-          })),
+          columns
+            .filter((column) => column.tbl === table.name)
+            .map((column) => ({
+              name: column.name,
+              type: column.type,
+              notNull: column.not_null,
+              primaryKeyPosition: column.pk ?? 0,
+            })),
           'postgres',
         );
       }
@@ -1481,9 +1538,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
       // 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,
+        typeof marker.layouts === 'string' ? marker.layouts : undefined,
       );
       const retiredTables = retiredTableNames(schema, layouts);
       await this.#exec.transaction(async (client) => {
@@ -2260,12 +2315,11 @@ 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.
+    // Concurrent reads of a pull share one statement across tables.
     const [row] = await this.#batchedPage<{ seq: unknown }>(
       LATEST_SCOPED_CHANGE_BATCH_SQL,
       partition,
-      query.table,
-      { var: firstVariable, vals: values },
+      { tbl: query.table, var: firstVariable, vals: values },
     );
     return row === undefined ? 0 : asNumber(row.seq);
   }
@@ -2283,7 +2337,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: StoredCommit[] = [];
@@ -2294,8 +2348,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
       const records = await this.#batchedPage<CommitWindowRecord>(
         COMMIT_WINDOW_BATCH_SQL,
         partition,
-        query.table,
         {
+          tbl: query.table,
           var: firstVariable,
           vals: firstValues,
           after: afterSeq,
@@ -2368,17 +2422,13 @@ 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<RowRecord>(
-        sql,
-        partition,
-        query.table,
-        {
-          var: firstVariable,
-          vals: firstValues,
-          after: afterRowId,
-          lim: batchSize,
-        },
-      );
+      const records = await this.#batchedPage<RowRecord>(sql, partition, {
+        tbl: query.table,
+        var: firstVariable,
+        vals: firstValues,
+        after: afterRowId,
+        lim: batchSize,
+      });
       if (records.length === 0) break;
       for (const record of records) {
         afterRowId = record.row_id;
@@ -2567,6 +2617,63 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     return rows.map((r) => r.blob_id);
   }
 
+  async listScopeValueRows(
+    partition: string,
+    query: ScopeValueQuery,
+  ): Promise<string[]> {
+    const { rows } = await this.#exec.query<{ row_id: string }>(
+      `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: string,
+    query: ScopeValueHistoryQuery,
+  ): Promise<number> {
+    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: string): Promise<ClientRecord[]> {

package/src/push.ts

@@ -75,7 +75,7 @@ import {
  * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
  * row-codec decode (§5.9.1), so `parseBlobRef` here is total.
  */
-function blobIdsInRow(
+export function blobIdsInRow(
   table: CompiledTable,
   values: readonly RowValue[],
 ): string[] {

package/src/relational-rows.ts

@@ -647,20 +647,20 @@ export function commitWindowPageSql(
 /**
  * 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: CompiledTable): string {
   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
@@ -670,25 +670,25 @@ export 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 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`;
 
 /**
@@ -720,15 +720,15 @@ export const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = `SELECT max((SELECT max(commi
 
 /**
  * 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]. */

package/src/sqlite-blob-store.ts

@@ -33,7 +33,17 @@ export class SqliteBlobStore implements BlobStore {
     mediaType?: string,
   ): Promise<BlobRecord> {
     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: BlobRecord = {
       blobId,
       partition,
@@ -51,6 +61,12 @@ export class SqliteBlobStore implements BlobStore {
     return record;
   }
 
+  async delete(partition: string, blobId: string): Promise<void> {
+    this.db
+      .query('DELETE FROM sync_blobs WHERE partition=? AND blob_id=?')
+      .run(partition, blobId);
+  }
+
   async has(partition: string, blobId: string): Promise<boolean> {
     const row = this.db
       .query<{ n: number }, [string, string]>(

package/src/sqlite-dialect.ts

@@ -18,6 +18,7 @@
 import type { PushOperationResult, ScopeMap } from '@syncular/core';
 import { matchesEffective } from './scopes';
 import type {
+  ScopeValueHistoryQuery,
   StoredChange,
   StoredCommit,
   StoredPushResult,
@@ -151,6 +152,48 @@ export function sqliteDdlStatements(): string[] {
     .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`,
+] as const;
+
+export function eraseScopeValueHistoryParams(
+  partition: string,
+  query: ScopeValueHistoryQuery,
+): [string, string, string, string, number, string, number] {
+  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: number): string {
   return new Array(count).fill('?').join(',');

package/src/sqlite-storage.ts

@@ -56,6 +56,9 @@ import { matchesEffective } from './scopes';
 import {
   collectCommitWindowPage,
   deserializePushResult,
+  ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL,
+  eraseScopeValueHistoryParams,
+  LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
   placeholders,
   SQLITE_DDL,
   type SqliteChangeRecord,
@@ -100,6 +103,8 @@ import type {
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
+  ScopeValueHistoryQuery,
+  ScopeValueQuery,
   ServerStorage,
   ServeGate,
   StorageTransaction,
@@ -1925,6 +1930,40 @@ END`);
     return rows.map((r) => r.blob_id);
   }
 
+  async listScopeValueRows(
+    partition: string,
+    query: ScopeValueQuery,
+  ): Promise<string[]> {
+    return this.db
+      .query<{ row_id: string }, [string, string, string, string, number]>(
+        LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
+      )
+      .all(partition, query.table, query.variable, query.value, query.limit)
+      .map((row) => row.row_id);
+  }
+
+  async eraseScopeValueHistory(
+    partition: string,
+    query: ScopeValueHistoryQuery,
+  ): Promise<number> {
+    const params = eraseScopeValueHistoryParams(partition, query);
+    return this.#serializeWrite(() => {
+      this.db.exec('BEGIN IMMEDIATE');
+      try {
+        let removed = 0;
+        for (const sql of ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL) {
+          removed += this.db.query(sql).all(...params).length;
+        }
+        this.db.exec('COMMIT');
+        return removed;
+      } catch (error) {
+        rollbackAfterError(() => {
+          this.db.exec('ROLLBACK');
+        }, error);
+      }
+    });
+  }
+
   // -- admin/console read surface --------------------------------------------
 
   async listClientRecords(partition: string): Promise<ClientRecord[]> {