@classytic/repo-core 0.4.2 → 0.6.0

package/dist/repository/types.d.mts

@@ -2,7 +2,9 @@ import { Filter } from "../filter/types.mjs";
 import { OffsetPaginationResult } from "../pagination/types.mjs";
 import { LookupPopulateOptions, LookupPopulateResult, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
+import { RepoCapabilities } from "./capabilities.mjs";
 import { CacheOptions } from "../cache/options.mjs";
+import { RetryPolicy } from "./resilience.mjs";
 
 //#region src/repository/types.d.ts
 /**
@@ -51,6 +53,18 @@ interface QueryOptions {
   user?: Record<string, unknown>;
   /** Arc request context (orgId, roles, requestId, ...). */
   context?: Record<string, unknown>;
+  /**
+   * Abort signal. Kits check it at the op boundary (and between chunks of
+   * chunked work) — cancelled requests stop before the next driver
+   * round-trip. Aborting never rolls back a write that already committed.
+   */
+  signal?: AbortSignal;
+  /**
+   * Retry transient driver failures with exponential backoff. Same shape
+   * everywhere (`TenantPurgeOptions.retry`, kit-internal loops) — see
+   * {@link RetryPolicy}. Default: no retry.
+   */
+  retryPolicy?: RetryPolicy;
   /** Driver-specific escape hatch — see JSDoc. */
   [key: string]: unknown;
 }
@@ -103,6 +117,127 @@ interface FindOneAndUpdateOptions extends QueryOptions {
   /** Insert when no doc matches. Default: false. */
   upsert?: boolean;
 }
+/**
+ * Strategy for processing rows matched by a tenant/scope field — the
+ * decision every multi-tenant host makes when an organization (or any
+ * tenant) is deleted. Each variant maps to a kit-native primitive;
+ * arc's `createOrgDeleteCascade` orchestrates the per-resource declarations.
+ *
+ * **Why a discriminated union (not an enum)**: each strategy carries
+ * its own arguments — `fields` for anonymize, `reason` for skip. The
+ * union forces callers to supply them at the type level rather than
+ * fail at runtime.
+ *
+ * **Compliance shapes covered**:
+ * - `hard` — GDPR right-to-be-forgotten, SOC 2 deletion timelines.
+ * - `soft` — recoverable deletes within audit retention windows; pairs
+ *   with TTL indexes (MongoDB `expireAfterSeconds` on `deletedAt`) for
+ *   eventual hard-purge.
+ * - `anonymize` — records that legally must outlive the tenant (audit
+ *   ledgers, financial records, medical history) but must lose PII
+ *   linkage. HIPAA / PCI / SOX-compatible.
+ * - `skip` — explicitly opt out, with a mandatory `reason` that surfaces
+ *   in audit reports.
+ */
+type TenantPurgeStrategy =
+/**
+ * Permanently remove every matching row.
+ */
+{
+  type: 'hard';
+}
+/**
+ * Mark every matching row as deleted via the soft-delete convention.
+ * Pair with `softDeletePlugin` or a TTL index for eventual cleanup.
+ */
+| {
+  type: 'soft'; /** Boolean flag field set to `true`. Default `'deleted'`. */
+  deletedField?: string; /** Timestamp field set to purge-time. Default `'deletedAt'`. */
+  deletedAtField?: string;
+}
+/**
+ * Retain every matching row but overwrite the declared fields. Field
+ * values can be static (preferred — statically inspectable for audit)
+ * or per-row functions when deterministic transforms are needed
+ * (hashing, derived identifiers).
+ */
+| {
+  type: 'anonymize';
+  fields: Record<string, unknown | ((doc: Record<string, unknown>) => unknown)>;
+}
+/**
+ * Take no action. `reason` is required — an undocumented skip is a
+ * silent compliance leak. Surfaces in audit reports + introspection.
+ */
+| {
+  type: 'skip';
+  reason: string;
+};
+/**
+ * Per-call options for `purgeByField`. Chunking is required for
+ * correctness on large tenant datasets; the kit implementation MUST
+ * honor `batchSize` to avoid OOM / lock contention.
+ */
+interface TenantPurgeOptions {
+  /** Rows per batch. Default kit-specific (typically 1000). */
+  batchSize?: number;
+  /** Driver session for transactional callers. */
+  session?: RepositorySession;
+  /** Per-chunk progress callback. `processed` is cumulative. */
+  onProgress?: (event: TenantPurgeProgress) => void | Promise<void>;
+  /**
+   * Abort signal. Kits MUST check between chunks and finalize with the
+   * cumulative `processed` count when aborted (no rollback — chunks
+   * already committed remain committed; this is at-least-once cleanup).
+   */
+  signal?: AbortSignal;
+  /**
+   * Retry transient chunk-level failures (network blips, write
+   * conflicts, busy-locks). Default `undefined` → no retry: first
+   * chunk error aborts the run. Hosts opt in for robustness:
+   *
+   * ```ts
+   * retry: {
+   *   maxAttempts: 3,         // default 3 when block present
+   *   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
+   *   shouldRetry: (err) =>   // optional: narrow retry to transient
+   *     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
+   * }
+   * ```
+   *
+   * The retry happens at the CHUNK level — already-committed chunks
+   * stay committed. A retry that eventually succeeds reports `ok: true`;
+   * one that exhausts `maxAttempts` aborts with the underlying error.
+   */
+  retry?: RetryPolicy;
+}
+/** Chunk-level progress event for `purgeByField`. */
+interface TenantPurgeProgress {
+  /** Rows processed so far (cumulative across chunks). */
+  processed: number;
+  /** Rows in the chunk that just completed. */
+  chunkSize: number;
+  /** Wall-clock ms elapsed since the call started. */
+  elapsedMs: number;
+}
+/** Final result of a `purgeByField` invocation. */
+interface TenantPurgeResult {
+  /** Strategy that actually executed (echoes input.type). */
+  strategy: TenantPurgeStrategy['type'];
+  /** Total rows processed (0 for `skip`). */
+  processed: number;
+  /** True iff the call completed without abort / error. */
+  ok: boolean;
+  /** Wall-clock ms. */
+  durationMs: number;
+  /** First error if `ok: false`. Kits abort the run on a chunk failure. */
+  error?: {
+    message: string;
+    chunkOffset: number;
+  };
+  /** Echoed for `skip` strategy. Undefined for other strategies. */
+  skipReason?: string;
+}
 /**
  * Transition spec for `StandardRepo.claim()` — a CAS state change.
  *
@@ -1142,6 +1277,18 @@ interface MinimalRepo<TDoc> {
  * kit-native.
  */
 interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
