@classytic/repo-core 0.13.0 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,152 @@ 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.17.0] - 2026-07-25
+
+### Added — `./cleanup`: framework-free cleanup provider step contract
+
+- **`@classytic/repo-core/cleanup`** — new subpath (pure types, no runtime).
+  Domain kernels (`@classytic/flow`, `@classytic/order`, `@classytic/facts`,
+  `@classytic/ledger`, …) export `CleanupStep[]` for the data they own; a host
+  framework (`@classytic/arc/cleanup`) folds them into a Cleanup Center recipe.
+  The contract lives in repo-core so kernels stay framework-free: kernels already
+  depend on repo-core (the chunked-purge mechanics) and MUST NOT depend on arc.
+- **`CleanupStep`** — the core provider interface: `id`, `resource`, `destructive`,
+  optional `rebuildActions`; and three lifecycle methods: `estimate(ctx)` (preview
+  without mutating), `execute(ctx)` (chunked, idempotent, cancellation-aware),
+  and optional `verify(ctx)` (post-checks — a delete count alone is never success).
+- **Supporting types**: `CleanupStepContext` (injected `now`, `signal`, `ambient`,
+  `parameters`, `logger`), `CleanupStepExecuteContext` (adds `onProgress` +
+  `throwIfCancelled`), `CleanupStepEstimate` (row count, `retained`, `blockers`,
+  `warnings`), `CleanupStepOutcome` (`processed`, `ok`, `error`, `cursor`),
+  `CleanupStepCheck` (`name`, `ok`, `detail`), `CleanupStepProgress`, `CleanupStepLogger`.
+
+Purely additive — zero runtime code, type-only subpath export.
+
+## [0.16.0] - 2026-07-24
+
+### Added — `runPurgeConformance`: cross-kit chunked-purge contract suite
+
+- **`runPurgeConformance(harness)`** (from `@classytic/repo-core/testing`) —
+  proves a kit's purge port makes **stable progress for every strategy** when
+  the match set exceeds `batchSize`. Every scenario seeds more rows than one
+  batch; a chunk budget converts a non-progressing port's infinite loop into a
+  crisp assertion failure. Scenarios: hard drain, soft multi-batch WITHOUT
+  caller-supplied exclusion predicates, anonymize static + function-form,
+  exact-batch boundary, skip, empty scope, abort-between-chunks.
+- **`PurgePort` progression contract (documented, mandatory)** — successive
+  `purgeChunk` calls MUST advance through the match set for every strategy via
+  stable keyset progression (`pk > lastSeen`, advanced only after the chunk's
+  write succeeds). Re-running the bare predicate only self-advances for
+  `hard`; `soft`/`anonymize` re-select the same first chunk forever. Offsets
+  are explicitly ruled out. A port instance is single-run state.
+
+### Fixed
+
+- `purgeByField` docstring no longer claims soft/anonymized rows "simply don't
+  match the next pass" — they generally DO still match; idempotency holds by
+  outcome convergence, and within-run progression is the port's keyset
+  responsibility.
+
+## [0.15.0] - 2026-07-24
+
+### Added — `purgeByFilter`: range/filter-scoped purge + anonymize
+
+- **`StandardRepo.purgeByFilter?(filter, strategy, options)`** — the
+  range/filter-scoped sibling of `purgeByField`. Where `purgeByField` matches
+  a single `field = value` equality, this optional method takes the full
+  portable `FilterInput` (Filter IR or a plain kit-native record) and runs any
+  `TenantPurgeStrategy` (`hard` / `soft` / `anonymize` / `skip`) over the
+  matched slice. THE compliance primitive for "purge/anonymize a dimension
+  across a RANGE while RETAINING measures" — redact a PII column across a
+  `civilDate` window, hard-delete rows past a retention cutoff, soft-delete a
+  compound cohort. Returns the same `TenantPurgeResult` envelope; chunking,
+  index requirement, idempotency, plugin composition, and narrowed-write
+  re-assertion are identical to `purgeByField`. Gate on the new
+  `capabilities.purgeByFilter`.
+- **`RepoCapabilities.purgeByFilter?: boolean`** — feature-detection flag,
+  mirroring `purgeByField`.
+- **`PurgePort` doc** clarifies the two bound-predicate forms (equality-bound
+  vs filter-bound) both satisfy the single port interface, so `runChunkedPurge`
+  drives both unchanged.
+
+Strictly additive: `purgeByField`, `TenantPurgeStrategy`, and `runChunkedPurge`
+are unchanged; both new members are optional.
+
+## [0.14.0] - 2026-07-16
+
+### Added — canonical `matchesRecordFilter` (the `DataAdapter.matchesFilter` home)
+
+- **`matchesRecordFilter(item, record)`** + **`policyRecordToFilter(record)`**
+  (`@classytic/repo-core/filter`) — THE single, shared implementation of the
+  `DataAdapter.matchesFilter` seam. Evaluates arc's Mongo-record `_policyFilters`
+  (`{ ownerId }`, `{ organizationId }`, `{ $or: [{ ownerId }, { _id: { $in } }] }`)
+  against an already-fetched document IN PROCESS, by converting to the portable
+  `Filter` IR and delegating to `matchFilter` — the SAME IR kits compile to
+  SQL/Mongo, so in-memory and DB enforcement agree by construction. Every kit's
+  adapter now delegates here; **no per-kit matcher, one contract, one IR.**
+  Operator scope: `$or`/`$and`/`$nor`/`$not`, `$eq`/`$ne`/`$gt`/`$gte`/`$lt`/`$lte`,
+  `$in`/`$nin`, `$exists`, implicit-eq; fails LOUD on anything else. (Distinct from
+  `recordToFilter`, the bare-operator query normalizer that does not accept
+  `$`-prefixed or logical operators.)
+- **`matchFilter` is now fully array + id + date aware** (additive superset;
+  primitive/Date-vs-Date behavior unchanged — strict cases still short-circuit):
+  - **id coercion** — an id-like object with a meaningful `toString` (Mongo
+    `ObjectId`, `Buffer`, `Decimal128`) matches its string form, so one shared
+    matcher serves Mongo (`ObjectId` `_id`) and SQL (primitive ids) alike.
+  - **array semantics** — dot-paths fan out over subdocument arrays
+    (`items.sku` on `[{sku},{sku}]`), and a scalar condition on a leaf array
+    field matches when ANY element satisfies it (`{ tags: 'x' }`,
+    `{ scores: { $gt: 5 } }`, regex on array elements). All array unwrapping is
+    concentrated in one helper; the comparators stay pure scalar.
+  - **Date⇄ISO-string range** — `compare` coerces the string side to a date
+    instant when the other side is a genuine `Date` (mirrors `equals`), and
+    never claims ordering across a number/string type boundary (fails closed
+    instead of matching spuriously).
+  - **prototype-pollution-safe reads** — path resolution uses `Object.hasOwn`,
+    so a crafted `{ '__proto__.x': … }` / `{ constructor.name: … }` filter can
+    never traverse the prototype chain.
+- **Ability parity across kits**: mongokit's earlier standalone matcher
+  (subdocument-array fan-out, array-contains, `$regex`, ObjectId coercion) is now
+  fully covered by the shared engine — nothing was lost in consolidation.
+- **MongoDB-parity hardening** (validated against the MongoDB manual + sift.js +
+  mingo — the two industry-standard in-memory matchers). The authorization-critical
+  rule "an absent field participates in comparisons as null/undefined" is now
+  fully honored:
+  - `{ field: null }`, `$ne`, `$nin`, and a `null` MEMBER of `$in`/`$nin` all
+    match a MISSING field (a policy filter `{ status: { $ne: 'archived' } }`
+    correctly returns docs that lack the field, exactly as MongoDB does — the top
+    silent-authorization-divergence trap). `$ne: null` remains the exception
+    (requires present + non-null).
+  - `$in` accepts RegExp-literal members (`{ name: { $in: [/^a/] } }`).
+  - Comparison ops are type-bracketed (no cross-type ordering; `$gt: null` matches
+    nothing); NaN equals NaN for `$eq` (via `Object.is`, not `===`).
+  - Numeric dot-path segments resolve as positional array indices (`items.0.sku`).
+  - Documented DELIBERATE divergences: `$exists` = present-and-non-null (matches
+    the IR `exists` op + SQL `IS NOT NULL` + sift; Mongo/mingo count present-null
+    as existing); `Date`⇄ISO-string range leniency; array-literal operands are
+    element-matched not exact-matched.
+- New: 41-case matcher suite incl. the 11 researched MongoDB gotchas + adversarial
+  (prototype pollution, NaN/Infinity, boolean/zero/empty-string, empty
+  `$in`/`$or`/`$and`/`$nor`, fail-loud on unsupported operators) + a 100k-doc
+  performance smoke (linear, cached regex).
+- **Security hardening** (from a review against sift.js/mingo CVEs + the OWASP
+  NoSQL-injection / ReDoS / prototype-pollution literature):
+  - **Prototype-key denylist** on path segments — `__proto__` / `constructor` /
+    `prototype` resolve to nothing (fail-closed), string-normalized (the
+    object-path CVE-2021-23434 lesson: an array-typed segment bypassed a `===`
+    check). Closes the "match an inherited member → wrong auth answer" case and
+    the `JSON.parse('{"__proto__":…}')` own-property vector, on top of the
+    already-`Object.hasOwn` reads.
+  - **`$regex` input-length cap** (64 KiB) — ReDoS is `pattern × input`; a field
+    value longer than the cap is treated as no-match (fail-closed) so one slow
+    match can't stall the event loop and amplify across a realtime fan-out
+    (matcher runs once per subscriber per record). Pattern-side ReDoS is a
+    non-issue for framework-supplied (trusted) patterns.
+  - Reaffirmed **fail-closed** posture: comparisons never coerce across a
+    number/string type boundary (return no-match rather than JS-coerced nonsense
+    — the classic over-visibility leak), and unsupported operators throw.
+
 ## [0.13.0] - 2026-07-15
 
 ### Added — `StandardRepo.applyTransition?()` contract (state-machine CAS with history)

