@classytic/repo-core 0.14.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,115 @@ 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.18.0] - 2026-07-27
+
+### Added — `definePurgeStep` builder (`./cleanup`) and `resolveTenantField` (`./tenant`)
+
+#### `./cleanup` — `definePurgeStep`
+
+- **`definePurgeStep(repository, spec)`** — standard builder for the most common
+  `CleanupStep` shape: a chunked `purgeByField` over a single scope value.
+  Nearly every provider step in a domain kernel is this pattern; the builder owns
+  the invariant core so callers only declare what differs:
+  - **fail-closed scoping** — missing scope value or unavailable repository is a
+    `BLOCKER` (not a silent no-op and never an unscoped purge that would hit every
+    tenant); blocked by `SCOPE_REQUIRED:<param>` / `REPOSITORY_UNAVAILABLE:<id>`.
+  - **cancellation** — `throwIfCancelled` is called before work starts and the
+    `signal` is threaded to the kit so a cancel lands between committed chunks.
+  - **honest failure** — a failing purge returns `ok: false` so the recipe composer
+    stops (retention §8); thrown errors are caught and reported, never swallowed.
+  - **verification** — absence is re-queried after the run via `countDocuments`
+    (`spec.verifyFilter` for steps whose match filter differs from the absence proof).
+- **`PurgeStepSpec`** — declaration object: `id`, `resource`, `parameter`, `field`,
+  `strategy`, optional `retained`, `warnings`, `batchSize`, `guard(scope, ctx)`,
+  `verifyFilter(scope)`, `verifyName`.
+- **`PurgeStepRepository`** — structural subset of `StandardRepo` satisfied by any
+  kit repository that implements `purgeByField` + `countDocuments`.
+- **`SCOPE_REQUIRED`** / **`REPOSITORY_UNAVAILABLE`** — blocker-code prefix constants.
+
+#### `./tenant` — `resolveTenantField`
+
+- **`resolveTenantField(config?)`** — returns the single `tenantField` string a
+  resource layer needs for `defineResource({ tenantField })`, or `false` when the
+  config disables tenant scoping (`false` / `{ enabled: false }` / `{ strategy: 'none' }`).
+  Four spine modules hand-rolled equivalent logic independently, each re-deriving
+  `'organizationId'` as the default; one copy omitted the disable branch, making
+  that package silently un-configurable. This function is the single definition.
+
+Both additions are purely additive — no breaking changes.
+
+## [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)

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/define-purge-step.d.mts

