@classytic/repo-core 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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

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

@@ -1,2 +1,3 @@
 import { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress } from "./types.mjs";
-export type { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };
+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/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,6 +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 { UsageConformanceHarness, runUsageStoreContract } from "./usage-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 PurgeConformanceContext, type PurgeConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.17.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,