package/README.md

@@ -1,5 +1,7 @@
 # @classytic/repo-core
 
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
 **Driver-agnostic repository primitives.** Hooks, Filter IR, operations registry, pagination, URL query parsing, cache contract — the shared foundation for `@classytic/mongokit`, `@classytic/sqlitekit`, and future `@classytic/pgkit` / `@classytic/prismakit`.
 
 Repo-core is **infrastructure for kit authors.** End-users install a kit (mongokit / sqlitekit) and import their full API from that one namespace. Repo-core is what each kit's runtime is built on — you typically won't import it directly in application code.

package/dist/cleanup/index.d.mts

@@ -0,0 +1,2 @@
+import { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress } from "./types.mjs";
+export type { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };

package/dist/cleanup/types.d.mts

@@ -0,0 +1,167 @@
+//#region src/cleanup/types.d.ts
+/**
+ * `@classytic/repo-core/cleanup` — the framework-free **cleanup provider step**
+ * contract (data-cleanup / retention design §6.3, §6.6).
+ *
+ * A domain kernel (`@classytic/flow`, `@classytic/order`, `@classytic/facts`,
+ * `@classytic/ledger`, …) exports one or more `CleanupStep`s for the data it
+ * owns — the unit retention.md §6.6 calls "cleanup recipe steps." A host
+ * (`be-prod`) composes ordered steps into a full Cleanup Center recipe.
+ *
+ * This contract lives in repo-core — NOT in `@classytic/arc` — on purpose:
+ *
+ *   - Kernels already depend on repo-core (it owns the chunked purge mechanics,
+ *     §6.3) and MUST stay free of any host-framework dependency. A kernel that
+ *     imported `@classytic/arc/cleanup` would invert the layering.
+ *   - Arc's Cleanup Center framework (`@classytic/arc/cleanup`) imports THIS
+ *     contract and folds `CleanupStep[]` into an arc `CleanupRecipe` via its
+ *     `recipeFromSteps()` composer. One shape, two consumers, zero cycle.
+ *
+ * A step is a PURE PROVIDER: it knows only how to estimate / execute / verify a
+ * slice of its own data. It never authorizes a superadmin, reads go-live state,
+ * speaks HTTP, or opens a Mongo transaction the host didn't hand it. It reuses
+ * repo-core's own chunked-purge envelope (`TenantPurgeResult` / progress) under
+ * the hood; this contract is the composable wrapper around that envelope.
+ */
+/**
+ * Framework-free ambient a cleanup step reads. A structural SUBSET of any host
+ * cleanup context (e.g. arc's `CleanupContext`), so passing the host context
+ * straight through type-checks — no adapter object required.
+ */
+interface CleanupStepContext {
+  /** Injected clock — steps never call `new Date()` directly (testability). */
+  readonly now: Date;
+  /** Cooperative cancellation — observed between chunks. */
+  readonly signal?: AbortSignal | undefined;
+  /**
+   * Opaque host-provided ambient scope (resolved company/branch, feature
+   * gates, …). MUST be JSON-serializable — a host may persist it on a durable
+   * run so a worker in another process rebuilds the exact operation context.
+   * A step reads only what it declared it needs; nobody else inspects it.
+   */
+  readonly ambient?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Operator-supplied recipe parameters (branch id, created-before date, module
+   * set, …). Opaque + host-validated at the edge; a step reads/parses the keys
+   * it declares. Recipes are boot-time singletons, so parameters arrive HERE at
+   * plan/execute time rather than being closed over at construction. The host
+   * composer threads the plan's sealed parameters through unchanged, so a
+   * worker replays the exact same op.
+   */
+  readonly parameters?: Readonly<Record<string, unknown>> | undefined;
+  /** Optional structured logger. */
+  readonly logger?: CleanupStepLogger | undefined;
+}
+interface CleanupStepLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+/** One committed chunk's progress — folded into the host run's bounded summary. */
+interface CleanupStepProgress {
+  readonly resource: string;
+  /** Cumulative rows processed by THIS step so far. */
+  readonly processed: number;
+  /** Opaque resume cursor (keyset position) for observability. */
+  readonly cursor?: string | undefined;
+}
+/**
+ * Execution-time context — adds progress reporting + a durable-cancellation
+ * probe. Both are optional so a step is trivially runnable in a unit test with
+ * a bare `CleanupStepContext`.
+ */
+interface CleanupStepExecuteContext extends CleanupStepContext {
+  /** Report one committed chunk. Call AFTER the chunk's write commits. */
+  onProgress?(update: CleanupStepProgress): void | Promise<void>;
+  /**
+   * Throw the host's cancellation error if a cancel was requested for this run.
+   * Cheap to call between chunks; backed by the host's durable `cancelRequested`
+   * flag (source of truth) plus the in-process `signal`. Absent in a bare test
+   * context — treat as "never cancelled."
+   */
+  throwIfCancelled?(): void | Promise<void>;
+}
+/**
+ * One preview line — maps 1:1 onto a host plan item. A business record class
+ * (`'sales facts'`, `'journal entries'`), never a collection name.
+ */
+interface CleanupStepEstimate {
+  readonly resource: string;
+  /** Estimated records this step would affect. */
+  readonly estimated: number;
+  /** What this step RETAINS (e.g. `'measures kept, PII redacted'`). */
+  readonly retained?: string | undefined;
+  /**
+   * Domain blockers preventing this step (e.g. `'POSTED_BOOKS_IMMUTABLE'`,
+   * `'OPEN_TRANSFER'`). A non-empty list is a HARD STOP — the host refuses to
+   * execute until the operator resolves it. Blockers are DOMAIN facts, never a
+   * permission decision (that is the host's job).
+   */
+  readonly blockers?: readonly string[] | undefined;
+  /**
+   * Non-blocking warnings surfaced to the operator (e.g. "rebuild may take
+   * several minutes on this generation").
+   */
+  readonly warnings?: readonly string[] | undefined;
+}
+/** One executed step's outcome — maps onto a host step result. */
+interface CleanupStepOutcome {
+  readonly resource: string;
+  /** Rows this step actually processed (deleted / redacted / rebuilt). */
+  readonly processed: number;
+  /**
+   * `false` iff the step failed. The host composer STOPS the recipe on the
+   * first `ok: false` (retention §8: never return success on a provider
+   * failure) and marks the run `failed`/`partial`. A step MUST NOT swallow a
+   * failure and report `ok: true`.
+   */
+  readonly ok: boolean;
+  /** Failure message when `ok: false`. */
+  readonly error?: string | undefined;
+  /** Opaque resume cursor for observability. */
+  readonly cursor?: string | undefined;
+}
+/** One post-check — maps onto a host verification check (§9). */
+interface CleanupStepCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail?: string | undefined;
+}
+/**
+ * A cleanup PROVIDER STEP — the unit a domain kernel exports for data it owns
+ * (retention design §6.6). Composed by the host into an ordered recipe.
+ *
+ * Idempotency + chunking are the step's responsibility: `execute` must be safe
+ * to re-run after a crash/retry (keyset progression, dedupe-by-occurrence, or a
+ * naturally-idempotent rebuild), and must observe `signal` / `throwIfCancelled`
+ * between chunks so a cancel lands between committed batches, never mid-write.
+ */
+interface CleanupStep {
+  /** Stable machine id, unique within a recipe. */
+  readonly id: string;
+  /** Logical resource label for the preview (e.g. `'sales facts'`). */
+  readonly resource: string;
+  /**
+   * `true` if the step deletes/redacts data; `false` for a pure rebuild
+   * (§4.3 — rebuilding a projection is not destructive to source data). A
+   * recipe is destructive iff ANY of its steps is.
+   */
+  readonly destructive: boolean;
+  /**
+   * Projection / scaffolding rebuilds this step performs AFTER its cleanup —
+   * surfaced in the preview's `rebuildActions` (e.g. `'rebuild sales rollup'`).
+   */
+  readonly rebuildActions?: readonly string[] | undefined;
+  /** Preview WITHOUT mutating. Idempotent + side-effect-free. */
+  estimate(ctx: CleanupStepContext): Promise<CleanupStepEstimate>;
+  /** Do the work. Chunked, idempotent, cancellation-aware. */
+  execute(ctx: CleanupStepExecuteContext): Promise<CleanupStepOutcome>;
+  /**
+   * Post-checks — the step owns what "clean" means for its data (§9: a delete
+   * count alone is never success). Optional: a pure-rebuild step may skip it,
+   * though verifying the watermark/counts is strongly encouraged.
+   */
+  verify?(ctx: CleanupStepContext): Promise<readonly CleanupStepCheck[]>;
+}
+//#endregion
+export { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };

