@classytic/repo-core 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-05-17
+
+### Added — compliance-grade tenant cleanup primitive
+
+Cross-kit foundation for "what happens to this data on org-delete?" —
+GDPR right-to-be-forgotten, SOC 2 deletion timelines, HIPAA / PCI
+retention rules. Every kit (mongokit, sqlitekit, future pgkit) gets
+the same surface; arc's `cascadeDeleteForOrganization` runner composes
+on top.
+
+- **`StandardRepo.purgeByField?(field, value, strategy, options)`** — new optional method. Processes every row matching `field = value` under a declared strategy, chunked under the hood. Optional because not every store needs the surface; arc's cascade runner checks for the method at boot.
+- **`TenantPurgeStrategy`** discriminated union — four variants:
+  - `{ type: 'hard' }` — permanent removal (GDPR right-to-be-forgotten).
+  - `{ type: 'soft', deletedField?, deletedAtField? }` — recoverable; pairs with TTL indexes for eventual hard-purge.
+  - `{ type: 'anonymize', fields }` — retain rows but overwrite declared fields (HIPAA / PCI / SOX-compatible).
+  - `{ type: 'skip', reason }` — explicit opt-out with **mandatory** `reason` (compliance forcing function — silent skips are leaks).
+- **`TenantPurgeOptions`** — `batchSize`, `session`, `onProgress`, `signal`. Chunking is mandatory (10M-row tenants can't run as a single `deleteMany`); abort signal is checked between chunks (never mid-write); aborted runs return `ok: false` with cumulative `processed` count (at-least-once cleanup semantics).
+- **`TenantPurgeResult`** + **`TenantPurgeProgress`** — typed result envelope + per-chunk progress event.
+
+### Added — kit-agnostic orchestrator (`runChunkedPurge`)
+
+The chunk-loop logic — abort handling, progress emission, error-wrapping into result envelope, natural-exit on non-full batch — is identical across kits. Extracting it here means a single bug fix lands for every kit, and the surface a new kit has to implement shrinks to ~80 lines.
+
+- **`runChunkedPurge(strategy, options, port)`** — pure orchestrator (130 lines, no I/O).
+- **`PurgePort`** interface — the driving port. Each kit implements two closures: `selectChunkIds(limit)` + `applyStrategy(ids, strategy)`.
+- **`WritingPurgeStrategy`** — strategy union with `skip` excluded (orchestrator handles `skip` before the port is consulted, so ports only see `hard` / `soft` / `anonymize`).
+
+Hexagonal pattern: orchestrator is the use-case, `PurgePort` is the driving port, each kit's port factory is the adapter. Adding a new strategy (e.g. `archive`) = one union member + one case per port. Adding a new kit = one port file + ~10-line method.
+
+### Added — 8 cross-kit conformance scenarios
+
+In `src/testing/conformance.ts`, gated by the new `ConformanceFeatures.purgeByField?: boolean` flag. When both mongokit and sqlitekit pass the same scenarios, cross-kit byte-stability for tenant cleanup is provable:
+
+1. `hard` removes every matching row, leaves others intact
+2. `hard` empty match → `processed: 0`, `ok: true`
+3. `anonymize` overwrites declared fields, keeps the row
+4. `skip` is a no-op, returns reason
+5. Chunking: `batchSize` honored, `onProgress` fires per chunk
+6. Idempotent: re-running on the same tenant is a no-op
+7. Scoping: only matching rows affected (cross-tenant safety)
+8. Abort signal: stops between chunks, returns partial count + `ok: false`
+
+The `soft` strategy is intentionally NOT in the conformance suite — it requires writable `deleted` / `deletedAt` fields not present on the shared `ConformanceDoc`; each kit covers `soft` in its own integration tests.
+
+### Migration notes
+
+- **Existing kits:** the new method is optional — kits don't break. mongokit 3.14.0 and sqlitekit 0.4.0 ship implementations; older kit versions continue to work, they just can't honor a `purgeByField` call.
+- **Existing hosts:** no breaking changes. Hosts using arc's `cascadeDeleteForOrganization` automatically pick up the new strategy surface once arc 2.16.0 lands.
+- **Build sync (workspace dev):** kits need `cp -r dist/* ../mongokit/node_modules/@classytic/repo-core/dist/` etc. after a workspace bump until npm publish.
+
 ## [0.4.0] - 2026-05-04
 
 ### Added — kit-shared building blocks (consolidation)

package/dist/repository/index.d.mts

@@ -4,5 +4,6 @@ import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
-import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type UpdateInput, type UpdateManyResult, type WriteOptions, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, PurgeRetryPolicy, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WriteOptions } from "./types.mjs";
+import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type PurgeRetryPolicy, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type UpdateInput, type UpdateManyResult, type WriteOptions, type WritingPurgeStrategy, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, validatePluginOrder };

