@syncular/server 0.34.0 → 0.35.0

package/dist/blob-handlers.js

@@ -189,12 +189,19 @@ async function downloadBlob(ctx, blobId) {
         // 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/dist/blob-store.d.ts

@@ -37,7 +37,9 @@ export interface BlobStoreStats {
 export interface BlobStore {
     /**
      * Store blob bytes under `blobId` (idempotent — same id ⇒ no-op success,
-     * §5.9.3). The caller has already verified the content address matches.
+     * §5.9.3). A re-upload that declares a media type records it on a blob
+     * stored without one; a recorded media type never changes. The caller has
+     * already verified the content address matches.
      */
     put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
     /** Presence check for the push existence rule (§5.9.6) and download. */
@@ -53,6 +55,11 @@ export interface BlobStore {
      * Returns the deleted blobIds.
      */
     sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    /**
+     * §4.6.1 erasure: delete one blob whose last reference is gone. Deleting a
+     * missing blob is a no-op.
+     */
+    delete(partition: string, blobId: string): Promise<void>;
     /** Admin/console counters (work item §2.5) — ADDITIVE, optional. */
     stats?(partition: string): Promise<BlobStoreStats>;
 }
@@ -68,6 +75,7 @@ export declare class MemoryBlobStore implements BlobStore {
         bytes: Uint8Array;
     } | undefined>;
     sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    delete(partition: string, blobId: string): Promise<void>;
     stats(partition: string): Promise<BlobStoreStats>;
 }
 export interface SweepOrphanBlobsOptions {

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

@@ -51,6 +51,7 @@ export declare class BucketBlobStore implements BlobStore {
      */
     objectKeyFor(partition: string, blobId: string): string;
     put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    delete(partition: string, blobId: string): Promise<void>;
     has(partition: string, blobId: string): Promise<boolean>;
     get(partition: string, blobId: string): Promise<{
         record: BlobRecord;

package/dist/bucket-blob-store.js

@@ -141,25 +141,28 @@ export class BucketBlobStore {
         // 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 = {
             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.
@@ -176,7 +179,10 @@ export class BucketBlobStore {
             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, blobId) {
+        await this.#bucket.delete(this.objectKeyFor(partition, blobId));
     }
     async has(partition, blobId) {
         if (!BLOB_ID_PATTERN.test(blobId))

package/dist/d1-storage.d.ts

@@ -42,7 +42,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
  */
 import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.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 interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -134,6 +134,8 @@ export declare class D1ServerStorage 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/d1-storage.js

@@ -47,7 +47,7 @@ import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './author
 import { syncError } from './errors.js';
 import { assertAppendOnlyMigration, 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, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
+import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 function toStoredReaction(record) {
@@ -1654,6 +1654,30 @@ export class D1ServerStorage {
             .all();
         return results.map((r) => r.blob_id);
     }
+    async listScopeValueRows(partition, query) {
+        const { results } = await this.#db
+            .prepare(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
+            .bind(partition, query.table, query.variable, query.value, query.limit)
+            .all();
+        return results.map((row) => row.row_id);
+    }
+    async eraseScopeValueHistory(partition, query) {
+        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) {
         const { results } = await this.#db

package/dist/erase.d.ts

@@ -0,0 +1,28 @@
+import { type SyncServerConfig } from './context.js';
+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 declare function eraseScopeValue(config: SyncServerConfig, options: EraseScopeValueOptions): Promise<EraseScopeValueResult>;

package/dist/erase.js

@@ -0,0 +1,122 @@
+/**
+ * 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 } from '@syncular/core';
+import { limitsOf } from './context.js';
+import { SyncError } from './errors.js';
+import { blobIdsInRow, processPushOperationsWithTrace } from './push.js';
+import { compileSchema } from './schema.js';
+import { StorageQueryError } from './storage-errors.js';
+/** Erase one scope binding of one partition, one budgeted step per call. */
+export async function eraseScopeValue(config, options) {
+    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 = [];
+    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();
+        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 = [];
+            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 = [];
+        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/dist/index.d.ts

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

package/dist/index.js

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

package/dist/postgres-storage.d.ts

@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.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, StoredCheckpoint, StoredCommit, 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, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -134,6 +134,8 @@ export declare class PostgresServerStorage 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/postgres-storage.js

@@ -1644,6 +1644,46 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         const { rows } = await this.#exec.query('SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=$1', [partition]);
         return rows.map((r) => r.blob_id);
     }
+    async listScopeValueRows(partition, query) {
+        const { rows } = await this.#exec.query(`SELECT row_id FROM sync_row_scopes
+        WHERE partition=$1 AND tbl=$2 AND var=$3 AND value=$4
+        ORDER BY row_id LIMIT $5`, [partition, query.table, query.variable, query.value, query.limit]);
+        return rows.map((row) => row.row_id);
+    }
+    async eraseScopeValueHistory(partition, query) {
+        const params = [
+            partition,
+            query.table,
+            query.variable,
+            query.value,
+            query.throughSeq,
+            query.limit,
+        ];
+        return this.#exec.transaction(async (client) => {
+            await lockPartitionOn(client, partition);
+            // Upsert change records of the binding, then the change scope entries
+            // whose commit no longer holds a change of the binding.
+            const changes = await client.query(`DELETE FROM sync_changes c USING (
+           SELECT c2.commit_seq, c2.idx FROM sync_change_scopes s
+             JOIN sync_changes c2 ON c2.partition=s.partition
+              AND c2.commit_seq=s.commit_seq AND c2.tbl=s.tbl
+            WHERE s.partition=$1 AND s.tbl=$2 AND s.var=$3 AND s.value=$4
+              AND s.commit_seq<=$5 AND c2.op=1 AND c2.scopes->>$3=s.value
+            LIMIT $6) d
+         WHERE c.partition=$1 AND c.commit_seq=d.commit_seq AND c.idx=d.idx`, params);
+            const scopes = await client.query(`DELETE FROM sync_change_scopes cs USING (
+           SELECT s.commit_seq FROM sync_change_scopes s
+            WHERE s.partition=$1 AND s.tbl=$2 AND s.var=$3 AND s.value=$4
+              AND s.commit_seq<=$5 AND NOT EXISTS (
+                SELECT 1 FROM sync_changes c
+                 WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
+                   AND c.tbl=s.tbl AND c.scopes->>$3=s.value)
+            LIMIT $6) d
+         WHERE cs.partition=$1 AND cs.tbl=$2 AND cs.var=$3 AND cs.value=$4
+           AND cs.commit_seq=d.commit_seq`, params);
+            return changes.rowCount + scopes.rowCount;
+        });
+    }
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);

package/dist/push.d.ts

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

package/dist/push.js

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

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

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

package/dist/sqlite-blob-store.js

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

package/dist/sqlite-dialect.d.ts

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

package/dist/sqlite-dialect.js

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

package/dist/sqlite-storage.d.ts

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

package/dist/sqlite-storage.js

@@ -15,7 +15,7 @@ import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './author
 import { syncError } from './errors.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';
@@ -1198,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