package/dist/filter/index.d.mts

@@ -3,6 +3,7 @@ import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists
 import { recordToFilter } from "./from-record.mjs";
 import { isFilter } from "./guard.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
+import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
 import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
-export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };

package/dist/filter/index.mjs

@@ -3,5 +3,6 @@ import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
 import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists, gt, gte, iEq, invert as not, isNotNull, isNull, like, lt, lte, ne, nin, or, raw, regex, startsWith } from "./builders.mjs";
 import { recordToFilter } from "./from-record.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
+import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
-export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };

package/dist/filter/match-record.d.mts

@@ -0,0 +1,19 @@
+import { Filter } from "./types.mjs";
+//#region src/filter/match-record.d.ts
+/**
+ * Convert an arc Mongo-record `_policyFilters` object into Filter IR.
+ * `{}` → `TRUE`. Throws on unsupported top-level operators.
+ */
+declare function policyRecordToFilter(record: Record<string, unknown>): Filter;
+/**
+ * Evaluate an arc Mongo-record `_policyFilters` object against a document —
+ * converts to Filter IR, then delegates to the shared {@link matchFilter}
+ * engine. THE canonical `DataAdapter.matchesFilter` implementation; every
+ * kit's adapter delegates here.
+ *
+ * @param item    The already-fetched document / row.
+ * @param filters Arc's `_policyFilters` in Mongo record syntax.
+ */
+declare function matchesRecordFilter(item: unknown, filters: Record<string, unknown>): boolean;
+//#endregion
+export { matchesRecordFilter, policyRecordToFilter };