package/dist/repository/index.mjs

@@ -2,4 +2,5 @@ import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
 import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };
+import { runChunkedPurge } from "./purge.mjs";
+export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, validatePluginOrder };

package/dist/repository/purge.d.mts

@@ -0,0 +1,57 @@
+import { TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy } from "./types.mjs";
+
+//#region src/repository/purge.d.ts
+/**
+ * Strategies that perform a write. `skip` is handled by the orchestrator
+ * before the port is ever consulted, so ports only deal with the three
+ * writing variants.
+ */
+type WritingPurgeStrategy = Exclude<TenantPurgeStrategy, {
+  type: 'skip';
+}>;
+/**
+ * Driver-facing port the orchestrator drives. Each kit implements one
+ * closure over its driver primitives + the purge predicate.
+ *
+ * **Plugin-bypass invariant.** Implementations MUST bypass tenant
+ * scoping in plugin hooks — the caller's `field = value` predicate IS
+ * the authoritative scope; a tenant-injecting hook would narrow to the
+ * wrong tenant. Pass `bypassTenant: true` on inner Repository calls
+ * (which keeps audit / cache hooks active but disables tenant injection).
+ *
+ * **Throughput contract.** Implementations should issue the minimum
+ * number of round-trips a chunk requires:
+ *
+ *   - `hard` on SQLite: `DELETE FROM t WHERE field = ? LIMIT n` — 1 RT
+ *   - `hard` on Mongo: `find(filter, {_id:1}).limit(n)` + `deleteMany`
+ *     — 2 RTs (Mongo has no DELETE LIMIT)
+ *   - `soft`: read ids + updateMany with `$set: {deleted, deletedAt}` — 2 RTs
+ *   - `anonymize` static fields: read ids + updateMany — 2 RTs
+ *   - `anonymize` with function-form replacers: read docs +
+ *     `bulkWrite([updateOne, …])` — 2 RTs (vs N+1 with per-doc fan-out)
+ */
+interface PurgePort {
+  /**
+   * Process one chunk under the given strategy. Returns the row count
+   * actually touched (≤ `limit`). The orchestrator loops until this
+   * returns less than `limit` (natural exit) or the abort signal fires.
+   *
+   * Returning `0` signals "no more matching rows"; the orchestrator
+   * exits. Returning a partial batch (`< limit`) is also a terminal
+   * signal — saves one round-trip on the last chunk.
+   */
+  purgeChunk(strategy: WritingPurgeStrategy, limit: number): Promise<number>;
+}
+/**
+ * Drive a chunked purge to completion. Returns a `TenantPurgeResult`
+ * envelope describing what happened — never throws for in-strategy
+ * errors (those wrap into `result.error`); only throws for invalid
+ * input (`batchSize < 1`).
+ *
+ * @param strategy  Strategy declaration — `skip` short-circuits.
+ * @param options   Chunking + signal + progress + optional retry.
+ * @param port      Kit-specific driver glue (one `purgeChunk` method).
+ */
+declare function runChunkedPurge(strategy: TenantPurgeStrategy, options: TenantPurgeOptions, port: PurgePort): Promise<TenantPurgeResult>;
+//#endregion
+export { PurgePort, WritingPurgeStrategy, runChunkedPurge };

package/dist/repository/purge.mjs

