@classytic/arc 2.23.0 → 2.28.0

package/dist/transactionContext-PNdoyLLm.mjs

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context/transactionContext.ts
+/**
+* Transaction Context via AsyncLocalStorage
+*
+* Provides a Unit-of-Work (UoW) hook so any code in the call stack can
+* retrieve the active database session/transaction without it being threaded
+* through every function parameter.
+*
+* Arc is DB-agnostic — the session type is `unknown` so any backend
+* (Mongoose session, Prisma transaction, pg client, Drizzle client) can
+* participate. Kit adapters call `runInTransaction(session, fn)` to install
+* the active context; the outbox's `store()` reads it automatically when no
+* explicit `options.session` is passed.
+*
+* @example
+* ```typescript
+* // In a Mongoose-backed service (mongokit adapter)
+* import { transactionContext } from '@classytic/arc/context';
+*
+* await mongoose.connection.withSession(async (session) => {
+*   await session.withTransaction(async () => {
+*     await transactionContext.run(session, async () => {
+*       await orders.insertOne(order, { session });
+*       // outbox.store() auto-picks up `session` — no manual threading
+*       await outbox.store(orderCreatedEvent);
+*     });
+*   });
+* });
+* ```
+*
+* @example
+* ```typescript
+* // Opt-out: explicit session always wins over the ALS context
+* await outbox.store(event, { session: explicitSession });
+* ```
+*/
+const storage = new AsyncLocalStorage();
+/**
+* Transaction context API.
+*
+* - `run(session, fn)` — install an active DB session for the duration of `fn`
+* - `get()` — read the current session (undefined if outside a transaction scope)
+*/
+const transactionContext = {
+	/**
+	* Run `fn` with `session` as the active DB transaction context.
+	* Any call to `get()` within `fn`'s async call stack returns `session`.
+	*/
+	run(session, fn) {
+		return storage.run(session, fn);
+	},
+	/**
+	* Get the current DB session, or `undefined` if not inside a
+	* `transactionContext.run(...)` scope.
+	*/
+	get() {
+		return storage.getStore();
+	},
+	/** The underlying AsyncLocalStorage instance. Exposed for advanced integrations. */
+	storage
+};
+//#endregion
+export { transactionContext as t };

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OpenApiSchemas, $t as UserLike, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, In as BaseControllerOptions, It as FastifyHandler, J as PresetHook, Jt as AnyRecord, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Qt as ObjectId, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Xt as ArcRequest, Y as PresetResult, Yt as ApiResponse, Z as CrudSchemas, Zt as JWTPayload, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, en as UserOrganization, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-BBsvQt7U.mjs";
-import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Y as PresetResult, Z as CrudSchemas, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as BaseControllerOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-DPRH0Cme.mjs";
+import { i as RequestScope } from "../types-DjC-KUCz.mjs";
+import { c as AnyRecord, d as ObjectId, f as UserLike, i as UserBase, l as ArcRequest, n as PermissionContext, p as UserOrganization, r as PermissionResult, t as PermissionCheck, u as JWTPayload } from "../types-Dmw-6Qeo.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
-export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };
+export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/{types-bHblZ9YN.mjs → types-CSyCxl2V.mjs}

@@ -1,4 +1,6 @@
 import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-DkO8Nk6-.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BvlQSDMB.mjs";
