@classytic/arc 2.25.0 → 2.28.0

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 };

package/dist/{index-KUoxjIq1.d.mts → types-Cu6vVJmh.d.mts}

@@ -587,108 +587,4 @@ type ArcModuleInput<TExports = unknown> = ArcModule<TExports> | Promise<ArcModul
  */
 interface ArcModuleRegistry {}
 //#endregion
-//#region src/factory/module/contributions.d.ts
-/**
- * Collect every module's `healthChecks` in the caller's order. Fails at boot
- * on a duplicate check `name` across modules, naming BOTH owning modules.
- * The host's app-level checks are appended AFTER this (modules-first,
- * host-last) by the caller.
- */
-declare function collectModuleHealthChecks(modules: readonly ArcModule[]): HealthCheck[];
-/**
- * Collect every module's `workflows`. Resolves factory contributions (so a
- * factory can close over a container the caller has already decorated on
- * `fastify`) and flattens to a single opaque array. Arc core deliberately
- * does NOT validate or interpret the values — the streamline integration
- * owns name/shape checks and registration. Called by the integration at init
- * time, not by arc's boot pipeline (workflows depend on the integration's
- * container).
- */
-declare function collectModuleWorkflows(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<unknown[]>;
-/**
- * Collect every module's `scheduledJobs`. Resolves factory contributions
- * (after bootstraps) and fails at boot on a duplicate job `name` across
- * modules. The caller passes the returned definitions to the canonical
- * schedules plugin; factories must therefore be resolved only once.
- */
-declare function collectModuleScheduledJobs(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<ScheduleDefinition[]>;
-//#endregion
-//#region src/factory/module/lifecycle.d.ts
-/**
- * Subscribe every module's `eventHandlers` in dependency order (pass the
- * `orderModules`-sorted list). Returns the ordered list of unsubscribe
- * functions so the caller can tear them down at shutdown BEFORE module
- * `onClose` (while module deps are still alive). Fails at boot on:
- *   - a duplicate NAMED handler across modules (attributing both owners);
- *   - a module declaring handlers while the event subsystem is unavailable.
- * Resolves factory contributions (after bootstraps) so a handler can close over
- * booted engines rather than a global getter.
- */
-declare function subscribeModuleEventHandlers(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<Array<() => void | Promise<void>>>;
-//#endregion
-//#region src/factory/module/order.d.ts
-/**
- * Order modules for composition by their `dependsOn` edges — a STABLE
- * topological sort. Called once at the start of the bootstrap phase; every
- * subsequent phase (bootstrap, resources, afterResources, and reverse-order
- * onClose) iterates the returned list, so a module's declared dependencies are
- * always composed before it.
- *
- * "Stable" = modules with no edge between them keep their original list order,
- * so declaring `dependsOn` on one module never silently reorders an unrelated
- * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
- * returned unchanged.
- *
- * Fail-fast — throws (never reorders past a broken contract) on:
- *   - duplicate module names (the name is the graph key)
- *   - a `dependsOn` name not present in the composed set
- *   - a self-reference (`dependsOn` includes the module's own name)
- *   - a dependency cycle (reports the concrete `a → b → … → a` path)
- */
-declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
-//#endregion
-//#region src/factory/module/resolve.d.ts
-/**
- * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
- * (this is where a dynamic `import()` fires); a promise (or plain module) is
- * awaited. Called once per module at the start of the bootstrap phase.
- */
-declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
-/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
-declare function resolveContribution<T>(contribution: ModuleContribution<T> | undefined, fastify: FastifyInstance): Promise<readonly T[]>;
-//#endregion
-//#region src/factory/module/index.d.ts
-/**
- * Identity helper for authoring a typed module — mirrors `defineResource`.
- * Gives inference + a single obvious construction site; does no work.
- *
- * `TExports` is inferred from the `bootstrap` return value, so a module
- * author gets a typed public export for free:
- *
- * ```ts
- * export const accountingModule = (deps: Deps) =>
- *   defineModule({
- *     name: "accounting",
- *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
- *   });
- * ```
- */
-declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
-/**
- * Typed accessor for a module's public export (its `bootstrap` return value),
- * recorded at `fastify.arc.modules[name]`.
- *
- * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
- * accessors): a missing entry means the module either isn't composed, is
- * composed AFTER the caller (list order = init order), or returned nothing —
- * all wiring bugs that must surface at boot, not as `undefined` downstream.
- *
- * The type parameter is an assertion, not a proof. Two ways to type it:
- *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
- *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
- *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
- */
-declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
-declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
-//#endregion
-export { schedulesPlugin as C, healthPlugin as D, _default$1 as E, _default as S, HealthOptions as T, ResourceModule as _, orderModules as a, ScheduleStats as b, collectModuleScheduledJobs as c, ArcModuleInput as d, ArcModuleRegistry as f, ResourceLike as g, LoadResourcesOptions as h, resolveModule as i, collectModuleWorkflows as l, ModuleContribution as m, getModuleExports as n, subscribeModuleEventHandlers as o, EventHandlerDefinition as p, resolveContribution as r, collectModuleHealthChecks as s, defineModule as t, ArcModule as u, loadResources as v, HealthCheck as w, SchedulesPluginOptions as x, ScheduleDefinition as y };
+export { _default$1 as _, ModuleContribution as a, ResourceModule as c, ScheduleStats as d, SchedulesPluginOptions as f, HealthOptions as g, HealthCheck as h, EventHandlerDefinition as i, loadResources as l, schedulesPlugin as m, ArcModuleInput as n, LoadResourcesOptions as o, _default as p, ArcModuleRegistry as r, ResourceLike as s, ArcModule as t, ScheduleDefinition as u, healthPlugin as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.25.0",
+  "version": "2.28.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -128,6 +128,10 @@
       "types": "./dist/testing/storageContract.d.mts",
       "default": "./dist/testing/storageContract.mjs"
     },
+    "./testing/cleanup": {
+      "types": "./dist/testing/cleanupStoreContract.d.mts",
+      "default": "./dist/testing/cleanupStoreContract.mjs"
+    },
     "./factory": {
       "types": "./dist/factory/index.d.mts",
       "default": "./dist/factory/index.mjs"
@@ -211,6 +215,14 @@
     "./usage": {
       "types": "./dist/usage/index.d.mts",
       "default": "./dist/usage/index.mjs"
+    },
+    "./cleanup": {
+      "types": "./dist/cleanup/index.d.mts",
+      "default": "./dist/cleanup/index.mjs"
+    },
+    "./testing/outbox": {
+      "types": "./dist/testing/outboxStoreContract.d.mts",
+      "default": "./dist/testing/outboxStoreContract.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -227,6 +239,7 @@
       ".": "stable",
       "./permissions": "stable",
       "./cache": "stable",
+      "./cleanup": "stable",
       "./types": "stable",
       "./types/storage": "stable",
       "./core": "stable",
@@ -255,6 +268,7 @@
       "./events/redis-stream": "stable",
       "./testing": "stable",
       "./testing/storage": "stable",
+      "./testing/cleanup": "stable",
       "./factory": "stable",
       "./schemas": "stable",
       "./migrations": "stable",
@@ -275,7 +289,8 @@
       "./scim": "stable",
       "./auth/audit": "stable",
       "./sync": "experimental",
-      "./usage": "experimental"
+      "./usage": "experimental",
+      "./testing/outbox": "stable"
     }
   },
   "files": [
@@ -327,8 +342,8 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.14.0",
-    "@classytic/repo-core": ">=0.14.0",
+    "@classytic/primitives": ">=0.15.0",
+    "@classytic/repo-core": ">=0.17.0",
     "@classytic/streamline": ">=2.8.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -446,13 +461,13 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@better-auth/drizzle-adapter": "^1.6.19",
     "@better-auth/mongo-adapter": "^1.6.19",
-    "@biomejs/biome": "^2.5.0",
+    "@biomejs/biome": "^2.5.5",
     "@classytic/dev-tools": "^0.2.0",
     "@classytic/gitkit": ">=0.1.0",
-    "@classytic/mongokit": "^3.25.0",
+    "@classytic/mongokit": "^3.28.0",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.14.0",
-    "@classytic/repo-core": "^0.14.0",
+    "@classytic/primitives": "^0.15.0",
+    "@classytic/repo-core": "^0.17.0",
     "@classytic/sqlitekit": "^0.6.0",
     "@classytic/streamline": "^2.8.2",
     "@electric-sql/pglite": "^0.5.4",
@@ -471,9 +486,9 @@
     "@types/qs": "^6.15.1",
     "@vitest/coverage-v8": "^4.1.9",
     "ajv": "^8.20.0",
-    "better-auth": "^1.6.19",
+    "better-auth": "^1.6.25",
     "better-sqlite3": "^12.11.1",
-    "bullmq": "^5.79.0",
+    "bullmq": "^5.81.2",
     "dotenv": "^17.4.2",
     "drizzle-orm": "^0.45.2",
     "fast-check": "^4.8.0",
@@ -488,10 +503,10 @@
     "mongodb-memory-server": "^11.2.0",
     "mongoose": "^9.7.1",
     "publint": "^0.3.21",
-    "tsdown": "^0.22.5",
+    "tsdown": "^0.22.14",
     "typebox": "^1.3.6",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "ws": "^8.21.0",
     "zod": "^4.4.3"
   },