@@ -0,0 +1,83 @@
+//#region src/repository/purge.ts
+/**
+* Drive a chunked purge to completion. Returns a `TenantPurgeResult`
+* envelope describing what happened — never throws for in-strategy
+* errors (those wrap into `result.error`); only throws for invalid
+* input (`batchSize < 1`).
+*
+* @param strategy  Strategy declaration — `skip` short-circuits.
+* @param options   Chunking + signal + progress + optional retry.
+* @param port      Kit-specific driver glue (one `purgeChunk` method).
+*/
+async function runChunkedPurge(strategy, options, port) {
+	const start = Date.now();
+	if (strategy.type === "skip") return {
+		strategy: "skip",
+		processed: 0,
+		ok: true,
+		durationMs: Date.now() - start,
+		skipReason: strategy.reason
+	};
+	const batchSize = options.batchSize ?? 1e3;
+	if (!Number.isInteger(batchSize) || batchSize < 1) throw new Error("purgeByField: batchSize must be a positive integer");
+	const retry = options.retry;
+	let processed = 0;
+	try {
+		while (true) {
+			if (options.signal?.aborted) return {
+				strategy: strategy.type,
+				processed,
+				ok: false,
+				durationMs: Date.now() - start
+			};
+			const chunkSize = await runChunkWithRetry(() => port.purgeChunk(strategy, batchSize), retry);
+			if (chunkSize === 0) break;
+			processed += chunkSize;
+			if (options.onProgress) await options.onProgress({
+				processed,
+				chunkSize,
+				elapsedMs: Date.now() - start
+			});
+			if (chunkSize < batchSize) break;
+		}
+	} catch (err) {
+		return {
+			strategy: strategy.type,
+			processed,
+			ok: false,
+			durationMs: Date.now() - start,
+			error: {
+				message: err instanceof Error ? err.message : String(err),
+				chunkOffset: processed
+			}
+		};
+	}
+	return {
+		strategy: strategy.type,
+		processed,
+		ok: true,
+		durationMs: Date.now() - start
+	};
+}
+/**
+* Run `fn` with exponential backoff when retry is enabled. Falls through
+* to a single attempt when `retry` is undefined (default behavior).
+*/
+async function runChunkWithRetry(fn, retry) {
+	if (!retry) return fn();
+	const maxAttempts = retry.maxAttempts ?? 3;
+	const baseDelayMs = retry.baseDelayMs ?? 100;
+	const shouldRetry = retry.shouldRetry ?? (() => true);
+	let lastErr;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) try {
+		return await fn();
+	} catch (err) {
+		lastErr = err;
+		if (attempt === maxAttempts - 1) break;
+		if (!shouldRetry(err, attempt + 1)) break;
+		await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
+	}
+	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+//#endregion
+export { runChunkedPurge };

package/dist/repository/types.d.mts

@@ -59,6 +59,26 @@ interface WriteOptions extends QueryOptions {
   /** Upsert on update/replace. */
   upsert?: boolean;
 }
+/**
+ * Options for the optional `findAll` verb.
+ *
+ * `sort` is intentionally `Record<string, unknown>` (not a structured
+ * `SortSpec`) so kits can keep their own driver-shaped sort representation
+ * without forcing repo-core to depend on a particular dialect. Mongokit's
+ * `findAll` accepts `SortSpec | string`; sqlitekit accepts the same shape
+ * cross-walked into ORDER BY. `limit` is the bounded-but-not-paginated
+ * cap that callers reach for when `getAll` would force an unwanted count
+ * round-trip and `findAll` without a limit would over-fetch.
+ *
+ * Both fields are optional; absence means "kit default" (typically:
+ * `sort` defaults to natural order, `limit` defaults to "no limit").
+ */
+interface FindAllOptions extends QueryOptions {
+  /** Sort disambiguating when natural order isn't acceptable. */
+  sort?: Record<string, unknown> | string;
+  /** Cap the result set at the driver level. When omitted, returns all matching docs. */
+  limit?: number;
+}
 /**
  * Delete-operation options.
  *
@@ -83,6 +103,139 @@ interface FindOneAndUpdateOptions extends QueryOptions {
   /** Insert when no doc matches. Default: false. */
   upsert?: boolean;
 }