+import { t as getUserId$1 } from "./userHelpers-Cg_y3fBz.mjs";
 //#region src/scope/types.ts
 /**
 * Request Scope — The One Standard
@@ -87,8 +89,7 @@ function getTenantFromRequest(req, options = {}) {
 		};
 	}
 	const headerName = (options.header ?? "x-organization-id").toLowerCase();
-	const raw = req.headers[headerName];
-	const headerValue = Array.isArray(raw) ? raw[0] : raw;
+	const headerValue = requireSingleHeaderValue(req.headers, headerName);
 	if (typeof headerValue === "string" && headerValue.length > 0) return {
 		organizationId: headerValue,
 		source: "header"
@@ -259,8 +260,13 @@ function isOrgInScope(scope, targetOrgId) {
 * ```
 */
 function getUserId(scope) {
-	if (scope.kind === "public") return void 0;
-	return scope.userId;
+	switch (scope.kind) {
+		case "authenticated":
+		case "member":
+		case "elevated": return scope.userId;
+		case "public":
+		case "service": return;
+	}
 }
 /**
 * Throwing variant of `getOrgId`. Returns the organization id when the
@@ -356,9 +362,12 @@ function getUserRoles(scope) {
 */
 function getOrgContext(request) {
 	const scope = request.scope ?? { kind: "public" };
+	const requestedOrgId = requireSingleHeaderValue(request.headers, "x-organization-id");
+	const rawOrganizationId = request.user?.organizationId;
+	const userOrganizationId = rawOrganizationId === void 0 || rawOrganizationId === null ? void 0 : String(rawOrganizationId) || void 0;
 	return {
-		userId: getUserId(scope) ?? request.user?.id ?? request.user?._id,
-		organizationId: getOrgId(scope) ?? request.user?.organizationId ?? request.headers?.["x-organization-id"],
+		userId: getUserId(scope) ?? getUserId$1(request.user),
+		organizationId: getOrgId(scope) ?? userOrganizationId ?? requestedOrgId,
 		roles: getUserRoles(scope),
 		orgRoles: getOrgRoles(scope)
 	};
@@ -389,9 +398,31 @@ function getOrgContext(request) {
 function getRequestScope(request) {
 	return request.scope ?? PUBLIC_SCOPE;
 }
+function scopeFirstCtx(req, options = {}) {
+	let actorId;
+	let organizationId;
+	const s = req.scope;
+	if (s && "kind" in s) {
+		actorId = getUserId(s) ?? getClientId(s);
+		organizationId = getOrgId(s);
+	} else if (s) {
+		actorId = s.userId;
+		organizationId = s.organizationId;
+	}
+	actorId = actorId ?? options.fallbackActorId;
+	if (!organizationId && options.orgHeader !== false && req.headers) {
+		const headerName = (options.orgHeader ?? "x-organization-id").toLowerCase();
+		const headerValue = requireSingleHeaderValue(req.headers, headerName);
+		if (typeof headerValue === "string" && headerValue.length > 0) organizationId = headerValue;
+	}
+	return {
+		...actorId !== void 0 ? { actorId } : {},
+		...organizationId !== void 0 ? { organizationId } : {}
+	};
+}
 /** Default public scope — used as initial decoration value */
 const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
 /** Default authenticated scope — used when user is logged in but no org */
 const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
 //#endregion
-export { isService as C, requireUserId as D, requireTeamId as E, isOrgInScope as S, requireOrgId as T, getUserRoles as _, getDPoPJkt as a, isElevated as b, getOrgId as c, getScopeContext as d, getScopeContextMap as f, getUserId as g, getTenantFromRequest as h, getClientId as i, getOrgRoles as l, getTeamId as m, PUBLIC_SCOPE as n, getMandate as o, getServiceScopes as p, getAncestorOrgIds as r, getOrgContext as s, AUTHENTICATED_SCOPE as t, getRequestScope as u, hasOrgAccess as v, requireClientId as w, isMember as x, isAuthenticated as y };
+export { isService as C, requireUserId as D, requireTeamId as E, scopeFirstCtx as O, isOrgInScope as S, requireOrgId as T, getUserRoles as _, getDPoPJkt as a, isElevated as b, getOrgId as c, getScopeContext as d, getScopeContextMap as f, getUserId as g, getTenantFromRequest as h, getClientId as i, getOrgRoles as l, getTeamId as m, PUBLIC_SCOPE as n, getMandate as o, getServiceScopes as p, getAncestorOrgIds as r, getOrgContext as s, AUTHENTICATED_SCOPE as t, getRequestScope as u, hasOrgAccess as v, requireClientId as w, isMember as x, isAuthenticated as y };

package/dist/types-C_ZZRcD6.d.mts

@@ -0,0 +1,450 @@
+import { PurgeActor, PurgeEvidence, PurgeResourceResult, PurgeStrategyKind as PurgeStrategyKind$1, PurgeVerificationSummary } from "@classytic/primitives/retention";
+//#region src/cleanup/types.d.ts
+/** Ambient context every recipe method receives. Host-injected — never global. */
+interface CleanupContext {
+  /** Who requested the operation. */
+  readonly actor: PurgeActor;
+  /** Injected clock — recipes never call `new Date()` directly (testability). */
+  readonly now: Date;
+  /** Cooperative cancellation — checked between chunks/steps. */
+  readonly signal?: AbortSignal | undefined;
+  /** Optional structured logger. */
+  readonly logger?: CleanupLogger | undefined;
+  /**
+   * Opaque host-provided ambient values (e.g. the resolved company/branch
+   * scope). MUST be JSON-serializable — it is persisted on the run so a worker
+   * (different process) can rebuild the exact operation context. Recipes read
+   * what they declared they need; the framework never inspects it.
+   */
+  readonly ambient?: Readonly<Record<string, unknown>> | undefined;
+}
+interface CleanupLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Execution-time context — adds progress reporting + the run/operation ids +
+ * cooperative cancellation.
+ */
+interface CleanupExecutionContext extends CleanupContext {
+  /** Durable run id this execution belongs to. */
+  readonly runId: string;
+  /** Stable operation id threaded through logs, audit, and evidence. */
+  readonly operationId: string;
+  /**
+   * Report one committed chunk. Updates the run's BOUNDED progress summary
+   * (counts / current resource / cursor / heartbeat) — it does NOT retain
+   * every step in memory. Also refreshes the cancellation view: after a chunk
+   * commits, call this so the executor learns of a cancel request promptly.
+   */
+  onStep(step: CleanupStepResult): Promise<void>;
+  /**
+   * Throw `CleanupCancelled` if a cancel has been requested for this run. Cheap
+   * to call between chunks; backed by the durable `cancelRequested` flag (the
+   * source of truth) plus the in-process `signal`.
+   */
+  throwIfCancelled(): Promise<void>;
+}
+/** Whether a recipe may run right now, and why not. */
+interface Availability {
+  readonly available: boolean;
+  /** Required when `available` is false — surfaced to the operator. */
+  readonly reason?: string | undefined;
+}
+/** Operator-supplied recipe parameters (branch, module set, before-date, …). */
+interface CleanupInput {
+  readonly parameters?: Readonly<Record<string, unknown>> | undefined;
+}
+/** One logical line in the preview — a business record class, never a collection. */
+interface CleanupPlanItem {
+  /** Logical module / resource label, e.g. `'orders'`, `'journal entries'`. */
+  readonly resource: string;
+  /** Estimated records affected. */
+  readonly estimated: number;
+  /** What is retained for this line (e.g. `'measures kept, PII redacted'`). */
+  readonly retained?: string | undefined;
+  /** Domain blockers preventing this line (e.g. `'OPEN_TRANSFER'`). */
+  readonly blockers?: readonly string[] | undefined;
+}
+/**
+ * A recipe's plan BEFORE the framework seals it — the recipe returns this; the
+ * service computes {@link CleanupPlan.digest} + stamps {@link CleanupPlan.recipeId}.
+ */
+interface CleanupPlanDraft {
+  readonly items: readonly CleanupPlanItem[];
+  /** Top-level categories the recipe explicitly RETAINS. */
+  readonly retains?: readonly string[] | undefined;
+  /**
+   * Top-level blockers. A NON-EMPTY blockers list is a HARD STOP — the service
+   * refuses `execute` with `CLEANUP_BLOCKED`. Preview surfaces them so the
+   * operator resolves them (or the recipe stops listing them) before running.
+   */
+  readonly blockers?: readonly string[] | undefined;
+  /** Projection/scaffolding rebuilds the recipe will perform after cleanup. */
+  readonly rebuildActions?: readonly string[] | undefined;
+  /** Non-blocking warnings for the operator. */
+  readonly warnings?: readonly string[] | undefined;
+  /**
+   * The exact phrase the operator must type to confirm a destructive run.
+   * Defaults (in the service) to the recipe id when omitted.
+   */
+  readonly confirmationPhrase?: string | undefined;
+}
+/** A sealed, digest-stamped plan. The digest makes confirmation tamper-evident. */
+interface CleanupPlan {
+  readonly recipeId: string;
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly items: readonly CleanupPlanItem[];
+  readonly retains: readonly string[];
+  readonly blockers: readonly string[];
+  readonly rebuildActions: readonly string[];
+  readonly warnings: readonly string[];
+  readonly estimatedTotal: number;
+  readonly confirmationPhrase: string;
+  /** Deterministic checksum of the plan's material content — see `computePlanDigest`. */
+  readonly digest: string;
+}
+/** One committed step's outcome — reported via `onStep`, folded into the summary. */
+interface CleanupStepResult {
+  readonly resource: string;
+  readonly processed: number;
+  readonly ok: boolean;
+  readonly error?: string | undefined;
+  /** Opaque resume cursor the recipe may surface for observability. */
+  readonly cursor?: string | undefined;
+  readonly startedAt?: Date | undefined;
+  readonly completedAt?: Date | undefined;
+}
+/**
+ * BOUNDED progress summary persisted on the run (design "Node.js memory"): a
+ * fixed-size aggregate, never an unbounded per-chunk array. Detailed steps, if a
+ * host wants them, go to a separate capped sink — not this document.
+ */
+interface CleanupProgressSummary {
+  /** Running total of processed records across all steps. */
+  readonly processed: number;
+  /** Count of steps reported so far. */
+  readonly steps: number;
+  /** Resource the last step touched. */
+  readonly currentResource?: string | undefined;
+  /** Last resume cursor reported. */
+  readonly lastCursor?: string | undefined;
+  /** When the last step landed — liveness/heartbeat. */
+  readonly heartbeatAt?: Date | undefined;
+  /** Count of failed steps (a run with any is never a clean success). */
+  readonly failed?: number | undefined;
+}
+/** One verification invariant's outcome. */
+interface VerificationCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail?: string | undefined;
+}
+/** The recipe's own post-checks — a delete count alone is never success (§9). */
+interface VerificationResult {
+  readonly ok: boolean;
+  readonly checks: readonly VerificationCheck[];
+}
+type CleanupOutcomeStatus = "completed" | "partial" | "failed" | "cancelled";
+/** What `execute` returns — the per-step results + a terminal status. */
+interface CleanupResult {
+  readonly status: Exclude<CleanupOutcomeStatus, "cancelled">;
+  readonly results: readonly CleanupStepResult[];
+}
+/**
+ * The finalization payload persisted ON the run BEFORE it enters `finalizing`
+ * (same CAS patch). This is what makes a `finalizing` crash recoverable
+ * WITHOUT re-executing the recipe: a recovering worker replays ONLY
+ * `evidenceStore.finalize()` + the terminal CAS from this durable snapshot —
+ * never `recipe.execute()` again.
+ */
+interface CleanupFinalizationPayload {
+  readonly status: CleanupOutcomeStatus;
+  readonly results: readonly CleanupStepResult[];
+  readonly verification: VerificationResult;
+  /** Count of verification checks dropped by `maxChecks` truncation. */
+  readonly checksTruncated?: number | undefined;
+  readonly failureReason?: string | undefined;
+}
+/**
+ * A cleanup recipe — the unit operators choose. Pure provider: the four
+ * methods are the only surface arc calls. A recipe delegates the actual
+ * domain work to kernel-provided steps; it never runs a raw Mongo cascade.
+ */
+interface CleanupRecipe {
+  /** Stable machine id, e.g. `'cleanup.pre-live-reset'`. Unique in a registry. */
+  readonly id: string;
+  /** Plain-language name for the UI. */
+  readonly label: string;
+  /** Whether this recipe removes data (gates confirmation + single-run fence). */
+  readonly destructive: boolean;
+  /**
+   * Recipe/plan-schema version. Persisted on the run; a retry that finds a
+   * different current version requires a fresh preview rather than replaying an
+   * incompatible sealed plan. Defaults to `'1'`.
+   */
+  readonly version?: string;
+  /**
+   * The purge strategy this recipe's evidence records (`'hard'` deletion,
+   * `'soft'` deactivation, `'anonymize'` redaction). Defaults to `'hard'`.
+   * A pure projection-rebuild recipe should declare `'soft'` (nothing about the
+   * SOURCE data is removed) or, better, the closest honest label — evidence
+   * must never overstate destructiveness.
+   */
+  readonly evidenceStrategy?: PurgeStrategyKind$1;
+  /** Whether this recipe may run right now (e.g. pre-go-live only). */
+  available(ctx: CleanupContext): Promise<Availability>;
+  /** Compute a preview WITHOUT mutating anything. Idempotent + side-effect-free. */
+  plan(input: CleanupInput, ctx: CleanupContext): Promise<CleanupPlanDraft>;
+  /** Execute the sealed plan. Must be chunked, idempotent, and cancellation-aware. */
+  execute(plan: CleanupPlan, ctx: CleanupExecutionContext): Promise<CleanupResult>;
+  /** Verify the post-state — the recipe owns what "clean" means. */
+  verify(plan: CleanupPlan, ctx: CleanupContext): Promise<VerificationResult>;
+}
+type CleanupRunStatus = "planned" | "queued" | "running" | "finalizing" | "completed" | "failed" | "cancelled";
+/** Terminal states — no further transition is valid. */
+declare const CLEANUP_TERMINAL_STATUSES: readonly CleanupRunStatus[];
+interface CleanupRun {
+  readonly id: string;
+  readonly recipeId: string;
+  readonly recipeVersion: string;
+  readonly status: CleanupRunStatus;
+  readonly planDigest: string;
+  /** The immutable sealed plan — replayed verbatim by the worker / a retry. */
+  readonly sealedPlan: CleanupPlan;
+  /** The operator-supplied parameters (also inside sealedPlan; kept explicit). */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  /** The authorizing actor — persisted so a worker attributes the op correctly. */
+  readonly actor: PurgeActor;
+  /** Serializable ambient scope captured at request time (branch/company). */
+  readonly ambient?: Readonly<Record<string, unknown>> | undefined;
+  readonly requestedBy: string;
+  readonly reason: string;
+  readonly operationId: string;
+  /**
+   * Whether the recipe was destructive at request time — persisted so a
+   * GENERIC store can enforce the single-destructive-run policy without
+   * consulting the registry (and so non-destructive rebuilds need not
+   * serialize behind it).
+   */
+  readonly destructive: boolean;
+  /**
+   * Admission-control key the store serializes on (e.g. `'global-destructive'`).
+   * Absent for runs that need no mutual exclusion. Hosts may shard it later
+   * (`'branch:<id>'`) without an arc change.
+   */
+  readonly concurrencyKey?: string | undefined;
+  /** How many times a worker has claimed this run (1 = first execution). */
+  readonly attempt: number;
+  /**
+   * Exclusive worker lease. A run in `running`/`finalizing` with an UNEXPIRED
+   * lease is owned — `claim` refuses it. Progress + status writes carry the
+   * token so a stalled ex-owner that wakes past expiry cannot clobber the new
+   * owner's writes.
+   */
+  readonly leaseToken?: string | undefined;
+  readonly leaseExpiresAt?: Date | undefined;
+  readonly progress: CleanupProgressSummary;
+  /** Durable cancellation request — the source of truth the executor polls. */
+  readonly cancelRequested: boolean;
+  /** Who requested the cancel + why + when (audit — §8, cancel evidence). */
+  readonly cancelRequestedBy?: PurgeActor | undefined;
+  readonly cancelReason?: string | undefined;
+  readonly cancelRequestedAt?: Date | undefined;
+  /** Durable finalization snapshot — see {@link CleanupFinalizationPayload}. */
+  readonly finalization?: CleanupFinalizationPayload | undefined;
+  readonly queuedAt?: Date | undefined;
+  readonly startedAt?: Date | undefined;
+  readonly completedAt?: Date | undefined;
+  readonly failureReason?: string | undefined;
+}
+/** Immutable proof of a completed run (§5) — deterministically checksummed. */
+interface CleanupManifest {
+  readonly runId: string;
+  readonly recipeId: string;
+  readonly recipeVersion: string;
+  readonly operationId: string;
+  readonly planDigest: string;
+  readonly status: CleanupOutcomeStatus;
+  readonly actor: PurgeActor;
+  readonly reason: string;
+  readonly results: readonly CleanupStepResult[];
+  readonly verification: VerificationResult;
+  /**
+   * Count of verification checks DROPPED by the `maxChecks` cap. Present and
+   * non-zero whenever `verification.checks` is not the complete set — evidence
+   * must say so rather than silently show only the retained checks.
+   */
+  readonly checksTruncated?: number | undefined;
+  readonly completedAt: Date;
+  /**
+   * Integrity CHECKSUM of the manifest content (not tamper-PROOF: plain SHA-256
+   * does not stop an attacker with write access from replacing the record and
+   * recomputing the digest — pair with access control / keyed signatures for
+   * that). Detects accidental corruption + drift.
+   */
+  readonly manifestDigest: string;
+}
+type CleanupRunCreateResult = {
+  readonly created: true;
+} | {
+  readonly created: false;
+  readonly activeRunId: string;
+};
+/** Fields a status transition may also patch. */
+interface CleanupRunTransitionPatch {
+  readonly queuedAt?: Date;
+  readonly startedAt?: Date;
+  readonly completedAt?: Date;
+  readonly failureReason?: string;
+  readonly progress?: CleanupProgressSummary;
+  /** Reset the cancellation flag — used when a terminal run is re-armed on retry. */
+  readonly cancelRequested?: boolean;
+  /** Persist the durable finalization snapshot (set entering `finalizing`). */
+  readonly finalization?: CleanupFinalizationPayload;
+}
+/** An exclusive worker lease on a run. */
+interface CleanupLease {
+  /** Opaque token identifying THIS worker's ownership of the run. */
+  readonly token: string;
+  /** When the lease lapses and the run becomes claimable again. */
+  readonly expiresAt: Date;
+}
+/** Metadata persisted with a durable cancel request (audit). */
+interface CleanupCancelRequest {
+  readonly actor?: PurgeActor | undefined;
+  readonly reason?: string | undefined;
+  readonly requestedAt: Date;
+}
+/**
+ * Durable store for cleanup runs. The host owns persistence (Mongo/SQL/…) AND
+ * the atomicity of these operations — the framework's safety rests on them:
+ *
+ *   - `createIfPermitted` MUST be atomic: for a run with a `concurrencyKey` it
+ *     inserts ONLY if no other run with the same key is in a non-terminal
+ *     state, backed by a unique partial index / conditional insert / lock. A
+ *     check-then-create is NOT sufficient. Runs WITHOUT a key are always
+ *     admitted.
+ *   - `claim` MUST be atomic and EXCLUSIVE: grant the lease ONLY if the run is
+ *     `queued`, OR is `running`/`finalizing` with an ABSENT or EXPIRED lease
+ *     (`leaseExpiresAt <= now`). On grant it sets `leaseToken`/`leaseExpiresAt`,
+ *     increments `attempt`, and returns the run (status UNCHANGED — the service
+ *     branches on it: `finalizing` recovers finalization only, never
+ *     re-executes). A run whose lease is live is OWNED — return `null`.
+ *   - `compareAndTransition` MUST be a compare-and-set: apply the transition
+ *     ONLY if the current status is one of `expected` AND, when `leaseToken`
+ *     is given, the run's current lease token matches. This is the ONLY way
+ *     status changes — it makes cancel-vs-complete AND stale-ex-owner races
+ *     safe.
+ *   - `reArmIfPermitted` MUST apply the same admission policy as
+ *     `createIfPermitted` atomically with the terminal→`queued` transition
+ *     (a retry must not slip past the single-destructive-run guard).
+ */
+interface CleanupRunStore {
+  /** Atomic conditional insert (admission control by `concurrencyKey`, §8). */
+  createIfPermitted(run: CleanupRun): Promise<CleanupRunCreateResult>;
+  get(id: string): Promise<CleanupRun | null>;
+  /**
+   * Atomically acquire the exclusive worker lease (see contract above).
+   * Returns the claimed run with the lease applied, or `null` if the run is
+   * owned, terminal, or missing.
+   */
+  claim(id: string, lease: CleanupLease): Promise<CleanupRun | null>;
+  /**
+   * CAS the status: set `status=to` (+ `patch`) ONLY if current status ∈
+   * `expected` and (when given) `leaseToken` matches the run's current lease.
+   * Returns the updated run, or `null` if the CAS lost the race.
+   */
+  compareAndTransition(id: string, expected: readonly CleanupRunStatus[], to: CleanupRunStatus, patch?: CleanupRunTransitionPatch, leaseToken?: string): Promise<CleanupRun | null>;
+  /**
+   * Atomically re-arm a terminal (`failed`/`cancelled`) run back to `queued`
+   * under the SAME admission policy as `createIfPermitted` (its
+   * `concurrencyKey` must not collide with another non-terminal run). Clears
+   * the cancel flag/metadata + lease. Returns `{created:false}`-style refusal
+   * via `null` + the blocking run id in the second tuple slot is NOT modeled —
+   * a `null` simply means "not permitted or not in a terminal state."
+   */
+  reArmIfPermitted(id: string, patch: CleanupRunTransitionPatch): Promise<CleanupRun | null>;
+  /**
+   * Set `cancelRequested = true` (+ audit metadata, idempotent — first request
+   * wins). Does NOT change `status`.
+   */
+  requestCancel(id: string, request?: CleanupCancelRequest): Promise<CleanupRun | null>;
+  /**
+   * Overwrite the small bounded progress summary (frequent, non-status).
+   * When `lease` is given, ALSO extend `leaseExpiresAt` (heartbeat renewal) —
+   * and apply ONLY if the run's current lease token matches `lease.token`.
+   */
+  saveProgress(id: string, progress: CleanupProgressSummary, lease?: CleanupLease): Promise<void>;
+}
+/**
+ * Durable store for the evidence + manifest a run leaves behind. `finalize`
+ * MUST be idempotent by `evidence.operationId` — a retry / restart that
+ * re-finalizes the same operation is a no-op (or an upsert), never a duplicate.
+ * Ideally the host writes both in one transaction (with the terminal run
+ * transition); the framework tolerates a `finalizing` intermediate + re-run.
+ */
+interface CleanupEvidenceStore {
+  finalize(input: {
+    evidence: PurgeEvidence;
+    manifest: CleanupManifest;
+  }): Promise<void>;
+}
+/** A serializable job — everything the worker needs is the run id. */
+interface CleanupJob {
+  readonly runId: string;
+}
+/**
+ * Durable job queue (§8). `execute()` enqueues a `{ runId }`; a worker later
+ * dequeues and calls `service.processRun(runId)` — a DIFFERENT process can do
+ * this because the run carries the whole sealed operation. The default in-proc
+ * queue defers to a microtask (still off the request path within one process);
+ * production injects BullMQ / SQS / a repo-backed queue for cross-process
+ * durability, claim/lease, and restart recovery.
+ */
+interface CleanupJobQueue {
+  enqueue(job: CleanupJob): Promise<void>;
+}
+/**
+ * A company/target write fence (§8) — blocks new writes for the duration of a
+ * destructive run. Acquire/release keyed by the operation id so a crashed run's
+ * fence is recoverable by op id.
+ *
+ * `acquire` MAY return a fencing token; when it does, the service passes the
+ * SAME token back to `release`, and the fence MUST refuse a release carrying a
+ * stale token. This closes the distributed race where a stalled ex-owner wakes
+ * after lease expiry and releases the fence out from under the new owner.
+ * Implementations without cross-process workers may return `undefined` and
+ * ignore the token.
+ */
+interface CleanupWriteFence {
+  acquire(operationId: string): Promise<string | undefined | void>;
+  release(operationId: string, token?: string): Promise<void>;
+}
+interface CleanupPermissions {
+  /** May preview/observe runs. */
+  view: CleanupPermissionCheck;
+  /** May execute a run. Superadmin in the reference host. */
+  execute: CleanupPermissionCheck;
+  /** May cancel/retry a run. Defaults to `execute` when omitted. */
+  manage?: CleanupPermissionCheck;
+}
+/** Host permission predicate — receives whatever the host passes as the request scope. */
+type CleanupPermissionCheck = (scope: unknown) => boolean | Promise<boolean>;
+/** Framework size caps that keep runs + documents bounded (design "memory"). */
+interface CleanupLimits {
+  /** Max plan items. Default 500. */
+  readonly maxPlanItems: number;
+  /** Max per-run result rows folded into the manifest. Default 1000. */
+  readonly maxResults: number;
+  /** Max verification checks. Default 200. */
+  readonly maxChecks: number;
+  /** Max reason string length. Default 2000. */
+  readonly maxReasonLength: number;
+  /** Max nesting depth of the parameters object. Default 8. */
+  readonly maxParamDepth: number;
+}
+declare const DEFAULT_CLEANUP_LIMITS: CleanupLimits;
+//#endregion
+export { CleanupWriteFence as A, CleanupResult as C, CleanupRunStore as D, CleanupRunStatus as E, PurgeStrategyKind$1 as F, PurgeVerificationSummary as I, VerificationCheck as L, PurgeActor as M, PurgeEvidence as N, CleanupRunTransitionPatch as O, PurgeResourceResult as P, VerificationResult as R, CleanupRecipe as S, CleanupRunCreateResult as T, CleanupPermissions as _, CleanupEvidenceStore as a, CleanupPlanItem as b, CleanupInput as c, CleanupLease as d, CleanupLimits as f, CleanupPermissionCheck as g, CleanupOutcomeStatus as h, CleanupContext as i, DEFAULT_CLEANUP_LIMITS as j, CleanupStepResult as k, CleanupJob as l, CleanupManifest as m, CLEANUP_TERMINAL_STATUSES as n, CleanupExecutionContext as o, CleanupLogger as p, CleanupCancelRequest as r, CleanupFinalizationPayload as s, Availability as t, CleanupJobQueue as u, CleanupPlan as v, CleanupRun as w, CleanupProgressSummary as x, CleanupPlanDraft as y };