package/dist/filter/match-record.mjs

@@ -0,0 +1,187 @@
+import { FALSE, TRUE, and, anyOf as in_, eq, gt, gte, invert as not, isNotNull, isNull, lt, lte, ne, or, regex } from "./builders.mjs";
+import { matchFilter } from "./match.mjs";
+//#region src/filter/match-record.ts
+/**
+* Mongo-record `_policyFilters` → Filter IR conversion + in-memory match.
+*
+* The CANONICAL, single home for evaluating arc's row-level policy filters
+* against an already-fetched document IN PROCESS (no DB round-trip). Every
+* kit's `DataAdapter.matchesFilter` delegates here — one contract, one IR,
+* no per-kit matcher.
+*
+* Arc's permission helpers emit policy filters in Mongo record syntax,
+* kit-agnostic (`requireOwnership` → `{ ownerId }`, multiTenant →
+* `{ organizationId }`, `requireGrant` list resolutions →
+* `{ $or: [{ ownerId }, { _id: { $in } }] }`). This module converts that
+* record into the portable {@link Filter} IR and evaluates it with the
+* shared {@link matchFilter} engine — the SAME IR kits compile to SQL /
+* Mongo, so in-memory and DB-level enforcement agree by construction.
+*
+* `matchFilter` is id-coercion aware (Mongo `ObjectId` `_id` matches its
+* string form — no kit-specific coercion) and array-aware (dot-paths fan
+* out over subdocument arrays; scalar conditions on array fields match any
+* element). See `match.ts`.
+*
+* SCOPE — the operators arc's policy filters emit. Fails LOUD on anything
+* else so a silent mismatch never masquerades as a denial:
+*
+*   logical:    $or, $and, $nor, $not
+*   comparison: implicit-eq, $eq, $ne, $gt, $gte, $lt, $lte
+*   membership: $in, $nin
+*   existence:  $exists (see divergence note below)
+*   pattern:    $regex (+ $options; RegExp literal accepted)
+*
+* MongoDB parity (validated against the MongoDB manual + sift/mingo):
+*   - Missing field ≡ null for `{field: null}`, `$ne`/`$nin`, and a `null`
+*     member of `$in`/`$nin` — the authorization-critical rule (a policy
+*     filter `{ status: { $ne: 'archived' } }` MUST return docs lacking the
+*     field, exactly as MongoDB does).
+*   - `$in` accepts RegExp-literal members (Mongo allows `/re/` in `$in`).
+*   - Comparison ops are TYPE-BRACKETED: no cross-type ordering
+*     (`{ n: { $gt: 5 } }` never matches a string `n`); `$gt: null` matches
+*     nothing. NaN equals NaN for `$eq`.
+*   - Dot-paths fan out over arrays AND resolve numeric segments as
+*     positional indices (`items.0.sku`).
+*
+* DELIBERATE divergences (documented, not bugs):
+*   - `$exists` = present-AND-non-null (a null value reads as absent),
+*     matching the shared IR `exists` op + SQL `IS NOT NULL` + sift.js.
+*     MongoDB/mingo treat present-null as existing; that would require a
+*     separate key-presence IR op threaded through every kit's SQL/Mongo
+*     compiler. Arc's built-in policy helpers never emit `$exists`; a
+*     custom filter that needs Mongo key-presence should use
+*     `{ field: { $ne: null } }` (present + non-null) or `{ field: null }`
+*     (null OR missing) instead.
+*   - `$gt`/`$lt` allow ONE cross-type leniency: a `Date` field compares
+*     against an ISO-string operand (JSON policy filters carry dates as
+*     strings). Consistent with `$eq`'s Date⇄string coercion.
+*   - An array-literal operand (`{ tags: ['a','b'] }`) is element-matched,
+*     not exact-array-matched — policy filters never assert whole-array
+*     equality.
+*
+* Distinct from {@link recordToFilter}, which is the ergonomic
+* record→IR normalizer for BARE-operator query shorthand (`{ price:
+* { gte } }`) and deliberately does NOT accept `$`-prefixed operators or
+* logical `$or`/`$and`. This function is the arc-policy-filter dialect
+* (`$`-prefixed, with logical operators).
+*/
+/** Field operators understood inside a `{ field: { ... } }` condition. */
+const FIELD_OPS = [
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin",
+	"$exists",
+	"$regex"
+];
+function isOperatorObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	if (Array.isArray(value) || value instanceof Date) return false;
+	const keys = Object.keys(value);
+	return keys.length > 0 && keys.every((k) => k.startsWith("$"));
+}
+/**
+* `$in` with MongoDB parity: a `null` member also matches a MISSING field
+* (inherits `{field: null}` semantics), and RegExp-literal members match by
+* pattern (Mongo allows `/re/` inside `$in`). Split members into
+* null / regex / scalar and OR the branches.
+*/
+function buildIn(field, members) {
+	const branches = [];
+	const scalars = [];
+	let hasNull = false;
+	for (const m of members) if (m === null || m === void 0) hasNull = true;
+	else if (m instanceof RegExp) branches.push(regex(field, m.source, m.flags));
+	else scalars.push(m);
+	if (hasNull) branches.push(isNull(field));
+	if (scalars.length > 0) branches.push(in_(field, scalars));
+	if (branches.length === 0) return FALSE;
+	return branches.length === 1 ? branches[0] : or(...branches);
+}
+/** `$nin` is the negation of `$in` — none of the members may match. */
+function buildNin(field, members) {
+	const inFilter = buildIn(field, members);
+	return inFilter.op === "false" ? TRUE : not(inFilter);
+}
+/** Convert a single `{ field: condition }` entry into a Filter IR node. */
+function fieldFilter(field, condition) {
+	if (!isOperatorObject(condition)) return condition === null ? isNull(field) : eq(field, condition);
+	const parts = [];
+	const options = typeof condition["$options"] === "string" ? condition["$options"] : void 0;
+	for (const [op, operand] of Object.entries(condition)) switch (op) {
+		case "$options": break;
+		case "$eq":
+			parts.push(operand === null ? isNull(field) : eq(field, operand));
+			break;
+		case "$ne":
+			parts.push(operand === null ? isNotNull(field) : ne(field, operand));
+			break;
+		case "$gt":
+			parts.push(gt(field, operand));
+			break;
+		case "$gte":
+			parts.push(gte(field, operand));
+			break;
+		case "$lt":
+			parts.push(lt(field, operand));
+			break;
+		case "$lte":
+			parts.push(lte(field, operand));
+			break;
+		case "$in":
+			parts.push(buildIn(field, operand ?? []));
+			break;
+		case "$nin":
+			parts.push(buildNin(field, operand ?? []));
+			break;
+		case "$exists":
+			parts.push(operand ? isNotNull(field) : isNull(field));
+			break;
+		case "$regex": {
+			const pattern = operand instanceof RegExp ? operand.source : String(operand);
+			const flags = operand instanceof RegExp ? operand.flags : options;
+			parts.push(flags ? regex(field, pattern, flags) : regex(field, pattern));
+			break;
+		}
+		default: throw new Error(`[repo-core] matchesRecordFilter: unsupported field operator '${op}'. Supported: ${FIELD_OPS.join(", ")}.`);
+	}
+	return parts.length === 1 ? parts[0] : and(...parts);
+}
+/**
+* Convert an arc Mongo-record `_policyFilters` object into Filter IR.
+* `{}` → `TRUE`. Throws on unsupported top-level operators.
+*/
+function policyRecordToFilter(record) {
+	const parts = [];
+	for (const [key, value] of Object.entries(record)) if (key === "$or") parts.push(or(...asFilterArray(value)));
+	else if (key === "$and") parts.push(and(...asFilterArray(value)));
+	else if (key === "$nor") parts.push(not(or(...asFilterArray(value))));
+	else if (key === "$not") parts.push(not(policyRecordToFilter(value)));
+	else if (key.startsWith("$")) throw new Error(`[repo-core] matchesRecordFilter: unsupported top-level operator '${key}'. Supported: $and, $or, $nor, $not.`);
+	else parts.push(fieldFilter(key, value));
+	if (parts.length === 0) return TRUE;
+	return parts.length === 1 ? parts[0] : and(...parts);
+}
+function asFilterArray(value) {
+	if (!Array.isArray(value)) throw new Error("[repo-core] matchesRecordFilter: $or/$and/$nor operand must be an array");
+	return value.map((entry) => policyRecordToFilter(entry));
+}
+/**
+* Evaluate an arc Mongo-record `_policyFilters` object against a document —
+* converts to Filter IR, then delegates to the shared {@link matchFilter}
+* engine. THE canonical `DataAdapter.matchesFilter` implementation; every
+* kit's adapter delegates here.
+*
+* @param item    The already-fetched document / row.
+* @param filters Arc's `_policyFilters` in Mongo record syntax.
+*/
+function matchesRecordFilter(item, filters) {
+	if (item === null || typeof item !== "object") return false;
+	return matchFilter(item, policyRecordToFilter(filters));
+}
+//#endregion
+export { matchesRecordFilter, policyRecordToFilter };