+  /**
+   * Runtime capability descriptor — feature-detection at boot instead of
+   * `UnsupportedOperationError` at runtime. Required: every kit declares
+   * what its backend supports (`arrayOperators`, `changeStreams`,
+   * `aggregateOps.percentile`, ...) so kit-portable hosts and arc can
+   * branch once instead of try/catching per call.
+   *
+   * The same shape gates the cross-kit conformance suite
+   * (`ConformanceFeatures` is an alias) — runtime declaration and test
+   * coverage cannot drift.
+   */
+  readonly capabilities: RepoCapabilities;
   /**
    * Atomic compare-and-set. Match one document, mutate it, return the
    * post-update doc (or pre-update when `returnDocument: 'before'`).
@@ -1328,6 +1475,56 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * **Promoted from optional to required in repo-core 0.2.0.**
    */
   deleteMany(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
+  /**
+   * Compliance-grade cleanup primitive — processes every row matching
+   * `field = value` under the given strategy. Powers tenant-scoped
+   * data cleanup (org delete → cascade across every multi-tenant
+   * resource) without forcing each consumer to hand-roll `deleteMany`
+   * + chunking + audit + idempotency.
+   *
+   * Strategy → kit-native primitive:
+   * - `hard`      → chunked `deleteMany({ [field]: value })`
+   * - `soft`      → chunked `updateMany` setting deleted/deletedAt
+   * - `anonymize` → chunked `updateMany` applying the field map per-row
+   * - `skip`      → no-op; `result.skipReason` echoes the declared reason
+   *
+   * **Chunking is mandatory.** Implementations MUST honor `batchSize`
+   * — a 10M-row tenant cleanup can't run as a single `deleteMany`
+   * (lock contention, oplog blowup, replication lag). Kits process
+   * rows in chunks of `batchSize` (default ~1000) and emit per-chunk
+   * `onProgress` events.
+   *
+   * **Index requirement — load-bearing for tractability.** The store
+   * MUST have an index leading with `field` (single-field
+   * `{ [field]: 1 }`, or a compound index whose first column is
+   * `field`). Without it, every chunk's selection runs a full
+   * collection / table scan — purge becomes O(n²) on large tenants
+   * and can lock the table for minutes. Verify before shipping:
+   *   - mongo: `db.coll.getIndexes()` shows an index keyed on `field`.
+   *   - sqlite: `EXPLAIN QUERY PLAN SELECT … WHERE field = ?` shows
+   *     `SEARCH … USING INDEX`, never `SCAN`.
+   *
+   * **Idempotent.** Re-running with the same arguments is safe — rows
+   * already deleted/anonymized simply don't match the next pass.
+   * Crucial for at-least-once cascade workers that may retry after
+   * partial failure.
+   *
+   * **Plugin composition.** Kits route the underlying chunked ops
+   * through their standard `before:deleteMany` / `before:updateMany`
+   * hooks so audit / cache-invalidation / observability plugins fire
+   * naturally — no separate `before:purgeByField` hook is required.
+   *
+   * **Optional method.** Kits without bulk-cleanup needs leave this
+   * undefined. Arc's `createOrgDeleteCascade` checks for the method
+   * at boot and emits a clear error naming the offending resource if
+   * a tenant-flagged resource's repo lacks it.
+   *
+   * @param field  Document field to match against (e.g. `'organizationId'`).
+   * @param value  Value the field must equal (e.g. the deleted org id).
+   * @param strategy  Strategy declaration — see {@link TenantPurgeStrategy}.
+   * @param options  Chunking, session, progress, abort signal.
+   */
+  purgeByField?(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Heterogeneous bulk write. Stays optional — kits dispatch each op
    * against the appropriate driver primitive inside a single transaction;
@@ -1425,6 +1622,51 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * ```
    */
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  /**
+   * Portable change feed — `for await` over committed mutations:
+   *
+   * ```ts
+   * for await (const change of repo.watch!({ status: 'pending' })) {
+   *   if (change.operation === 'create') enqueue(change.doc!);
+   * }
+   * ```
+   *
+   * Backends differ wildly here, so the method is optional and gated by
+   * `capabilities.changeStreams`:
+   *   - mongokit — Mongo change streams (`Model.watch`); requires a
+   *     replica set. `fullDocument: 'updateLookup'` semantics for updates.
+   *   - SQL kits — typically absent (no native feed). Hosts that need
+   *     a feed on SQL pair the repo with `events` emission instead.
+   *
+   * The iterator ends when `options.signal` aborts. Errors from the
+   * underlying stream propagate to the consumer.
+   */
+  watch?(filter?: FilterInput, options?: WatchOptions): AsyncIterable<ChangeEvent<TDoc>>;
+}
+/** A single committed mutation observed by `watch()`. */
+interface ChangeEvent<TDoc = unknown> {
+  /** What happened. `replace` = full-document overwrite (Mongo `replaceOne`). */
+  operation: 'create' | 'update' | 'delete' | 'replace';
+  /** Primary key of the affected document. */
+  id?: unknown;
+  /**
+   * The post-image document — present on create/replace always, on update
+   * when the backend supports post-image lookup, absent on delete.
+   */
+  doc?: TDoc;
+  /** Commit timestamp as reported by the backend. */
+  timestamp: Date;
+}
+/** Options for `StandardRepo.watch()`. */
+interface WatchOptions {
+  /** End the iterator. The only portable way to stop a change feed. */
+  signal?: AbortSignal;
+  /**
+   * Resume token / cursor from a previous stream (kit-specific shape —
+   * Mongo resume tokens are opaque BSON). Hosts persist and replay it
+   * for at-least-once consumption across restarts.
+   */
+  resumeAfter?: unknown;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WatchOptions, WriteOptions };

package/dist/schema/index.d.mts

@@ -1,4 +1,5 @@
+import { StandardSchemaV1, validateStandardSchema } from "./standard-schema.mjs";
 import { CrudSchemas, FieldRule, FieldRules, JsonSchema, SchemaBuilderOptions, ValidationResult } from "./types.mjs";
 import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { SchemaGenerator, SchemaGeneratorContext, isSchemaGenerator } from "./generator.mjs";
-export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type ValidationResult, applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };
+export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type StandardSchemaV1, type ValidationResult, applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateStandardSchema, validateUpdateBody };

package/dist/schema/index.mjs

@@ -1,3 +1,4 @@
+import { validateStandardSchema } from "./standard-schema.mjs";
 import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { isSchemaGenerator } from "./generator.mjs";
-export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateStandardSchema, validateUpdateBody };

package/dist/schema/standard-schema.d.mts

@@ -0,0 +1,89 @@
+//#region src/schema/standard-schema.d.ts
+/**
+ * Standard Schema integration — the validator-agnostic validation slot.
+ *
+ * [Standard Schema](https://standardschema.dev) is the shared interface
+ * implemented by Zod 3.24+, Valibot 1.0+, ArkType 2.0+, Effect Schema and
+ * others. Vendoring the interface (officially encouraged — it's a
+ * types-only spec designed to be copied) keeps repo-core's zero-dependency
+ * guarantee while letting hosts plug ANY conforming validator into a
+ * repository:
+ *
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const repo = createRepository(UserModel, {
+ *   schema: z.object({ name: z.string(), email: z.string().email() }),
+ * });
+ * await repo.create({ name: 1 }); // throws HttpError 400 with validationErrors
+ * ```
+ *
+ * `RepositoryBase` wires `schema` / `updateSchema` into `before:create` /
+ * `before:createMany` / `before:update` hooks at `HOOK_PRIORITY.VALIDATION`
+ * — after policy plugins (so tenant-stamped fields are present) and before
+ * cache/observability.
+ */
+/** The Standard Schema interface. Any conforming validator satisfies it. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: readonly Issue[];
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+/**
+ * Validate `data` against a Standard Schema. Returns the schema's typed
+ * output (validators may coerce/transform) or throws an `HttpError` 400
+ * carrying `validationErrors` + structured `meta.issues` — the same wire
+ * shape every kit's own validation errors serialize to.
+ */
+declare function validateStandardSchema<TSchema extends StandardSchemaV1>(schema: TSchema, data: unknown): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
+export { StandardSchemaV1, validateStandardSchema };

package/dist/schema/standard-schema.mjs

@@ -0,0 +1,59 @@
+import { ERROR_CODES } from "../errors/types.mjs";
+//#region src/schema/standard-schema.ts
+/**
+* Standard Schema integration — the validator-agnostic validation slot.
+*
+* [Standard Schema](https://standardschema.dev) is the shared interface
+* implemented by Zod 3.24+, Valibot 1.0+, ArkType 2.0+, Effect Schema and
+* others. Vendoring the interface (officially encouraged — it's a
+* types-only spec designed to be copied) keeps repo-core's zero-dependency
+* guarantee while letting hosts plug ANY conforming validator into a
+* repository:
+*
+* ```ts
+* import { z } from 'zod';
+*
+* const repo = createRepository(UserModel, {
+*   schema: z.object({ name: z.string(), email: z.string().email() }),
+* });
+* await repo.create({ name: 1 }); // throws HttpError 400 with validationErrors
+* ```
+*
+* `RepositoryBase` wires `schema` / `updateSchema` into `before:create` /
+* `before:createMany` / `before:update` hooks at `HOOK_PRIORITY.VALIDATION`
+* — after policy plugins (so tenant-stamped fields are present) and before
+* cache/observability.
+*/
+/** Dot-path string from a Standard Schema issue path. */
+function issuePath(issue) {
+	if (!issue.path || issue.path.length === 0) return "";
+	return issue.path.map((seg) => String(typeof seg === "object" && seg !== null && "key" in seg ? seg.key : seg)).join(".");
+}
+/**
+* Validate `data` against a Standard Schema. Returns the schema's typed
+* output (validators may coerce/transform) or throws an `HttpError` 400
+* carrying `validationErrors` + structured `meta.issues` — the same wire
+* shape every kit's own validation errors serialize to.
+*/
+async function validateStandardSchema(schema, data) {
+	let result = schema["~standard"].validate(data);
+	if (result instanceof Promise) result = await result;
+	if (result.issues) {
+		const validationErrors = result.issues.map((issue) => ({
+			validator: schema["~standard"].vendor,
+			error: issuePath(issue) ? `${issuePath(issue)}: ${issue.message}` : issue.message
+		}));
+		throw Object.assign(/* @__PURE__ */ new Error("Validation failed"), {
+			status: 400,
+			code: ERROR_CODES.VALIDATION,
+			validationErrors,
+			meta: { issues: result.issues.map((issue) => ({
+				path: issuePath(issue) || void 0,
+				message: issue.message
+			})) }
+		});
+	}
+	return result.value;
+}
+//#endregion
+export { validateStandardSchema };

package/dist/testing/conformance.mjs

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

package/dist/testing/index.d.mts

@@ -1,4 +1,5 @@
-import { AggregateOpsSupport, ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
+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";
 export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, runLockAdapterConformance, runStandardRepoConformance };