@@ -0,0 +1,76 @@
+import { TenantPurgeOptions, TenantPurgeStrategy } from "../repository/types.mjs";
+import { CleanupStep, CleanupStepContext } from "./types.mjs";
+//#region src/cleanup/define-purge-step.d.ts
+/**
+ * The repository surface a purge step needs — a structural subset of
+ * `StandardRepo`, so any kit repository satisfies it without an adapter.
+ * Both members are optional so an engine that never wired the repository
+ * yields a BLOCKER rather than a crash.
+ */
+interface PurgeStepRepository {
+  purgeByField?(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<{
+    processed: number;
+    ok: boolean;
+    error?: {
+      message: string;
+    };
+  }>;
+  countDocuments?(filter: Record<string, unknown>): Promise<number>;
+}
+interface PurgeStepSpec {
+  /** Stable machine id, unique within a recipe. */
+  id: string;
+  /** Business record class for the preview (e.g. `'CRM contacts'`). */
+  resource: string;
+  /**
+   * Run-parameter key carrying the scope value (e.g. `'subjectId'`,
+   * `'organizationId'`). Read from `ctx.parameters` at plan AND execute time,
+   * so a retry replays the value the operator actually confirmed.
+   */
+  parameter: string;
+  /** Document field matched against the parameter's value. */
+  field: string;
+  /** What to do with matched rows. */
+  strategy: TenantPurgeStrategy;
+  /** What survives — surfaced in the preview. */
+  retained?: string;
+  /** Non-blocking operator warnings. */
+  warnings?: readonly string[];
+  /** Rows per chunk. Kit default when omitted. */
+  batchSize?: number;
+  /**
+   * Domain blockers beyond the built-in scope/availability checks (e.g.
+   * `'OPEN_CHECKOUTS:3'`). A non-empty result is a HARD STOP.
+   */
+  guard?: (scope: string, ctx: CleanupStepContext) => Promise<readonly string[]>;
+  /**
+   * Filter proving absence, when it differs from the match filter — e.g. an
+   * anonymize keyed on `_id` leaves the row in place, so absence must be
+   * proven by querying the redacted identifier instead.
+   */
+  verifyFilter?: (scope: string) => Record<string, unknown>;
+  /** Overrides the generated check name. */
+  verifyName?: string;
+}
+/** Prefix for the blocker raised when the run carries no scope value. */
+declare const SCOPE_REQUIRED = "CLEANUP_SCOPE_REQUIRED";
+/** Prefix for the blocker raised when the repository cannot be reached. */
+declare const REPOSITORY_UNAVAILABLE = "CLEANUP_REPOSITORY_UNAVAILABLE";
+/**
+ * Build a `CleanupStep` from a repository + declaration.
+ *
+ * Invariants this owns, so no caller can get them wrong:
+ *   - **fail-closed scoping** — no scope value, or no repository, is a
+ *     BLOCKER, never a silent no-op and never an unscoped purge (which would
+ *     hit every tenant);
+ *   - **cancellation** — checked before work starts and threaded to the kit so
+ *     a cancel lands between committed chunks, never mid-write;
+ *   - **honest failure** — a failing purge returns `ok: false` so the composer
+ *     stops the recipe (retention §8), and a thrown error is reported, never
+ *     swallowed;
+ *   - **verification** — absence is re-queried after the run, because a
+ *     processed count alone is never proof (§9).
+ */
+declare function definePurgeStep(repository: PurgeStepRepository | undefined, spec: PurgeStepSpec): CleanupStep;
+//#endregion
+export { PurgeStepRepository, PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/define-purge-step.mjs

@@ -0,0 +1,107 @@
+//#region src/cleanup/define-purge-step.ts
+/** Prefix for the blocker raised when the run carries no scope value. */
+const SCOPE_REQUIRED = "CLEANUP_SCOPE_REQUIRED";
+/** Prefix for the blocker raised when the repository cannot be reached. */
+const REPOSITORY_UNAVAILABLE = "CLEANUP_REPOSITORY_UNAVAILABLE";
+function scopeOf(ctx, parameter) {
+	const raw = ctx.parameters?.[parameter];
+	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+/**
+* Build a `CleanupStep` from a repository + declaration.
+*
+* Invariants this owns, so no caller can get them wrong:
+*   - **fail-closed scoping** — no scope value, or no repository, is a
+*     BLOCKER, never a silent no-op and never an unscoped purge (which would
+*     hit every tenant);
+*   - **cancellation** — checked before work starts and threaded to the kit so
+*     a cancel lands between committed chunks, never mid-write;
+*   - **honest failure** — a failing purge returns `ok: false` so the composer
+*     stops the recipe (retention §8), and a thrown error is reported, never
+*     swallowed;
+*   - **verification** — absence is re-queried after the run, because a
+*     processed count alone is never proof (§9).
+*/
+function definePurgeStep(repository, spec) {
+	const destructive = spec.strategy.type !== "skip";
+	const verifyName = spec.verifyName ?? `${spec.id}.verified`;
+	const filterFor = (scope) => spec.verifyFilter?.(scope) ?? { [spec.field]: scope };
+	return {
+		id: spec.id,
+		resource: spec.resource,
+		destructive,
+		async estimate(ctx) {
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope) return {
+				resource: spec.resource,
+				estimated: 0,
+				blockers: [`${SCOPE_REQUIRED}:${spec.parameter}`]
+			};
+			if (!repository?.purgeByField) return {
+				resource: spec.resource,
+				estimated: 0,
+				blockers: [`${REPOSITORY_UNAVAILABLE}:${spec.id}`]
+			};
+			const estimated = await repository.countDocuments?.({ [spec.field]: scope }) ?? 0;
+			const blockers = await spec.guard?.(scope, ctx) ?? [];
+			return {
+				resource: spec.resource,
+				estimated,
+				...spec.retained === void 0 ? {} : { retained: spec.retained },
+				...blockers.length > 0 ? { blockers: [...blockers] } : {},
+				...spec.warnings === void 0 ? {} : { warnings: [...spec.warnings] }
+			};
+		},
+		async execute(ctx) {
+			await ctx.throwIfCancelled?.();
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope || !repository?.purgeByField) return {
+				resource: spec.resource,
+				processed: 0,
+				ok: false,
+				error: scope ? `repository for '${spec.id}' is unavailable` : `missing run parameter '${spec.parameter}'`
+			};
+			try {
+				const result = await repository.purgeByField(spec.field, scope, spec.strategy, {
+					...spec.batchSize === void 0 ? {} : { batchSize: spec.batchSize },
+					...ctx.signal ? { signal: ctx.signal } : {},
+					onProgress: async (event) => {
+						await ctx.onProgress?.({
+							resource: spec.resource,
+							processed: event.processed
+						});
+					}
+				});
+				return {
+					resource: spec.resource,
+					processed: result.processed,
+					ok: result.ok,
+					...result.ok ? {} : { error: result.error?.message ?? "purge reported failure" }
+				};
+			} catch (error) {
+				return {
+					resource: spec.resource,
+					processed: 0,
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		},
+		async verify(ctx) {
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope || !repository?.countDocuments) return [{
+				name: verifyName,
+				ok: false,
+				detail: "could not verify — no scope or no count support"
+			}];
+			const remaining = await repository.countDocuments(filterFor(scope));
+			return [{
+				name: verifyName,
+				ok: remaining === 0,
+				detail: remaining === 0 ? `no ${spec.resource} still match the scope` : `${remaining} row(s) still match — cleanup incomplete`
+			}];
+		}
+	};
+}
+//#endregion
+export { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/index.d.mts

@@ -0,0 +1,3 @@
+import { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress } from "./types.mjs";
+import { PurgeStepRepository, PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep } from "./define-purge-step.mjs";
+export { type CleanupStep, type CleanupStepCheck, type CleanupStepContext, type CleanupStepEstimate, type CleanupStepExecuteContext, type CleanupStepLogger, type CleanupStepOutcome, type CleanupStepProgress, type PurgeStepRepository, type PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/index.mjs

@@ -0,0 +1,2 @@
+import { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep } from "./define-purge-step.mjs";
+export { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

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/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/tenant/index.d.mts

@@ -1,3 +1,3 @@
 import { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy } from "./types.mjs";
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig };
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig, resolveTenantField };

package/dist/tenant/index.mjs

@@ -1,2 +1,2 @@
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.d.mts

@@ -12,5 +12,21 @@ import { ResolvedTenantConfig, TenantConfig } from "./types.mjs";
 type TenantDefaults = { [K in 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required']-?: Exclude<TenantConfig[K], undefined>; };
 declare const DEFAULT_TENANT_CONFIG: TenantDefaults;
 declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
+/**
+ * The single `tenantField` value a resource layer wants, or `false` when the
+ * option disables scoping entirely.
+ *
+ * Packages composing an arc resource need exactly this shape for
+ * `defineResource({ tenantField })`, and four spine modules independently
+ * hand-rolled it — each re-deriving `'organizationId'` as the default and
+ * unwrapping `{ tenantField }` by hand. One of those copies omitted the
+ * disable branch, so that package silently could not be configured
+ * company-wide. This wraps {@link resolveTenantConfig} so the default, the
+ * disable semantics, and the object-unwrapping have ONE definition.
+ *
+ * `false` / `{ enabled: false }` / `{ strategy: 'none' }` all mean "no tenant
+ * scoping" and all return `false` — callers get one thing to branch on.
+ */
+declare function resolveTenantField(config?: TenantConfig | boolean): string | false;
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.mjs

@@ -51,5 +51,25 @@ function resolveTenantConfig(config) {
 		enabled: cleaned.enabled ?? true
 	};
 }
+/**
+* The single `tenantField` value a resource layer wants, or `false` when the
+* option disables scoping entirely.
+*
+* Packages composing an arc resource need exactly this shape for
+* `defineResource({ tenantField })`, and four spine modules independently
+* hand-rolled it — each re-deriving `'organizationId'` as the default and
+* unwrapping `{ tenantField }` by hand. One of those copies omitted the
+* disable branch, so that package silently could not be configured
+* company-wide. This wraps {@link resolveTenantConfig} so the default, the
+* disable semantics, and the object-unwrapping have ONE definition.
+*
+* `false` / `{ enabled: false }` / `{ strategy: 'none' }` all mean "no tenant
+* scoping" and all return `false` — callers get one thing to branch on.
+*/
+function resolveTenantField(config) {
+	const resolved = resolveTenantConfig(config);
+	if (!resolved.enabled || resolved.strategy === "none") return false;
+	return resolved.tenantField;
+}
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/testing/index.d.mts

@@ -2,5 +2,6 @@ import { AggregateOpsSupport } from "../repository/capabilities.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
+import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-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 };
+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 { runPurgeConformance } from "./purge-conformance.mjs";
 import { runUsageStoreContract } from "./usage-conformance.mjs";
-export { runLockAdapterConformance, runStandardRepoConformance, runUsageStoreContract };
+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.14.0",
+  "version": "0.18.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": [