@syncular/client 0.15.9 → 0.15.11

package/README.md

@@ -144,6 +144,40 @@ records a sorted `changedFields` list so conflict and rejection UI knows which
 fields the user intended to touch. That intent is local-only and never enters
 `PUSH_COMMIT`; full-row `mutate` operations omit it.
 
+## Application-authorized local security purge
+
+`purgeLocalData({ purgeId, targets })` is the narrow local-storage primitive
+for an application that has already validated a server-authoritative device,
+membership, or key-revocation directive. It is available on direct clients,
+worker handles, the normalized React client, and the Tauri bridge.
+
+```ts
+const result = await client.purgeLocalData({
+  purgeId: directive.id,
+  targets: [
+    {
+      table: 'patient_notes',
+      selectors: { encryption_key_id: [directive.keyVersionId] },
+    },
+  ],
+});
+```
+
+The host MUST first quarantine the affected feature and gate/remove any
+subscription that could download the protected rows again. This method does
+not authenticate a directive, revoke server authority, delete app-owned files,
+or remove a key from the OS secure store.
+
+Within one local SQLite transaction the engine deletes exactly the matching
+synced rows, lets generated FTS triggers remove their projections, drops every
+whole pending commit with a matching operation, restores/replays unrelated
+optimistic state, reconciles blob references, persists the `purgeId`, and emits
+one revisioned change batch. A retry with the same canonical plan returns
+`alreadyApplied: true`; reusing an id with different selectors fails closed.
+Only bounded, non-empty, code-like values on plaintext string schema columns
+are accepted. There is intentionally no full-table mode. The result exposes
+counts only—never row ids or selector values.
+
 Validator rejections may include bounded `details` (`fieldPaths`, `reason`,
 `requiredAction`, and explicitly safe `references`). The details persist with
 the rejection. Treat every value as a machine hint: map known values to

package/dist/client.d.ts

@@ -13,6 +13,7 @@ import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
+import { type LocalDataPurgeInput, type LocalDataPurgeResult } from './local-purge.js';
 import { type OutboxCommit } from './outbox.js';
 import { type CommitOutcome, type CommitOutcomeQuery, type ConflictRecord, type RejectionRecord, type ResolveCommitOutcomeInput } from './outcomes.js';
 import { type ClientSchema } from './schema.js';
@@ -382,6 +383,17 @@ export declare class SyncClient {
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;
     }): string;
+    /**
+     * Apply one host-authorized local security purge. The host must stop/gate
+     * protected subscriptions before calling this method; this operation owns
+     * local SQLite cleanup only and intentionally cannot revoke server access.
+     *
+     * Selector columns are validated as bounded plaintext strings. Targets are
+     * OR-combined and each target's selectors are AND-combined. `purgeId` is
+     * persisted with the canonical plan, making exact retries no-ops while a
+     * reused id with different selectors fails closed.
+     */
+    purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
     /** Host-facing patch result with explicit network work intent (§7.5). */
     patchCommand(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;

package/dist/client.js

@@ -14,6 +14,7 @@ import { registerDevtools } from './devtools.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
+import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
@@ -1066,6 +1067,145 @@ export class SyncClient {
             },
         ], [[...normalizedPartial.keys()].sort()]);
     }
