@syncular/server 0.33.0 → 0.35.0

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>;

package/dist/sqlite-storage.js

@@ -13,9 +13,9 @@ import { serveNotReadyError } from './readiness.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, placeholders, SQLITE_DDL, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1034,13 +1034,8 @@ END`);
         if (firstVariable === undefined || values.length === 0)
             return 0;
         const row = this.db
-            .query(latestScopedChangeSeqSql(values.length))
-            .get(...values.flatMap((value) => [
-            partition,
-            query.table,
-            firstVariable,
-            value,
-        ]));
+            .query(LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL)
+            .get(partition, query.table, firstVariable, JSON.stringify(values));
         return row?.seq ?? 0;
     }
     async readCommitWindow(partition, query) {
@@ -1203,6 +1198,31 @@ END`);
             .all(partition);
         return rows.map((r) => r.blob_id);
     }
+    async listScopeValueRows(partition, query) {
+        return this.db
+            .query(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
+            .all(partition, query.table, query.variable, query.value, query.limit)
+            .map((row) => row.row_id);
+    }
+    async eraseScopeValueHistory(partition, query) {
+        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) {
         const records = this.db

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.33.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.33.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

@@ -54,7 +54,7 @@ import {
   assertPhysicalColumns,
   assertStoredLayouts,
   commitWindowPageSql,
-  latestScopedChangeSeqSql,
+  LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
   deleteRowSql,
   deleteSqliteRowScopesSql,
   dropTableDdl,
@@ -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,
@@ -2189,8 +2194,8 @@ export class D1ServerStorage implements ServerStorage {
     if (firstVariable === undefined || values.length === 0) return 0;
     // Concurrent reads of a pull share one `db.batch` round trip.
     const [row] = await this.#batchedAll<{ seq: number | null }>(
-      latestScopedChangeSeqSql(values.length),
-      values.flatMap((value) => [partition, query.table, firstVariable, value]),
+      LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
+      [partition, query.table, firstVariable, JSON.stringify(values)],
     );
     return row?.seq ?? 0;
   }
@@ -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';