+/**
+ * Strategy for processing rows matched by a tenant/scope field — the
+ * decision every multi-tenant host makes when an organization (or any
+ * tenant) is deleted. Each variant maps to a kit-native primitive;
+ * arc's `createOrgDeleteCascade` orchestrates the per-resource declarations.
+ *
+ * **Why a discriminated union (not an enum)**: each strategy carries
+ * its own arguments — `fields` for anonymize, `reason` for skip. The
+ * union forces callers to supply them at the type level rather than
+ * fail at runtime.
+ *
+ * **Compliance shapes covered**:
+ * - `hard` — GDPR right-to-be-forgotten, SOC 2 deletion timelines.
+ * - `soft` — recoverable deletes within audit retention windows; pairs
+ *   with TTL indexes (MongoDB `expireAfterSeconds` on `deletedAt`) for
+ *   eventual hard-purge.
+ * - `anonymize` — records that legally must outlive the tenant (audit
+ *   ledgers, financial records, medical history) but must lose PII
+ *   linkage. HIPAA / PCI / SOX-compatible.
+ * - `skip` — explicitly opt out, with a mandatory `reason` that surfaces
+ *   in audit reports.
+ */
+type TenantPurgeStrategy =
+/**
+ * Permanently remove every matching row.
+ */
+{
+  type: 'hard';
+}
+/**
+ * Mark every matching row as deleted via the soft-delete convention.
+ * Pair with `softDeletePlugin` or a TTL index for eventual cleanup.
+ */
+| {
+  type: 'soft'; /** Boolean flag field set to `true`. Default `'deleted'`. */
+  deletedField?: string; /** Timestamp field set to purge-time. Default `'deletedAt'`. */
+  deletedAtField?: string;
+}
+/**
+ * Retain every matching row but overwrite the declared fields. Field
+ * values can be static (preferred — statically inspectable for audit)
+ * or per-row functions when deterministic transforms are needed
+ * (hashing, derived identifiers).
+ */
+| {
+  type: 'anonymize';
+  fields: Record<string, unknown | ((doc: Record<string, unknown>) => unknown)>;
+}
+/**
+ * Take no action. `reason` is required — an undocumented skip is a
+ * silent compliance leak. Surfaces in audit reports + introspection.
+ */
+| {
+  type: 'skip';
+  reason: string;
+};
+/**
+ * Per-call options for `purgeByField`. Chunking is required for
+ * correctness on large tenant datasets; the kit implementation MUST
+ * honor `batchSize` to avoid OOM / lock contention.
+ */
+interface TenantPurgeOptions {
+  /** Rows per batch. Default kit-specific (typically 1000). */
+  batchSize?: number;
+  /** Driver session for transactional callers. */
+  session?: RepositorySession;
+  /** Per-chunk progress callback. `processed` is cumulative. */
+  onProgress?: (event: TenantPurgeProgress) => void | Promise<void>;
+  /**
+   * Abort signal. Kits MUST check between chunks and finalize with the
+   * cumulative `processed` count when aborted (no rollback — chunks
+   * already committed remain committed; this is at-least-once cleanup).
+   */
+  signal?: AbortSignal;
+  /**
+   * Retry transient chunk-level failures (network blips, write
+   * conflicts, busy-locks). Default `undefined` → no retry: first
+   * chunk error aborts the run. Hosts opt in for robustness:
+   *
+   * ```ts
+   * retry: {
+   *   maxAttempts: 3,         // default 3 when block present
+   *   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
+   *   shouldRetry: (err) =>   // optional: narrow retry to transient
+   *     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
+   * }
+   * ```
+   *
+   * The retry happens at the CHUNK level — already-committed chunks
+   * stay committed. A retry that eventually succeeds reports `ok: true`;
+   * one that exhausts `maxAttempts` aborts with the underlying error.
+   */
+  retry?: PurgeRetryPolicy;
+}
+/**
+ * Retry policy for `purgeByField` chunk-level failures. See
+ * `TenantPurgeOptions.retry` for the full contract.
+ */
+interface PurgeRetryPolicy {
+  /** Max attempts per chunk (including the first try). Default 3. */
+  maxAttempts?: number;
+  /** Base delay (ms) for exponential backoff. Default 100ms. */
+  baseDelayMs?: number;
+  /** Decide whether a given error is transient. Default: retry every error. */
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+/** Chunk-level progress event for `purgeByField`. */
+interface TenantPurgeProgress {
+  /** Rows processed so far (cumulative across chunks). */
+  processed: number;
+  /** Rows in the chunk that just completed. */
+  chunkSize: number;
+  /** Wall-clock ms elapsed since the call started. */
+  elapsedMs: number;
+}
+/** Final result of a `purgeByField` invocation. */
+interface TenantPurgeResult {
+  /** Strategy that actually executed (echoes input.type). */
+  strategy: TenantPurgeStrategy['type'];
+  /** Total rows processed (0 for `skip`). */
+  processed: number;
+  /** True iff the call completed without abort / error. */
+  ok: boolean;
+  /** Wall-clock ms. */
+  durationMs: number;
+  /** First error if `ok: false`. Kits abort the run on a chunk failure. */
+  error?: {
+    message: string;
+    chunkOffset: number;
+  };
+  /** Echoed for `skip` strategy. Undefined for other strategies. */
+  skipReason?: string;
+}
 /**
  * Transition spec for `StandardRepo.claim()` — a CAS state change.
  *
@@ -1258,7 +1411,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
     _id: unknown;
   } | null>;
   distinct?<T = unknown>(field: string, filter?: FilterInput, options?: QueryOptions): Promise<T[]>;
-  findAll?(filter?: FilterInput, options?: QueryOptions): Promise<TDoc[]>;
+  findAll?(filter?: FilterInput, options?: FindAllOptions): Promise<TDoc[]>;
   /**
    * Atomic "look up by filter, insert `data` if missing, return the doc."
    *
@@ -1308,6 +1461,56 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * **Promoted from optional to required in repo-core 0.2.0.**
    */
   deleteMany(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
+  /**
+   * Compliance-grade cleanup primitive — processes every row matching
+   * `field = value` under the given strategy. Powers tenant-scoped
+   * data cleanup (org delete → cascade across every multi-tenant
+   * resource) without forcing each consumer to hand-roll `deleteMany`
+   * + chunking + audit + idempotency.
+   *
+   * Strategy → kit-native primitive:
+   * - `hard`      → chunked `deleteMany({ [field]: value })`
+   * - `soft`      → chunked `updateMany` setting deleted/deletedAt
+   * - `anonymize` → chunked `updateMany` applying the field map per-row
+   * - `skip`      → no-op; `result.skipReason` echoes the declared reason
+   *
+   * **Chunking is mandatory.** Implementations MUST honor `batchSize`
+   * — a 10M-row tenant cleanup can't run as a single `deleteMany`
+   * (lock contention, oplog blowup, replication lag). Kits process
+   * rows in chunks of `batchSize` (default ~1000) and emit per-chunk
+   * `onProgress` events.
+   *
+   * **Index requirement — load-bearing for tractability.** The store
+   * MUST have an index leading with `field` (single-field
+   * `{ [field]: 1 }`, or a compound index whose first column is
+   * `field`). Without it, every chunk's selection runs a full
+   * collection / table scan — purge becomes O(n²) on large tenants
+   * and can lock the table for minutes. Verify before shipping:
+   *   - mongo: `db.coll.getIndexes()` shows an index keyed on `field`.
+   *   - sqlite: `EXPLAIN QUERY PLAN SELECT … WHERE field = ?` shows
+   *     `SEARCH … USING INDEX`, never `SCAN`.
+   *
+   * **Idempotent.** Re-running with the same arguments is safe — rows
+   * already deleted/anonymized simply don't match the next pass.
+   * Crucial for at-least-once cascade workers that may retry after
+   * partial failure.
+   *
+   * **Plugin composition.** Kits route the underlying chunked ops
+   * through their standard `before:deleteMany` / `before:updateMany`
+   * hooks so audit / cache-invalidation / observability plugins fire
+   * naturally — no separate `before:purgeByField` hook is required.
+   *
+   * **Optional method.** Kits without bulk-cleanup needs leave this
+   * undefined. Arc's `createOrgDeleteCascade` checks for the method
+   * at boot and emits a clear error naming the offending resource if
+   * a tenant-flagged resource's repo lacks it.
+   *
+   * @param field  Document field to match against (e.g. `'organizationId'`).
+   * @param value  Value the field must equal (e.g. the deleted org id).
+   * @param strategy  Strategy declaration — see {@link TenantPurgeStrategy}.
+   * @param options  Chunking, session, progress, abort signal.
+   */
+  purgeByField?(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Heterogeneous bulk write. Stays optional — kits dispatch each op
    * against the appropriate driver primitive inside a single transaction;
@@ -1407,4 +1610,4 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, PurgeRetryPolicy, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WriteOptions };

package/dist/testing/conformance.mjs

@@ -34,6 +34,7 @@ function runStandardRepoConformance(harness) {
 	const skipNoSubMinuteBuckets = !aggGate || !ops?.dateBucketSubMinute;
 	const skipNoStddev = !aggGate || !ops?.stddev;
 	const skipNoCache = !aggGate || !ops?.cache;
+	const skipNoPurge = !harness.features.purgeByField;
 	describe(`[conformance] ${harness.name}`, () => {
 		let ctx;
 		beforeEach(async () => {
@@ -1124,6 +1125,149 @@ function runStandardRepoConformance(harness) {
 				});
 			});
 		});
+		describe("purgeByField (tenant cleanup)", () => {
+			const seedTwoTenants = async () => {
+				await ctx.repo.create(harness.makeDoc({
+					name: "a-1",
+					category: "org-a"
+				}));
+				await ctx.repo.create(harness.makeDoc({
+					name: "a-2",
+					category: "org-a"
+				}));
+				await ctx.repo.create(harness.makeDoc({
+					name: "a-3",
+					category: "org-a"
+				}));
+				await ctx.repo.create(harness.makeDoc({
+					name: "b-1",
+					category: "org-b"
+				}));
+				await ctx.repo.create(harness.makeDoc({
+					name: "b-2",
+					category: "org-b"
+				}));
+			};
+			it.skipIf(skipNoPurge)("hard: removes every matching row, leaves others intact", async () => {
+				await seedTwoTenants();
+				const result = await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
+				expect(result.ok).toBe(true);
+				expect(result.strategy).toBe("hard");
+				expect(result.processed).toBe(3);
+				expect(typeof result.durationMs).toBe("number");
+				expect(await ctx.repo.count({ category: "org-a" })).toBe(0);
+				expect(await ctx.repo.count({ category: "org-b" })).toBe(2);
+			});
+			it.skipIf(skipNoPurge)("hard: empty match completes ok with processed: 0", async () => {
+				const result = await ctx.repo.purgeByField("category", "nonexistent", { type: "hard" });
+				expect(result.ok).toBe(true);
+				expect(result.processed).toBe(0);
+			});
+			it.skipIf(skipNoPurge)("anonymize: overwrites declared fields, keeps the row", async () => {
+				await seedTwoTenants();
+				const result = await ctx.repo.purgeByField("category", "org-a", {
+					type: "anonymize",
+					fields: {
+						name: "[REDACTED]",
+						notes: null
+					}
+				});
+				expect(result.ok).toBe(true);
+				expect(result.strategy).toBe("anonymize");
+				expect(result.processed).toBe(3);
+				expect(await ctx.repo.count({ category: "org-a" })).toBe(3);
+				const redacted = await ctx.repo.findAll({ category: "org-a" });
+				for (const row of redacted) {
+					expect(row.name).toBe("[REDACTED]");
+					expect(row.notes).toBeNull();
+				}
+				const others = await ctx.repo.findAll({ category: "org-b" });
+				for (const row of others) expect(row.name).not.toBe("[REDACTED]");
+			});
+			it.skipIf(skipNoPurge)("skip: no-op, returns reason and processed: 0", async () => {
+				await seedTwoTenants();
+				const result = await ctx.repo.purgeByField("category", "org-a", {
+					type: "skip",
+					reason: "audit-retained-per-SOX"
+				});
+				expect(result.ok).toBe(true);
+				expect(result.strategy).toBe("skip");
+				expect(result.processed).toBe(0);
+				expect(result.skipReason).toBe("audit-retained-per-SOX");
+				expect(await ctx.repo.count({ category: "org-a" })).toBe(3);
+				expect(await ctx.repo.count({ category: "org-b" })).toBe(2);
+			});
+			it.skipIf(skipNoPurge)("chunking: batchSize honored, onProgress fires per chunk", async () => {
+				for (let i = 0; i < 25; i++) await ctx.repo.create(harness.makeDoc({
+					name: `chunk-${i}`,
+					category: "org-chunk"
+				}));
+				const progressEvents = [];
+				expect((await ctx.repo.purgeByField("category", "org-chunk", { type: "hard" }, {
+					batchSize: 10,
+					onProgress: (event) => {
+						progressEvents.push({
+							processed: event.processed,
+							chunkSize: event.chunkSize
+						});
+					}
+				})).processed).toBe(25);
+				expect(progressEvents.length).toBe(3);
+				expect(progressEvents[0]).toEqual({
+					processed: 10,
+					chunkSize: 10
+				});
+				expect(progressEvents[1]).toEqual({
+					processed: 20,
+					chunkSize: 10
+				});
+				expect(progressEvents[2]).toEqual({
+					processed: 25,
+					chunkSize: 5
+				});
+				expect(await ctx.repo.count({ category: "org-chunk" })).toBe(0);
+			});
+			it.skipIf(skipNoPurge)("idempotent: re-running on the same tenant is a no-op", async () => {
+				await seedTwoTenants();
+				expect((await ctx.repo.purgeByField("category", "org-a", { type: "hard" })).processed).toBe(3);
+				const second = await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
+				expect(second.ok).toBe(true);
+				expect(second.processed).toBe(0);
+			});
+			it.skipIf(skipNoPurge)("scoping: only rows matching field=value are affected", async () => {
+				await seedTwoTenants();
+				const totalBefore = await ctx.repo.count({});
+				await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
+				expect(await ctx.repo.count({})).toBe(totalBefore - 3);
+				expect(await ctx.repo.count({ category: "org-b" })).toBe(2);
+			});
+			it.skipIf(skipNoPurge)("abort signal: stops between chunks, returns partial count", async () => {
+				for (let i = 0; i < 25; i++) await ctx.repo.create(harness.makeDoc({
+					name: `abort-${i}`,
+					category: "org-abort"
+				}));
+				const controller = new AbortController();
+				const result = await ctx.repo.purgeByField("category", "org-abort", { type: "hard" }, {
+					batchSize: 10,
+					signal: controller.signal,
+					onProgress: (event) => {
+						if (event.processed === 10) controller.abort();
+					}
+				});
+				expect(result.ok).toBe(false);
+				expect(result.processed).toBe(10);
+				expect(await ctx.repo.count({ category: "org-abort" })).toBe(15);
+			});
+			it.skipIf(skipNoPurge)("retry policy is plumbed through (default no retry, opt-in works)", async () => {
+				await seedTwoTenants();
+				const result = await ctx.repo.purgeByField("category", "org-a", { type: "hard" }, { retry: {
+					maxAttempts: 1,
+					baseDelayMs: 10
+				} });
+				expect(result.ok).toBe(true);
+				expect(result.processed).toBe(3);
+			});
+		});
 	});
 }
 //#endregion

package/dist/testing/types.d.mts

@@ -132,6 +132,13 @@ interface ConformanceFeatures {
   getOrCreate: boolean;
   /** `count(filter)` and `exists(filter)`. */
   countAndExists: boolean;
+  /**
+   * `purgeByField(field, value, strategy, options)` — compliance-grade
+   * tenant cleanup primitive. Both mongokit and sqlitekit ship this as
+   * of repo-core 0.x. Future kits without it leave the flag absent
+   * (defaults to false) and skip the cleanup scenarios.
+   */
+  purgeByField?: boolean;
 }
 /**
  * One-shot context produced by `harness.setup()`. Scenarios receive a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,