+    /**
+     * Apply one host-authorized local security purge. The host must stop/gate
+     * protected subscriptions before calling this method; this operation owns
+     * local SQLite cleanup only and intentionally cannot revoke server access.
+     *
+     * Selector columns are validated as bounded plaintext strings. Targets are
+     * OR-combined and each target's selectors are AND-combined. `purgeId` is
+     * persisted with the canonical plan, making exact retries no-ops while a
+     * reused id with different selectors fails closed.
+     */
+    purgeLocalData(input) {
+        this.#requireStarted();
+        const purge = compileLocalDataPurge(this.#schema, input);
+        const metaKey = localDataPurgeMetaKey(purge.purgeId);
+        const appliedPlan = getMeta(this.#db, metaKey);
+        if (appliedPlan !== undefined) {
+            if (appliedPlan !== purge.canonicalPlan) {
+                throw new ClientSyncError('sync.invalid_request', `local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`);
+            }
+            return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
+        }
+        const rejectionCount = this.#rejections.length;
+        try {
+            return this.#applyBatch((batch) => {
+                const initialRowIds = this.#localPurgeRowIds(purge);
+                const targetsByTable = this.#localPurgeTargetsByTable(purge);
+                const doomed = listOutbox(this.#db)
+                    .filter((commit) => {
+                    const images = new Map(listOutboxBeforeImages(this.#db, commit.clientCommitId).map((image) => [image.opIndex, image]));
+                    return commit.operations.some((operation, opIndex) => {
+                        const targets = targetsByTable.get(operation.table);
+                        if (targets === undefined)
+                            return false;
+                        if (initialRowIds.get(operation.table)?.has(operation.rowId) ===
+                            true) {
+                            return true;
+                        }
+                        if (operation.values !== undefined &&
+                            targets.some((target) => localDataPurgeTargetMatches(target, operation.values ?? {}))) {
+                            return true;
+                        }
+                        const beforeValues = images.get(opIndex)?.values;
+                        return (beforeValues !== undefined &&
+                            targets.some((target) => localDataPurgeTargetMatches(target, beforeValues)));
+                    });
+                })
+                    // Reverse order is essential: each rollback restores its before-image;
+                    // removing newest-first prevents an older doomed write reappearing.
+                    .sort((a, b) => b.seq - a.seq);
+                for (const commit of doomed) {
+                    this.#rollbackFailedCommit(commit, batch);
+                }
+                // Rollback may reveal a target row hidden by an optimistic delete or
+                // move, so select the final base/visible set only after doomed commits
+                // have been removed.
+                const rowIds = this.#localPurgeRowIds(purge);
+                let purgedRows = 0;
+                for (const [tableName, ids] of rowIds) {
+                    if (ids.size === 0)
+                        continue;
+                    const table = this.#table(tableName);
+                    const values = [...ids];
+                    purgedRows += values.length;
+                    batch.table(tableName);
+                    for (let offset = 0; offset < values.length; offset += 400) {
+                        const chunk = values.slice(offset, offset + 400);
+                        this.#db.exec(`DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN (${chunk.map(() => '?').join(', ')})`, chunk);
+                    }
+                }
+                if (doomed.length > 0) {
+                    for (const commit of doomed) {
+                        const results = commit.operations.map((operation, opIndex) => {
+                            const rejection = {
+                                clientCommitId: commit.clientCommitId,
+                                opIndex,
+                                code: 'client.local_data_purged',
+                                message: 'the commit was dropped by an application-authorized local data purge',
+                                retryable: false,
+                                operation,
+                            };
+                            this.#rejections.push(rejection);
+                            return { status: 'error', rejection };
+                        });
+                        recordCommitOutcome(this.#db, {
+                            clientCommitId: commit.clientCommitId,
+                            status: 'rejected',
+                            recordedAtMs: this.#now(),
+                            results,
+                            operations: commit.operations,
+                        });
+                    }
+                    pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+                    batch.status();
+                    batch.rejections();
+                    batch.outcomes();
+                }
+                this.#reconcileBlobs(true);
+                setMeta(this.#db, metaKey, purge.canonicalPlan);
+                return {
+                    alreadyApplied: false,
+                    purgedRows,
+                    droppedCommits: doomed.length,
+                };
+            });
+        }
+        catch (error) {
+            // SQLite rolls back through #applyBatch; mirror that rollback for the
+            // in-memory rejection cache before surfacing the storage failure.
+            this.#rejections.length = rejectionCount;
+            throw error;
+        }
+    }
+    #localPurgeTargetsByTable(purge) {
+        const byTable = new Map();
+        for (const target of purge.targets) {
+            const targets = byTable.get(target.table.name) ?? [];
+            targets.push(target);
+            byTable.set(target.table.name, targets);
+        }
+        return byTable;
+    }
+    #localPurgeRowIds(purge) {
+        const byTable = new Map();
+        for (const target of purge.targets) {
+            const ids = byTable.get(target.table.name) ?? new Set();
+            const clauses = [];
+            const params = [];
+            for (const selector of target.selectors) {
+                clauses.push(`${quoteIdent(selector.column)} IN (${selector.values.map(() => '?').join(', ')})`);
+                params.push(...selector.values);
+            }
+            for (const row of this.#db.query(`SELECT CAST(${quoteIdent(target.table.primaryKey)} AS TEXT) AS id FROM ${quoteIdent(target.table.name)} WHERE ${clauses.join(' AND ')}`, params)) {
+                if (typeof row.id === 'string')
+                    ids.add(row.id);
+            }
+            byTable.set(target.table.name, ids);
+        }
+        return byTable;
+    }
     /** Host-facing patch result with explicit network work intent (§7.5). */
     patchCommand(table, rowId, partial, options) {
         return {

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './errors.js';
 export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
+export * from './local-purge.js';
 export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export * from './errors.js';
 export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
+export * from './local-purge.js';
 export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';

package/dist/local-purge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Application-authorized local data purge.
+ *
+ * Syncular deliberately does not decide *why* a device lost access. The host
+ * validates the signed/replayed server directive, gates the corresponding
+ * subscriptions, and then hands this bounded plaintext-selector plan to the
+ * local engine. The engine owns the atomic SQLite consequences: synced rows,
+ * generated FTS projections, doomed optimistic commits, and blob references.
+ */
+import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
+/** One AND-combined selector set. Targets are OR-combined. */
+export interface LocalDataPurgeTarget {
+    readonly table: string;
+    readonly selectors: Readonly<Record<string, readonly string[]>>;
+}
+/** A durable idempotency key plus one or more exact local routing targets. */
+export interface LocalDataPurgeInput {
+    readonly purgeId: string;
+    readonly targets: readonly LocalDataPurgeTarget[];
+}
+/** Counts only; row ids and selector values never leave the local engine. */
+export interface LocalDataPurgeResult {
+    readonly alreadyApplied: boolean;
+    readonly purgedRows: number;
+    readonly droppedCommits: number;
+}
+export interface CompiledLocalDataPurgeSelector {
+    readonly column: string;
+    readonly values: readonly string[];
+}
+export interface CompiledLocalDataPurgeTarget {
+    readonly table: CompiledClientTable;
+    readonly selectors: readonly CompiledLocalDataPurgeSelector[];
+}
+export interface CompiledLocalDataPurge {
+    readonly purgeId: string;
+    readonly targets: readonly CompiledLocalDataPurgeTarget[];
+    /** Stable JSON persisted beside the purge id for collision detection. */
+    readonly canonicalPlan: string;
+}
+/** Validate and canonicalize before any transaction is entered. */
+export declare function compileLocalDataPurge(schema: CompiledClientSchema, input: LocalDataPurgeInput): CompiledLocalDataPurge;
+/** Exact AND match for one target; targets themselves are OR-combined. */
+export declare function localDataPurgeTargetMatches(target: CompiledLocalDataPurgeTarget, values: Readonly<Record<string, unknown>>): boolean;
+export declare function localDataPurgeMetaKey(purgeId: string): string;

package/dist/local-purge.js

@@ -0,0 +1,92 @@
+/**
+ * Application-authorized local data purge.
+ *
+ * Syncular deliberately does not decide *why* a device lost access. The host
+ * validates the signed/replayed server directive, gates the corresponding
+ * subscriptions, and then hands this bounded plaintext-selector plan to the
+ * local engine. The engine owns the atomic SQLite consequences: synced rows,
+ * generated FTS projections, doomed optimistic commits, and blob references.
+ */
+import { ClientSyncError } from './errors.js';
+const MAX_TARGETS = 64;
+const MAX_SELECTORS_PER_TARGET = 8;
+const MAX_VALUES_PER_SELECTOR = 128;
+const MAX_ROUTING_VALUE_LENGTH = 256;
+const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function compareCodeLike(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid(message) {
+    throw new ClientSyncError('sync.invalid_request', message);
+}
+/** Validate and canonicalize before any transaction is entered. */
+export function compileLocalDataPurge(schema, input) {
+    if (input.purgeId.length === 0 ||
+        input.purgeId.length > 128 ||
+        !CODE_LIKE_VALUE.test(input.purgeId)) {
+        invalid('local purge purgeId must be a 1–128 character code-like identifier');
+    }
+    if (input.targets.length === 0 || input.targets.length > MAX_TARGETS) {
+        invalid(`local purge needs between 1 and ${MAX_TARGETS} targets`);
+    }
+    const deduplicated = new Map();
+    for (const target of input.targets) {
+        const table = schema.tables.get(target.table);
+        if (table === undefined) {
+            invalid(`local purge names unknown table ${JSON.stringify(target.table)}`);
+        }
+        const entries = Object.entries(target.selectors);
+        if (entries.length === 0 || entries.length > MAX_SELECTORS_PER_TARGET) {
+            invalid(`local purge target ${JSON.stringify(target.table)} needs between 1 and ${MAX_SELECTORS_PER_TARGET} selectors`);
+        }
+        const selectors = entries
+            .map(([columnName, rawValues]) => {
+            const column = table.columns.find((candidate) => candidate.name === columnName);
+            if (column === undefined) {
+                invalid(`local purge target ${JSON.stringify(target.table)} names unknown column ${JSON.stringify(columnName)}`);
+            }
+            if (column.type !== 'string' || column.encrypted === true) {
+                invalid(`local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} must be a plaintext string column`);
+            }
+            if (rawValues.length === 0 ||
+                rawValues.length > MAX_VALUES_PER_SELECTOR) {
+                invalid(`local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} needs between 1 and ${MAX_VALUES_PER_SELECTOR} values`);
+            }
+            const values = [...new Set(rawValues)];
+            for (const value of values) {
+                if (typeof value !== 'string' ||
+                    value.length === 0 ||
+                    value.length > MAX_ROUTING_VALUE_LENGTH ||
+                    !CODE_LIKE_VALUE.test(value)) {
+                    invalid(`local purge selector values must be 1–${MAX_ROUTING_VALUE_LENGTH} character code-like identifiers`);
+                }
+            }
+            values.sort();
+            return { column: columnName, values };
+        })
+            .sort((a, b) => compareCodeLike(a.column, b.column));
+        const canonicalTarget = {
+            table: table.name,
+            selectors: Object.fromEntries(selectors.map((selector) => [selector.column, selector.values])),
+        };
+        deduplicated.set(JSON.stringify(canonicalTarget), { table, selectors });
+    }
+    const targets = [...deduplicated.entries()]
+        .sort(([a], [b]) => compareCodeLike(a, b))
+        .map(([, target]) => target);
+    const canonicalPlan = JSON.stringify(targets.map((target) => ({
+        table: target.table.name,
+        selectors: Object.fromEntries(target.selectors.map((selector) => [selector.column, selector.values])),
+    })));
+    return { purgeId: input.purgeId, targets, canonicalPlan };
+}
+/** Exact AND match for one target; targets themselves are OR-combined. */
+export function localDataPurgeTargetMatches(target, values) {
+    return target.selectors.every((selector) => {
+        const value = values[selector.column];
+        return typeof value === 'string' && selector.values.includes(value);
+    });
+}
+export function localDataPurgeMetaKey(purgeId) {
+    return `localPurge:${purgeId}`;
+}

package/dist/worker-entry.js

@@ -276,6 +276,7 @@ export function startSyncWorker(overrides = {}) {
             consumeEffects(result.effects);
             return result.value;
         },
+        purgeLocalData: (input) => requireClient().purgeLocalData(input),
         sync: () => {
             const running = requireClient();
             return serializedSync(() => running.sync());

package/dist/worker-host.d.ts

@@ -28,6 +28,7 @@ import type { SqlRow, SqlValue } from './database.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
+import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
 import { type CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
@@ -145,6 +146,7 @@ export declare class SyncClientHandle {
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;
     }): Promise<string>;
+    purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;

package/dist/worker-host.js

@@ -162,6 +162,9 @@ export class SyncClientHandle {
     patch(table, rowId, partial, options) {
         return this.#call('patch', [table, rowId, partial, options]);
     }
+    purgeLocalData(input) {
+        return this.#call('purgeLocalData', [input]);
+    }
     sync() {
         return this.#call('sync', []);
     }

package/dist/worker-protocol.d.ts

@@ -22,6 +22,7 @@ import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryRead
 import type { SqlRow, SqlValue } from './database.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
+import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
@@ -89,6 +90,8 @@ export interface WorkerApi {
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;
     }): string;
+    /** Application-authorized, idempotent local security purge. */
+    purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.9",
+  "version": "0.15.11",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.9"
+    "@syncular/core": "0.15.11"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.9",
+    "@syncular/server": "0.15.11",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -80,6 +80,15 @@ import {
   type LeaderLock,
   singleOwnerLock,
 } from './leader-lock';
+import {
+  type CompiledLocalDataPurge,
+  type CompiledLocalDataPurgeTarget,
+  compileLocalDataPurge,
+  type LocalDataPurgeInput,
+  type LocalDataPurgeResult,
+  localDataPurgeMetaKey,
+  localDataPurgeTargetMatches,
+} from './local-purge';
 import {
   appendOutboxCommit,
   deleteOutboxCommit,
@@ -1642,6 +1651,178 @@ export class SyncClient {
     );
   }
 
+  /**
+   * Apply one host-authorized local security purge. The host must stop/gate
+   * protected subscriptions before calling this method; this operation owns
+   * local SQLite cleanup only and intentionally cannot revoke server access.
+   *
+   * Selector columns are validated as bounded plaintext strings. Targets are
+   * OR-combined and each target's selectors are AND-combined. `purgeId` is
+   * persisted with the canonical plan, making exact retries no-ops while a
+   * reused id with different selectors fails closed.
+   */
+  purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult {
+    this.#requireStarted();
+    const purge = compileLocalDataPurge(this.#schema, input);
+    const metaKey = localDataPurgeMetaKey(purge.purgeId);
+    const appliedPlan = getMeta(this.#db, metaKey);
+    if (appliedPlan !== undefined) {
+      if (appliedPlan !== purge.canonicalPlan) {
+        throw new ClientSyncError(
+          'sync.invalid_request',
+          `local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`,
+        );
+      }
+      return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
+    }
+
+    const rejectionCount = this.#rejections.length;
+    try {
+      return this.#applyBatch((batch) => {
+        const initialRowIds = this.#localPurgeRowIds(purge);
+        const targetsByTable = this.#localPurgeTargetsByTable(purge);
+        const doomed = listOutbox(this.#db)
+          .filter((commit) => {
+            const images = new Map(
+              listOutboxBeforeImages(this.#db, commit.clientCommitId).map(
+                (image) => [image.opIndex, image],
+              ),
+            );
+            return commit.operations.some((operation, opIndex) => {
+              const targets = targetsByTable.get(operation.table);
+              if (targets === undefined) return false;
+              if (
+                initialRowIds.get(operation.table)?.has(operation.rowId) ===
+                true
+              ) {
+                return true;
+              }
+              if (
+                operation.values !== undefined &&
+                targets.some((target) =>
+                  localDataPurgeTargetMatches(target, operation.values ?? {}),
+                )
+              ) {
+                return true;
+              }
+              const beforeValues = images.get(opIndex)?.values;
+              return (
+                beforeValues !== undefined &&
+                targets.some((target) =>
+                  localDataPurgeTargetMatches(target, beforeValues),
+                )
+              );
+            });
+          })
+          // Reverse order is essential: each rollback restores its before-image;
+          // removing newest-first prevents an older doomed write reappearing.
+          .sort((a, b) => b.seq - a.seq);
+
+        for (const commit of doomed) {
+          this.#rollbackFailedCommit(commit, batch);
+        }
+
+        // Rollback may reveal a target row hidden by an optimistic delete or
+        // move, so select the final base/visible set only after doomed commits
+        // have been removed.
+        const rowIds = this.#localPurgeRowIds(purge);
+        let purgedRows = 0;
+        for (const [tableName, ids] of rowIds) {
+          if (ids.size === 0) continue;
+          const table = this.#table(tableName);
+          const values = [...ids];
+          purgedRows += values.length;
+          batch.table(tableName);
+          for (let offset = 0; offset < values.length; offset += 400) {
+            const chunk = values.slice(offset, offset + 400);
+            this.#db.exec(
+              `DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN (${chunk.map(() => '?').join(', ')})`,
+              chunk,
+            );
+          }
+        }
+
+        if (doomed.length > 0) {
+          for (const commit of doomed) {
+            const results: CommitOperationOutcome[] = commit.operations.map(
+              (operation, opIndex) => {
+                const rejection: RejectionRecord = {
+                  clientCommitId: commit.clientCommitId,
+                  opIndex,
+                  code: 'client.local_data_purged',
+                  message:
+                    'the commit was dropped by an application-authorized local data purge',
+                  retryable: false,
+                  operation,
+                };
+                this.#rejections.push(rejection);
+                return { status: 'error', rejection };
+              },
+            );
+            recordCommitOutcome(this.#db, {
+              clientCommitId: commit.clientCommitId,
+              status: 'rejected',
+              recordedAtMs: this.#now(),
+              results,
+              operations: commit.operations,
+            });
+          }
+          pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+          batch.status();
+          batch.rejections();
+          batch.outcomes();
+        }
+        this.#reconcileBlobs(true);
+        setMeta(this.#db, metaKey, purge.canonicalPlan);
+        return {
+          alreadyApplied: false,
+          purgedRows,
+          droppedCommits: doomed.length,
+        };
+      });
+    } catch (error) {
+      // SQLite rolls back through #applyBatch; mirror that rollback for the
+      // in-memory rejection cache before surfacing the storage failure.
+      this.#rejections.length = rejectionCount;
+      throw error;
+    }
+  }
+
+  #localPurgeTargetsByTable(
+    purge: CompiledLocalDataPurge,
+  ): Map<string, CompiledLocalDataPurgeTarget[]> {
+    const byTable = new Map<string, CompiledLocalDataPurgeTarget[]>();
+    for (const target of purge.targets) {
+      const targets = byTable.get(target.table.name) ?? [];
+      targets.push(target);
+      byTable.set(target.table.name, targets);
+    }
+    return byTable;
+  }
+
+  #localPurgeRowIds(purge: CompiledLocalDataPurge): Map<string, Set<string>> {
+    const byTable = new Map<string, Set<string>>();
+    for (const target of purge.targets) {
+      const ids = byTable.get(target.table.name) ?? new Set<string>();
+      const clauses: string[] = [];
+      const params: string[] = [];
+      for (const selector of target.selectors) {
+        clauses.push(
+          `${quoteIdent(selector.column)} IN (${selector.values.map(() => '?').join(', ')})`,
+        );
+        params.push(...selector.values);
+      }
+      for (const row of this.#db.query(
+        `SELECT CAST(${quoteIdent(target.table.primaryKey)} AS TEXT) AS id FROM ${quoteIdent(target.table.name)} WHERE ${clauses.join(' AND ')}`,
+        params,
+      )) {
+        if (typeof row.id === 'string') ids.add(row.id);
+      }
+      byTable.set(target.table.name, ids);
+    }
+    return byTable;
+  }
+
   /** Host-facing patch result with explicit network work intent (§7.5). */
   patchCommand(
     table: string,

package/src/index.ts

@@ -19,6 +19,7 @@ export * from './errors';
 export * from './http';
 export * from './invalidation';
 export * from './leader-lock';
+export * from './local-purge';
 export * from './multi-tab';
 export * from './naming';
 export * from './outbox';

package/src/local-purge.ts

@@ -0,0 +1,172 @@
+/**
+ * Application-authorized local data purge.
+ *
+ * Syncular deliberately does not decide *why* a device lost access. The host
+ * validates the signed/replayed server directive, gates the corresponding
+ * subscriptions, and then hands this bounded plaintext-selector plan to the
+ * local engine. The engine owns the atomic SQLite consequences: synced rows,
+ * generated FTS projections, doomed optimistic commits, and blob references.
+ */
+
+import { ClientSyncError } from './errors';
+import type { CompiledClientSchema, CompiledClientTable } from './schema';
+
+const MAX_TARGETS = 64;
+const MAX_SELECTORS_PER_TARGET = 8;
+const MAX_VALUES_PER_SELECTOR = 128;
+const MAX_ROUTING_VALUE_LENGTH = 256;
+const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function compareCodeLike(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** One AND-combined selector set. Targets are OR-combined. */
+export interface LocalDataPurgeTarget {
+  readonly table: string;
+  readonly selectors: Readonly<Record<string, readonly string[]>>;
+}
+
+/** A durable idempotency key plus one or more exact local routing targets. */
+export interface LocalDataPurgeInput {
+  readonly purgeId: string;
+  readonly targets: readonly LocalDataPurgeTarget[];
+}
+
+/** Counts only; row ids and selector values never leave the local engine. */
+export interface LocalDataPurgeResult {
+  readonly alreadyApplied: boolean;
+  readonly purgedRows: number;
+  readonly droppedCommits: number;
+}
+
+export interface CompiledLocalDataPurgeSelector {
+  readonly column: string;
+  readonly values: readonly string[];
+}
+
+export interface CompiledLocalDataPurgeTarget {
+  readonly table: CompiledClientTable;
+  readonly selectors: readonly CompiledLocalDataPurgeSelector[];
+}
+
+export interface CompiledLocalDataPurge {
+  readonly purgeId: string;
+  readonly targets: readonly CompiledLocalDataPurgeTarget[];
+  /** Stable JSON persisted beside the purge id for collision detection. */
+  readonly canonicalPlan: string;
+}
+
+function invalid(message: string): never {
+  throw new ClientSyncError('sync.invalid_request', message);
+}
+
+/** Validate and canonicalize before any transaction is entered. */
+export function compileLocalDataPurge(
+  schema: CompiledClientSchema,
+  input: LocalDataPurgeInput,
+): CompiledLocalDataPurge {
+  if (
+    input.purgeId.length === 0 ||
+    input.purgeId.length > 128 ||
+    !CODE_LIKE_VALUE.test(input.purgeId)
+  ) {
+    invalid(
+      'local purge purgeId must be a 1–128 character code-like identifier',
+    );
+  }
+  if (input.targets.length === 0 || input.targets.length > MAX_TARGETS) {
+    invalid(`local purge needs between 1 and ${MAX_TARGETS} targets`);
+  }
+
+  const deduplicated = new Map<string, CompiledLocalDataPurgeTarget>();
+  for (const target of input.targets) {
+    const table = schema.tables.get(target.table);
+    if (table === undefined) {
+      invalid(
+        `local purge names unknown table ${JSON.stringify(target.table)}`,
+      );
+    }
+    const entries = Object.entries(target.selectors);
+    if (entries.length === 0 || entries.length > MAX_SELECTORS_PER_TARGET) {
+      invalid(
+        `local purge target ${JSON.stringify(target.table)} needs between 1 and ${MAX_SELECTORS_PER_TARGET} selectors`,
+      );
+    }
+    const selectors: CompiledLocalDataPurgeSelector[] = entries
+      .map(([columnName, rawValues]) => {
+        const column = table.columns.find(
+          (candidate) => candidate.name === columnName,
+        );
+        if (column === undefined) {
+          invalid(
+            `local purge target ${JSON.stringify(target.table)} names unknown column ${JSON.stringify(columnName)}`,
+          );
+        }
+        if (column.type !== 'string' || column.encrypted === true) {
+          invalid(
+            `local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} must be a plaintext string column`,
+          );
+        }
+        if (
+          rawValues.length === 0 ||
+          rawValues.length > MAX_VALUES_PER_SELECTOR
+        ) {
+          invalid(
+            `local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} needs between 1 and ${MAX_VALUES_PER_SELECTOR} values`,
+          );
+        }
+        const values = [...new Set(rawValues)];
+        for (const value of values) {
+          if (
+            typeof value !== 'string' ||
+            value.length === 0 ||
+            value.length > MAX_ROUTING_VALUE_LENGTH ||
+            !CODE_LIKE_VALUE.test(value)
+          ) {
+            invalid(
+              `local purge selector values must be 1–${MAX_ROUTING_VALUE_LENGTH} character code-like identifiers`,
+            );
+          }
+        }
+        values.sort();
+        return { column: columnName, values };
+      })
+      .sort((a, b) => compareCodeLike(a.column, b.column));
+    const canonicalTarget = {
+      table: table.name,
+      selectors: Object.fromEntries(
+        selectors.map((selector) => [selector.column, selector.values]),
+      ),
+    };
+    deduplicated.set(JSON.stringify(canonicalTarget), { table, selectors });
+  }
+
+  const targets = [...deduplicated.entries()]
+    .sort(([a], [b]) => compareCodeLike(a, b))
+    .map(([, target]) => target);
+  const canonicalPlan = JSON.stringify(
+    targets.map((target) => ({
+      table: target.table.name,
+      selectors: Object.fromEntries(
+        target.selectors.map((selector) => [selector.column, selector.values]),
+      ),
+    })),
+  );
+  return { purgeId: input.purgeId, targets, canonicalPlan };
+}
+
+/** Exact AND match for one target; targets themselves are OR-combined. */
+export function localDataPurgeTargetMatches(
+  target: CompiledLocalDataPurgeTarget,
+  values: Readonly<Record<string, unknown>>,
+): boolean {
+  return target.selectors.every((selector) => {
+    const value = values[selector.column];
+    return typeof value === 'string' && selector.values.includes(value);
+  });
+}
+
+export function localDataPurgeMetaKey(purgeId: string): string {
+  return `localPurge:${purgeId}`;
+}

package/src/worker-entry.ts

@@ -368,6 +368,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       consumeEffects(result.effects);
       return result.value;
     },
+    purgeLocalData: (input) => requireClient().purgeLocalData(input),
     sync: () => {
       const running = requireClient();
       return serializedSync(() => running.sync());

package/src/worker-host.ts

@@ -56,6 +56,7 @@ import {
   singleOwnerLock,
   webLocksLeaderLock,
 } from './leader-lock';
+import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
 import {
   broadcastChannelFactory,
   type CrossTabChannel,
@@ -359,6 +360,10 @@ export class SyncClientHandle {
     return this.#call('patch', [table, rowId, partial, options]);
   }
 
+  purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult> {
+    return this.#call('purgeLocalData', [input]);
+  }
+
   sync(): Promise<SyncSummary> {
     return this.#call('sync', []);
   }

package/src/worker-protocol.ts

@@ -39,6 +39,7 @@ import type {
   LocalRevision,
   SyncStatusSnapshot,
 } from './invalidation';
+import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
 import type { OutboxCommit } from './outbox';
 import type {
   CommitOutcome,
@@ -133,6 +134,8 @@ export interface WorkerApi {
     partial: Readonly<Record<string, unknown>>,
     options?: { readonly baseVersion?: number },
   ): string;
+  /** Application-authorized, idempotent local security purge. */
+  purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
   sync(): Promise<SyncSummary>;
   syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];