package/dist/filter/match.mjs

@@ -7,35 +7,26 @@ function matchFilter(doc, filter) {
 		case "and": return filter.children.every((child) => matchFilter(doc, child));
 		case "or": return filter.children.some((child) => matchFilter(doc, child));
 		case "not": return !matchFilter(doc, filter.child);
-		case "eq": return equals(getField(doc, filter.field), filter.value);
-		case "ne": return !equals(getField(doc, filter.field), filter.value);
-		case "gt": return compare(getField(doc, filter.field), filter.value) > 0;
-		case "gte": return compare(getField(doc, filter.field), filter.value) >= 0;
-		case "lt": return compare(getField(doc, filter.field), filter.value) < 0;
-		case "lte": return compare(getField(doc, filter.field), filter.value) <= 0;
-		case "in": {
-			const v = getField(doc, filter.field);
-			return filter.values.some((candidate) => equals(v, candidate));
-		}
-		case "nin": {
-			const v = getField(doc, filter.field);
-			return !filter.values.some((candidate) => equals(v, candidate));
-		}
+		case "eq": return someValue(resolve(doc, filter.field), (v) => equals(v, filter.value));
+		case "ne": return !someValue(resolve(doc, filter.field), (v) => equals(v, filter.value));
+		case "gt": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) > 0);
+		case "gte": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) >= 0);
+		case "lt": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) < 0);
+		case "lte": return someValue(resolve(doc, filter.field), (v) => compare(v, filter.value) <= 0);
+		case "in": return someValue(resolve(doc, filter.field), (v) => filter.values.some((candidate) => equals(v, candidate)));
+		case "nin": return !someValue(resolve(doc, filter.field), (v) => filter.values.some((candidate) => equals(v, candidate)));
 		case "exists": {
-			const v = getField(doc, filter.field);
-			const present = v !== void 0 && v !== null;
+			const present = fieldPresent(doc, filter.field);
 			return filter.exists ? present : !present;
 		}
 		case "like": {
-			const v = getField(doc, filter.field);
-			if (typeof v !== "string") return false;
 			const flags = filter.caseSensitivity === "sensitive" ? "" : "i";
-			return getOrCompileLike(filter.pattern, flags).test(v);
+			const re = getOrCompileLike(filter.pattern, flags);
+			return someValue(resolve(doc, filter.field), (v) => regexTest(re, v));
 		}
 		case "regex": {
-			const v = getField(doc, filter.field);
-			if (typeof v !== "string") return false;
-			return getOrCompileRegex(filter.pattern, filter.flags).test(v);
+			const re = getOrCompileRegex(filter.pattern, filter.flags);
+			return someValue(resolve(doc, filter.field), (v) => regexTest(re, v));
 		}
 		case "raw": return false;
 	}
