@syncular/server 0.34.0 → 0.35.0

package/dist/storage-errors.d.ts

@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.query_over_staged_writes';
+export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
  * paths, or row data; callers branch on `code`, never message text. The

package/dist/storage-errors.js

@@ -32,6 +32,8 @@ const STORAGE_QUERY_MESSAGES = {
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',
     'sync.storage.index_value_count_mismatch': 'trusted row lookup requires one exact value per index column',
     'sync.storage.invalid_limit': 'trusted row lookup limit must be an integer from 1 through 1,000',
+    'sync.storage.erase_unsupported': 'this storage backend cannot erase a scope value',
+    'sync.storage.invalid_erase_query': 'erasure requires a declared scope variable, a non-empty value, and a row budget within the operation cap',
 };
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,

package/dist/storage.d.ts

@@ -701,6 +701,22 @@ export interface ServerStorage {
      */
     listRowsReferencingBlob?(partition: string, blobId: string): Promise<BlobReferencingRow[]>;
     listReferencedBlobIds?(partition: string): Promise<string[]>;
+    /**
+     * §4.6.1 scope-value erasure — ADDITIVE, optional; `eraseScopeValue`
+     * requires both.
+     *
+     * `listScopeValueRows`: up to `limit` rowIds of `table` whose stored scope
+     * binds `variable` to `value`, ordered by rowId (the row scope index).
+     *
+     * `eraseScopeValueHistory`: under the partition write lock, removes up to
+     * `limit` upsert change records of `table` at or below `throughSeq` whose
+     * scopes bind `variable` to `value`, then up to `limit` change scope index
+     * entries of that binding whose commit holds no such change any more.
+     * Delete change records stay: clients behind the erasure still need them.
+     * Returns the number of records removed.
+     */
+    listScopeValueRows?(partition: string, query: ScopeValueQuery): Promise<string[]>;
+    eraseScopeValueHistory?(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
     /**
      * Admin/console read surface (`SyncularAdmin`): ADDITIVE,
      * optional. All read-only, partition-scoped, and JSON-able. A backend
@@ -736,6 +752,16 @@ export interface ServerStorage {
     listPushResults?(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
     listPartitions(): Promise<string[]>;
 }
+/** One scope binding of one table, budgeted (§4.6.1). */
+export interface ScopeValueQuery {
+    readonly table: string;
+    readonly variable: string;
+    readonly value: string;
+    readonly limit: number;
+}
+export interface ScopeValueHistoryQuery extends ScopeValueQuery {
+    readonly throughSeq: number;
+}
 /** A row referencing a blob, with the scopes needed to authorize download. */
 export interface BlobReferencingRow {
     readonly table: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.34.0"
+    "@syncular/core": "0.35.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/blob-handlers.ts

@@ -6,7 +6,7 @@
  * `blobId` is never a bearer capability. Framework-free; the hono/runtime
  * adapters map these onto `PUT/GET <mount>/blobs/{blobId}`.
  */
-import { blobIdFor, isBlobId } from './blob-store';
+import { type BlobRecord, blobIdFor, isBlobId } from './blob-store';
 import type { SyncRequestContext } from './context';
 import {
   clockOf,
@@ -180,7 +180,7 @@ async function downloadBlob(
   // egress path — it only needs to know the object EXISTS (a HEAD/`has`), not
   // the bytes. Inline delivery loads the bytes; presigned delivery does not.
   const presignConfigured = ctx.blobSignedUrls !== undefined;
-  let entry: { bytes: Uint8Array } | undefined;
+  let entry: { record: BlobRecord; bytes: Uint8Array } | undefined;
   if (presignConfigured) {
     if (!(await store.has(ctx.partition, blobId))) {
       throw syncError('blob.not_found', 'unknown blob (§5.9.5)');
@@ -277,12 +277,20 @@ async function downloadBlob(
     // Unreachable: presign not configured ⇒ `entry` was loaded above.
     throw syncError('blob.not_found', 'blob bytes unavailable (§5.9.5)');
   }
-  // §5.9.5: inline bytes are always octet-stream. The stored media type
-  // would make a JSON blob indistinguishable from the signed-URL envelope.
+  // §5.9.5: inline bytes carry the stored media type, so an <img> or <a>
+  // pointed at the route renders them. A JSON type stays octet-stream: a
+  // JSON body is reserved for the signed-URL envelope.
+  const mediaType = entry?.record.mediaType;
   return {
     bytes,
     headers: {
-      'Content-Type': 'application/octet-stream',
+      'Content-Type':
+        mediaType === undefined ||
+        mediaType.toLowerCase().includes('application/json')
+          ? 'application/octet-stream'
+          : mediaType,
+      'X-Content-Type-Options': 'nosniff',
+      'Content-Security-Policy': "sandbox; default-src 'none'",
       ETag: `"${blobId}"`,
       'Cache-Control': 'private, max-age=0',
       Vary: 'Authorization, Accept-Encoding',

package/src/bucket-blob-store.ts

@@ -218,29 +218,31 @@ export class BucketBlobStore implements BlobStore {
     // blob once, and preserve the FIRST createdAtMs so the sweep's grace clock
     // is not reset by a re-upload (§5.9.2 upload age).
     const preexisting = await this.#bucket.head(objectKey);
-    if (preexisting !== undefined) {
-      const meta = preexisting.metadata[BLOB_META_KEY];
-      if (meta !== undefined) {
-        const existing = parseMetaJson(
-          base64urlToUtf8(meta),
-          blobId,
-          this.#label,
-        );
-        return {
-          blobId,
-          partition,
-          byteLength: existing.byteLength,
-          ...(existing.mediaType !== undefined
-            ? { mediaType: existing.mediaType }
-            : {}),
-          createdAtMs: existing.createdAtMs,
-        };
-      }
+    const storedMeta = preexisting?.metadata[BLOB_META_KEY];
+    const existing =
+      storedMeta === undefined
+        ? undefined
+        : parseMetaJson(base64urlToUtf8(storedMeta), blobId, this.#label);
+    if (
+      existing !== undefined &&
+      (existing.mediaType !== undefined || mediaType === undefined)
+    ) {
+      return {
+        blobId,
+        partition,
+        byteLength: existing.byteLength,
+        ...(existing.mediaType !== undefined
+          ? { mediaType: existing.mediaType }
+          : {}),
+        createdAtMs: existing.createdAtMs,
+      };
     }
+    // A re-upload that names the media type an earlier upload left out
+    // rewrites the object under the same precondition, keeping its age.
     const meta: BlobMeta = {
       byteLength: bytes.length,
       ...(mediaType !== undefined ? { mediaType } : {}),
-      createdAtMs: nowMs,
+      createdAtMs: existing?.createdAtMs ?? nowMs,
     };
     // Conditional write: of two concurrent uploads of the same blob exactly
     // one lands, so the first createdAtMs survives and the blob counts once.
@@ -256,7 +258,11 @@ export class BucketBlobStore implements BlobStore {
     if (!written) return this.put(partition, blobId, bytes, nowMs, mediaType);
     if (preexisting === undefined)
       await this.#bumpStats({ count: 1, bytes: bytes.length });
-    return record;
+    return { ...record, createdAtMs: meta.createdAtMs };
+  }
+
+  async delete(partition: string, blobId: string): Promise<void> {
+    await this.#bucket.delete(this.objectKeyFor(partition, blobId));
   }
 
   async has(partition: string, blobId: string): Promise<boolean> {

package/src/d1-storage.ts

@@ -92,6 +92,9 @@ import {
   collectCommitWindowPage,
   deserializePushResult,
   placeholders,
+  ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL,
+  eraseScopeValueHistoryParams,
+  LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
   type SqliteChangeRecord,
   type SqliteCommitWindowRecord,
   type SqliteRowRecord,
@@ -130,6 +133,8 @@ import type {
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
+  ScopeValueHistoryQuery,
+  ScopeValueQuery,
   ServerStorage,
   ServeGate,
   StorageTransaction,
@@ -2473,6 +2478,46 @@ export class D1ServerStorage implements ServerStorage {
     return results.map((r) => r.blob_id);
   }
 
+  async listScopeValueRows(
+    partition: string,
+    query: ScopeValueQuery,
+  ): Promise<string[]> {
+    const { results } = await this.#db
+      .prepare(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
+      .bind(partition, query.table, query.variable, query.value, query.limit)
+      .all<{ row_id: string }>();
+    return results.map((row) => row.row_id);
+  }
+
+  async eraseScopeValueHistory(
+    partition: string,
+    query: ScopeValueHistoryQuery,
+  ): Promise<number> {
+    if (!this.#pushApplySerialized)
+      throw new Error(
+        'D1 erasure requires externally serialized partition writes',
+      );
+    const params = eraseScopeValueHistoryParams(partition, query);
+    const results = await this.#db.batch(
+      ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL.map((sql) =>
+        this.#db.prepare(sql).bind(...params),
+      ),
+    );
+    let removed = 0;
+    for (const result of results) {
+      if (
+        typeof result !== 'object' ||
+        result === null ||
+        !('results' in result) ||
+        !Array.isArray(result.results)
+      ) {
+        throw new Error('D1 erasure returned an invalid batch result');
+      }
+      removed += result.results.length;
+    }
+    return removed;
+  }
+
   // -- admin/console read surface --------------------------------------------
 
   async listClientRecords(partition: string): Promise<ClientRecord[]> {

package/src/erase.ts

@@ -0,0 +1,173 @@
+/**
+ * Scope-value erasure (SPEC.md §4.6.1): remove every row whose stored scope
+ * binds one variable to one value, the upsert change records that carried
+ * those rows, and the blob bytes no remaining row references.
+ *
+ * Live rows leave through one ordinary delete commit per call, applied on
+ * the shared push path (partition lock, tombstones, blob reference index,
+ * realtime fanout). The commit advances the binding's scoped change seq, so
+ * no cached segment taken before the erasure is reused, and every client
+ * holding the rows receives the deletes. Once no live row is left, each call
+ * scrubs the change log of the binding. Hosts loop until `done`.
+ */
+import { decodeRow, type PushOperation } from '@syncular/core';
+import { limitsOf, type SyncServerConfig } from './context';
+import { SyncError } from './errors';
+import { blobIdsInRow, processPushOperationsWithTrace } from './push';
+import { compileSchema } from './schema';
+import { StorageQueryError } from './storage-errors';
+
+export interface EraseScopeValueOptions {
+  readonly partition: string;
+  /** The scope variable as declared by the schema's scope patterns. */
+  readonly variable: string;
+  readonly value: string;
+  /**
+   * Rows deleted per call, and change records removed per table per call
+   * (default 200, at most the push operation cap).
+   */
+  readonly maxRows?: number;
+  /** Actor recorded on the erasure commits (default `syncular.erase`). */
+  readonly actorId?: string;
+}
+
+export interface EraseScopeValueResult {
+  /** Rows the erasure commit of this call deleted. */
+  readonly rowsErased: number;
+  /** The erasure commit of this call, when it deleted rows. */
+  readonly commitSeq?: number;
+  /** Change log records this call removed. */
+  readonly historyErased: number;
+  /** Blobs whose last reference this call removed; their bytes are gone. */
+  readonly blobsErased: readonly string[];
+  /** Nothing of the binding is left; further calls change nothing. */
+  readonly done: boolean;
+}
+
+/** Erase one scope binding of one partition, one budgeted step per call. */
+export async function eraseScopeValue(
+  config: SyncServerConfig,
+  options: EraseScopeValueOptions,
+): Promise<EraseScopeValueResult> {
+  const { storage } = config;
+  const { partition, variable, value } = options;
+  const maxRows = options.maxRows ?? 200;
+  const listRows = storage.listScopeValueRows?.bind(storage);
+  const eraseHistory = storage.eraseScopeValueHistory?.bind(storage);
+  const listReferences = storage.listRowsReferencingBlob?.bind(storage);
+  if (
+    listRows === undefined ||
+    eraseHistory === undefined ||
+    listReferences === undefined
+  ) {
+    throw new StorageQueryError('sync.storage.erase_unsupported');
+  }
+  const schema = compileSchema(config.schema);
+  const tables = [...schema.tables.values()].filter((table) =>
+    table.scopePatterns.some((pattern) => pattern.variable === variable),
+  );
+  if (
+    tables.length === 0 ||
+    value.length === 0 ||
+    !Number.isSafeInteger(maxRows) ||
+    maxRows < 1 ||
+    maxRows > limitsOf(config).maxOperationsPerRequest
+  ) {
+    throw new StorageQueryError('sync.storage.invalid_erase_query');
+  }
+  if ((await storage.getPartitionLogEpoch(partition)) === undefined) {
+    return { rowsErased: 0, historyErased: 0, blobsErased: [], done: true };
+  }
+  await storage.ensureSchema(schema, config.checkpoints);
+
+  const targets: { table: string; rowId: string }[] = [];
+  for (const table of tables) {
+    const limit = maxRows - targets.length;
+    if (limit === 0) break;
+    const query = { table: table.name, variable, value, limit };
+    for (const rowId of await listRows(partition, query)) {
+      targets.push({ table: table.name, rowId });
+    }
+  }
+
+  if (targets.length > 0) {
+    // Erasure is the operator's act: app validators do not gate it.
+    const { validators, commitValidator, ...trusted } = config;
+    const blobIds = new Set<string>();
+    let rowsErased = 0;
+    const processed = await processPushOperationsWithTrace(
+      { ...trusted, partition, actorId: options.actorId ?? 'syncular.erase' },
+      schema,
+      {
+        ok: true,
+        allowed: Object.fromEntries(
+          [...schema.tables.values()].flatMap((table) =>
+            table.scopePatterns.map((pattern) => [pattern.variable, ['*']]),
+          ),
+        ),
+      },
+      'syncular.erase',
+      crypto.randomUUID(),
+      async (tx) => {
+        const operations: PushOperation[] = [];
+        for (const target of targets) {
+          // Re-read under the partition lock: a row may have moved or gone.
+          const stored = await tx.getRow(target.table, target.rowId);
+          if (stored?.scopes[variable] !== value) continue;
+          const table = schema.tables.get(target.table)!;
+          for (const blobId of blobIdsInRow(
+            table,
+            decodeRow(table.columns, stored.payload),
+          )) {
+            blobIds.add(blobId);
+          }
+          operations.push({
+            table: target.table,
+            op: 'delete',
+            rowId: target.rowId,
+          });
+        }
+        rowsErased = operations.length;
+        return operations;
+      },
+    );
+    const { frame } = processed;
+    if (frame.status !== 'applied') {
+      const failed = frame.results.find((result) => 'code' in result);
+      throw failed !== undefined && 'code' in failed
+        ? new SyncError(failed.code, failed.message)
+        : new Error('eraseScopeValue: the erasure commit was not applied');
+    }
+    const blobsErased: string[] = [];
+    for (const blobId of blobIds) {
+      if ((await listReferences(partition, blobId)).length > 0) continue;
+      await config.blobs?.delete(partition, blobId);
+      blobsErased.push(blobId);
+    }
+    return {
+      rowsErased,
+      ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
+      historyErased: 0,
+      blobsErased,
+      done: false,
+    };
+  }
+
+  const throughSeq = await storage.getMaxCommitSeq(partition);
+  let historyErased = 0;
+  for (const table of tables) {
+    historyErased += await eraseHistory(partition, {
+      table: table.name,
+      variable,
+      value,
+      throughSeq,
+      limit: maxRows,
+    });
+  }
+  return {
+    rowsErased: 0,
+    historyErased,
+    blobsErased: [],
+    done: historyErased === 0,
+  };
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export * from './content-encoding';
 export * from './context';
 export * from './crdt-merger';
 export * from './d1-storage';
+export * from './erase';
 export * from './errors';
 export * from './events';
 export * from './events-ring';

package/src/postgres-storage.ts

@@ -121,6 +121,8 @@ import type {
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
+  ScopeValueHistoryQuery,
+  ScopeValueQuery,
   ServerStorage,
   ServeGate,
   StorageTransaction,
@@ -2567,6 +2569,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/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[]> {