@@ -47,27 +38,92 @@ function matchFilter(doc, filter) {
 function asPredicate(filter) {
 	return (doc) => matchFilter(doc, filter);
 }
-function getField(doc, path) {
-	if (!doc || typeof doc !== "object") return void 0;
-	const segments = path.split(".");
-	let cursor = doc;
-	for (const segment of segments) {
-		if (cursor === null || cursor === void 0) return void 0;
-		if (typeof cursor !== "object") return void 0;
-		cursor = cursor[segment];
+/**
+* Resolve a dot-path to the SET of values it reaches, fanning out over
+* arrays on intermediate segments (Mongo/JSON-path array semantics):
+* `items.sku` on `{ items: [{ sku: 1 }, { sku: 2 }] }` → `[1, 2]`. A path
+* with no array yields a single-element list, so scalar leaf ops behave
+* exactly as before. A leaf array field (`tags`) is returned as one value
+* (the array) so `equals`'s array-contains handles it.
+*/
+/**
+* Path segments that must never be resolved — reading them can surface an
+* inherited member (or, for a JSON-parsed doc where `JSON.parse('{"__proto__":
+* …}')` created a real OWN `__proto__`, a crafted value) and produce a WRONG
+* authorization answer. Denied string-normalized (the object-path CVE-2021-23434
+* lesson: an array-typed segment bypassed a `===` check). Fail closed: any
+* path touching one of these resolves to no values → no match.
+*/
+const DANGEROUS_SEGMENTS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function resolve(doc, path) {
+	let frontier = [doc];
+	for (const segment of path.split(".")) {
+		if (DANGEROUS_SEGMENTS.has(String(segment))) return [];
+		const next = [];
+		for (const node of frontier) {
+			if (node === null || node === void 0 || typeof node !== "object") continue;
+			if (Array.isArray(node)) {
+				const idx = Number(segment);
+				if (Number.isInteger(idx) && idx >= 0 && idx < node.length) next.push(node[idx]);
+				for (const el of node) if (el && typeof el === "object" && Object.hasOwn(el, segment)) next.push(el[segment]);
+			} else if (Object.hasOwn(node, segment)) next.push(node[segment]);
+		}
+		if (next.length === 0) return [];
+		frontier = next;
 	}
-	return cursor;
+	return frontier;
+}
+/** Is any value reachable at `path` present (defined + non-null)? */
+function fieldPresent(doc, path) {
+	return resolve(doc, path).some((v) => v !== void 0 && v !== null);
+}
+/**
+* Apply a scalar predicate to a resolved value SET, unwrapping leaf array
+* values so a scalar condition on an array field (`tags`, `scores`)
+* matches when ANY element satisfies it — Mongo + SQL array semantics,
+* concentrated in ONE place so `equals`/`compare`/regex stay pure scalar.
+*/
+function someValue(values, pred) {
+	for (const v of values) if (Array.isArray(v)) {
+		if (v.some(pred)) return true;
+	} else if (pred(v)) return true;
+	return false;
 }
 function equals(a, b) {
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
 	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
 	if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
 	if (b instanceof Date && typeof a === "string") return b.toISOString() === a;
-	return a === b;
+	const as = idString(a);
+	const bs = idString(b);
+	if (as !== void 0 && bs !== void 0) return as === bs;
+	return false;
+}
+/** String form of an id-like value for coercing comparison; else undefined. */
+function idString(value) {
+	if (typeof value === "string") return value;
+	if (value === null || value === void 0 || typeof value !== "object") return void 0;
+	if (Array.isArray(value)) return void 0;
+	const s = String(value);
+	return s === "[object Object]" ? void 0 : s;
 }
 function compare(a, b) {
+	if (a instanceof Date && typeof b === "string") {
+		const t = Date.parse(b);
+		if (!Number.isNaN(t)) b = new Date(t);
+	} else if (b instanceof Date && typeof a === "string") {
+		const t = Date.parse(a);
+		if (!Number.isNaN(t)) a = new Date(t);
+	}
 	const aNum = toComparable(a);
 	const bNum = toComparable(b);
 	if (aNum === void 0 || bNum === void 0) return NaN;
+	if (typeof aNum !== typeof bNum) return NaN;
 	if (aNum < bNum) return -1;
 	if (aNum > bNum) return 1;
 	return 0;
@@ -114,6 +170,21 @@ function getOrCompileRegex(pattern, flags) {
 	regexCache.set(key, re);
 	return re;
 }
+/**
+* Max string length fed to a regex `.test()`. ReDoS is `pattern × input`;
+* even a benign developer-written pattern can go quadratic on a pathological
+* INPUT string — and in a realtime fan-out the matcher runs once per
+* subscriber per record, so one slow match blocks the event loop and
+* amplifies across the whole subscriber set. A field value longer than this
+* is treated as NO MATCH (fail closed) rather than risking a stall; policy
+* filters never regex-test megabyte fields. (Trusted-source patterns make
+* pattern-side ReDoS a non-issue; this caps the input side.)
+*/
+const MAX_REGEX_INPUT = 64 * 1024;
+/** Guarded regex test: string-only, input-length-capped (see MAX_REGEX_INPUT). */
+function regexTest(re, v) {
+	return typeof v === "string" && v.length <= MAX_REGEX_INPUT && re.test(v);
+}
 /** SQL `LIKE` pattern → JS regex body. Escapes regex metachars; `%` → `.*`, `_` → `.`. */
 function likeToRegex(pattern) {
 	let out = "";

package/dist/repository/capabilities.d.mts

@@ -126,6 +126,15 @@ interface RepoCapabilities {
    * tenant cleanup primitive.
    */
   purgeByField?: boolean;
+  /**
+   * `purgeByFilter(filter, strategy, options)` — range/filter-scoped
+   * variant of `purgeByField`. Processes rows matching an arbitrary
+   * compiled filter (a `civilDate` window, a retention cutoff, a compound
+   * cohort) rather than a single `field = value` equality — the GDPR /
+   * retention "anonymize a slice across a RANGE while retaining measures"
+   * primitive.
+   */
+  purgeByFilter?: boolean;
   /**
    * `archiveByFilter(filter, sink, options)` — chunked cold-storage
    * extraction (write-before-delete, at-least-once). The data-lifecycle

package/dist/repository/purge.d.mts

@@ -12,11 +12,30 @@ type WritingPurgeStrategy = Exclude<TenantPurgeStrategy, {
  * Driver-facing port the orchestrator drives. Each kit implements one
  * closure over its driver primitives + the purge predicate.
  *
+ * **Bound-predicate forms.** The port binds its selection predicate
+ * internally — the orchestrator never sees it. Two factory shapes both
+ * satisfy this single interface:
+ *
+ *   - **Equality-bound** (`purgeByField`): the predicate is
+ *     `{ [field]: value }` — the classic tenant-scoped cleanup where an
+ *     organization id equals the deleted tenant.
+ *   - **Filter-bound** (`purgeByFilter`): the predicate is a compiled
+ *     range/compound filter (e.g. a `civilDate` window `gte/lte`,
+ *     `{ status: 'archived', createdAt: { $lt: cutoff } }`). This is the
+ *     GDPR/retention "anonymize a PII dimension across a range while
+ *     RETAINING measures" op — no native equality analogue. Mirrors how
+ *     the archive port's factory (`createMongoArchivePort`) binds a
+ *     pre-compiled Filter rather than a `field/value` pair.
+ *
+ * Because `runChunkedPurge` drives ANY `PurgePort`, both factories reuse
+ * the same orchestrator unchanged — only the bound base predicate differs.
+ *
  * **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).
+ * scoping in plugin hooks — the caller's bound predicate (`field = value`
+ * OR the compiled filter) 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:
@@ -38,6 +57,23 @@ interface PurgePort {
    * 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.
+   *
+   * **PROGRESSION CONTRACT (mandatory).** Successive calls MUST advance
+   * through the match set for EVERY strategy. `hard` advances naturally
+   * (deleted rows leave the predicate's match set) — but `soft` and
+   * `anonymize` mutate rows that usually STILL satisfy the base
+   * predicate, so a port that re-runs `find(filter).limit(n)` re-selects
+   * the same first chunk forever and the orchestrator never terminates.
+   * Implementations must use **stable keyset progression**: order by the
+   * primary key and keep an internal `pk > lastSeen` cursor across calls
+   * (advance it only after the chunk's write succeeds, so a retried
+   * chunk re-selects the same rows). Offsets (`skip`) are not acceptable
+   * — they shift under concurrent writes and re-scan the head.
+   *
+   * A port instance is single-run state: build a fresh port per
+   * `runChunkedPurge` invocation, never share one across runs.
+   * `runPurgeConformance` (from `@classytic/repo-core/testing`) proves a
+   * kit satisfies this contract with match sets larger than `batchSize`.
    */
   purgeChunk(strategy: WritingPurgeStrategy, limit: number): Promise<number>;
 }

package/dist/repository/types.d.mts

@@ -1598,10 +1598,13 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    *   - 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.
+   * **Idempotent by outcome.** Re-running with the same arguments is
+   * safe: `hard` rows are gone, and `soft`/`anonymize` rows converge to
+   * the same terminal field values on a second pass (the rows generally
+   * DO still match the predicate — which is exactly why ports must use
+   * keyset progression, not re-selection, to advance WITHIN a run; see
+   * the {@link PurgePort} progression contract). 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`
@@ -1619,6 +1622,41 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * @param options  Chunking, session, progress, abort signal.
    */
   purgeByField?(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  /**
+   * Range/filter-scoped variant of {@link purgeByField} — processes every
+   * row matching an arbitrary `filter` (not just `field = value`) under the
+   * given {@link TenantPurgeStrategy}. The compliance primitive for
+   * "purge/anonymize a slice across a RANGE while retaining measures":
+   * redact a PII dimension across a `civilDate` window, hard-delete rows
+   * older than a retention cutoff, soft-delete a compound-predicate cohort.
+   *
+   * `purgeByField(field, value, ...)` is the equality special case
+   * (`{ [field]: value }`); this method takes the full portable
+   * {@link FilterInput} (Filter IR or a plain kit-native record), compiled
+   * once by the kit before the chunk loop — the same dual-dialect rule
+   * every other verb follows.
+   *
+   * Everything else is identical to `purgeByField`:
+   * - Strategy → kit-native primitive (`hard`/`soft`/`anonymize`/`skip`).
+   * - **Chunking mandatory** — implementations MUST honor `batchSize`.
+   * - **Index requirement** — the filter's leading field(s) MUST be indexed
+   *   or every chunk re-scans the collection / table.
+   * - **Idempotent** — re-running with the same arguments is safe; already
+   *   purged rows simply don't match the next pass.
+   * - **Plugin composition** — the chunked ops route through the kit's
+   *   `before:deleteMany` / `before:updateMany` hooks so audit /
+   *   cache-invalidation / observability plugins fire naturally.
+   * - **Narrowed-write re-assertion** — kits re-assert the base filter on
+   *   the `{ _id: { $in: ids }, ...filter }` write, defending against a row
+   *   that left the matching set between the id select and the write.
+   *
+   * Optional method; gate on `capabilities.purgeByFilter`.
+   *
+   * @param filter   Predicate selecting rows to purge (Filter IR or record).
+   * @param strategy Strategy declaration — see {@link TenantPurgeStrategy}.
+   * @param options  Chunking, session, progress, abort signal.
+   */
+  purgeByFilter?(filter: FilterInput, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Chunked cold-storage extraction — move every row matching `filter`
    * into a host-provided {@link ArchiveSink}, then remove it from the hot

package/dist/testing/index.d.mts

@@ -3,4 +3,5 @@ import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHar
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
 import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runStandardRepoConformance, runUsageStoreContract };
+import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-conformance.mjs";
+export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,4 +1,5 @@
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
 import { runUsageStoreContract } from "./usage-conformance.mjs";
-export { runLockAdapterConformance, runStandardRepoConformance, runUsageStoreContract };
+import { runPurgeConformance } from "./purge-conformance.mjs";
+export { runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/purge-conformance.d.mts

@@ -0,0 +1,33 @@
+import { TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy } from "../repository/types.mjs";
+//#region src/testing/purge-conformance.d.ts
+/** Everything the shared scenarios need from a kit. */
+interface PurgeConformanceContext {
+  /**
+   * Seed `inScope` docs matching the purge scope and `outOfScope` docs
+   * outside it. Every in-scope doc must carry:
+   *   - a string field `email` set to `'user-<i>@test.local'` (anonymize target);
+   *   - a numeric field `amount` (a measure that must SURVIVE soft/anonymize).
+   */
+  seed(inScope: number, outOfScope: number): Promise<void>;
+  /** Run the kit's chunked purge over the bound scope. */
+  purge(strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  /** RAW physical count of in-scope rows — MUST bypass soft-delete query filters. */
+  countRaw(): Promise<number>;
+  /** RAW count of in-scope rows carrying the soft-deleted flag. */
+  countSoftFlagged(): Promise<number>;
+  /** RAW count of in-scope rows whose `email` equals `value`. */
+  countEmail(value: string): Promise<number>;
+  /** RAW sum of `amount` across in-scope rows (proves measures retained). */
+  sumAmount(): Promise<number>;
+  /** RAW physical count of OUT-of-scope rows — must never change. */
+  countOutOfScope(): Promise<number>;
+}
+interface PurgeConformanceHarness {
+  /** Kit name — the top-level describe() label. */
+  name: string;
+  /** Fresh isolated context per test (own collection/table). */
+  setup(): Promise<PurgeConformanceContext>;
+}
+declare function runPurgeConformance(harness: PurgeConformanceHarness): void;
+//#endregion
+export { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance };

package/dist/testing/purge-conformance.mjs

@@ -0,0 +1,160 @@
+import { beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/purge-conformance.ts
+/**
+* `runPurgeConformance` — cross-kit chunked-purge contract suite.
+*
+* Proves a kit's `purgeByField`/`purgeByFilter` port makes **stable
+* progress for EVERY strategy** when the match set exceeds `batchSize`
+* — the exact property the naive "re-query the same predicate" port
+* shape violates: `hard` self-advances (deleted rows leave the match
+* set) but `soft`/`anonymize` re-select the same first chunk forever
+* because the mutated rows still satisfy the base predicate.
+*
+* Every scenario seeds MORE rows than `batchSize`, so a port without
+* keyset progression fails here instead of hanging production. A chunk
+* budget (via `onProgress` + abort) converts the would-be infinite loop
+* into a crisp assertion failure.
+*
+* ## Usage from a kit
+*
+*     import { runPurgeConformance } from '@classytic/repo-core/testing';
+*
+*     describe('mongokit purge conformance', () => {
+*       runPurgeConformance({
+*         name: 'mongokit',
+*         async setup() { …return a PurgeConformanceContext… },
+*       });
+*     });
+*/
+const IN_SCOPE = 25;
+const OUT_SCOPE = 5;
+const BATCH = 10;
+const AMOUNT_EACH = 7;
+/**
+* Wrap TenantPurgeOptions with a chunk budget: when the port stops
+* progressing, the loop would otherwise run forever — the budget aborts
+* it after `limit` chunks so the suite fails with a readable assertion
+* instead of a vitest timeout.
+*/
+function budgeted(limit, chunks = []) {
+	const controller = new AbortController();
+	return {
+		batchSize: BATCH,
+		signal: controller.signal,
+		onProgress({ chunkSize }) {
+			chunks.push(chunkSize);
+			if (chunks.length >= limit) controller.abort();
+		}
+	};
+}
+/** ceil(25/10) + 1 slack — a progressing port never needs more. */
+const CHUNK_BUDGET = Math.ceil(IN_SCOPE / BATCH) + 1;
+function runPurgeConformance(harness) {
+	describe(`${harness.name} — chunked purge conformance`, () => {
+		let ctx;
+		beforeEach(async () => {
+			ctx = await harness.setup();
+		});
+		it("hard: drains a multi-batch scope exactly once per row", async () => {
+			await ctx.seed(IN_SCOPE, OUT_SCOPE);
+			const chunks = [];
+			const res = await ctx.purge({ type: "hard" }, budgeted(CHUNK_BUDGET, chunks));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(IN_SCOPE);
+			expect(chunks).toEqual([
+				10,
+				10,
+				5
+			]);
+			expect(await ctx.countRaw()).toBe(0);
+			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
+		});
+		it("soft: progresses across batches WITHOUT caller-supplied exclusion predicates", async () => {
+			await ctx.seed(IN_SCOPE, OUT_SCOPE);
+			const chunks = [];
+			const res = await ctx.purge({ type: "soft" }, budgeted(CHUNK_BUDGET, chunks));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(IN_SCOPE);
+			expect(chunks).toEqual([
+				10,
+				10,
+				5
+			]);
+			expect(await ctx.countRaw()).toBe(IN_SCOPE);
+			expect(await ctx.countSoftFlagged()).toBe(IN_SCOPE);
+			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
+		});
+		it("anonymize (static): progresses across batches and retains measures", async () => {
+			await ctx.seed(IN_SCOPE, OUT_SCOPE);
+			const chunks = [];
+			const res = await ctx.purge({
+				type: "anonymize",
+				fields: { email: "redacted@example.invalid" }
+			}, budgeted(CHUNK_BUDGET, chunks));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(IN_SCOPE);
+			expect(chunks).toEqual([
+				10,
+				10,
+				5
+			]);
+			expect(await ctx.countEmail("redacted@example.invalid")).toBe(IN_SCOPE);
+			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+			expect(await ctx.countRaw()).toBe(IN_SCOPE);
+			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
+		});
+		it("anonymize (function-form): progresses across batches", async () => {
+			await ctx.seed(IN_SCOPE, OUT_SCOPE);
+			const res = await ctx.purge({
+				type: "anonymize",
+				fields: { email: () => "fn-redacted@example.invalid" }
+			}, budgeted(CHUNK_BUDGET));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(IN_SCOPE);
+			expect(await ctx.countEmail("fn-redacted@example.invalid")).toBe(IN_SCOPE);
+			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+		});
+		it("exact-batch boundary: inScope === batchSize processes each row once", async () => {
+			await ctx.seed(BATCH, OUT_SCOPE);
+			const res = await ctx.purge({ type: "soft" }, budgeted(CHUNK_BUDGET));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(BATCH);
+			expect(await ctx.countSoftFlagged()).toBe(BATCH);
+		});
+		it("skip: declared no-op reaches no rows", async () => {
+			await ctx.seed(3, 0);
+			const res = await ctx.purge({
+				type: "skip",
+				reason: "retention-owned"
+			});
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(0);
+			expect(res.skipReason).toBe("retention-owned");
+			expect(await ctx.countRaw()).toBe(3);
+		});
+		it("empty scope: terminates immediately with zero processed", async () => {
+			await ctx.seed(0, OUT_SCOPE);
+			const res = await ctx.purge({ type: "hard" }, budgeted(CHUNK_BUDGET));
+			expect(res.ok).toBe(true);
+			expect(res.processed).toBe(0);
+			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
+		});
+		it("abort between chunks: committed chunks stay, result is ok:false", async () => {
+			await ctx.seed(IN_SCOPE, OUT_SCOPE);
+			const controller = new AbortController();
+			const res = await ctx.purge({ type: "hard" }, {
+				batchSize: BATCH,
+				signal: controller.signal,
+				onProgress() {
+					controller.abort();
+				}
+			});
+			expect(res.ok).toBe(false);
+			expect(res.processed).toBe(BATCH);
+			expect(await ctx.countRaw()).toBe(IN_SCOPE - BATCH);
+		});
+	});
+}
+//#endregion
+export { runPurgeConformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.13.0",
+  "version": "0.17.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,
@@ -102,6 +102,10 @@
     "./sync": {
       "types": "./dist/sync/index.d.mts",
       "default": "./dist/sync/index.mjs"
+    },
+    "./cleanup": {
+      "types": "./dist/cleanup/index.d.mts",
+      "default": "./dist/cleanup/index.mjs"
     }
   },
   "keywords": [