@classytic/arc 2.25.0 → 2.28.0

package/README.md

@@ -1,5 +1,7 @@
 # @classytic/arc
 
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
 Database-agnostic resource framework for Fastify. One `defineResource()` call -> REST + auth + permissions + events + caching + OpenAPI + MCP tools.
 
 Fastify 5+ | Node.js 22+ | ESM only

package/dist/{BaseController--M8EMzt0.mjs → BaseController-B65zbz9m.mjs}

@@ -1,10 +1,10 @@
 import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
+import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
 import { n as getUserRoles, t as getUserId } from "./userHelpers-Cg_y3fBz.mjs";
 import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-CSyCxl2V.mjs";
 import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-Cg05HPsn.mjs";
-import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-Tw4iXtlf.mjs";
+import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-BnyVE9eD.mjs";
 import { g as ArcQueryParser, n as scheduleBackground } from "./utils-taUVD4p3.mjs";
 import { t as buildQueryKey } from "./keys-Cd316u_y.mjs";
 //#region src/core/AccessControl.ts
@@ -453,6 +453,7 @@ async function executeHookedOp(ctx, args, executor) {
 		const beforeReturn = await hooks.executeBefore(resourceName, args.op, args.input, hookOpts);
 		if (pipeProcessed) processedData = beforeReturn;
 	} catch (err) {
+		if (isArcError(err)) throw err;
 		throw createError(400, "Hook execution failed", {
 			code: `BEFORE_${args.op.toUpperCase()}_HOOK_ERROR`,
 			message: err.message
@@ -1683,6 +1684,7 @@ function SoftDeleteMixin(Base) {
 					meta: { id }
 				});
 			} catch (err) {
+				if (isArcError(err)) throw err;
 				throw createError(400, "Hook execution failed", {
 					code: "BEFORE_RESTORE_HOOK_ERROR",
 					message: err.message

package/dist/{applyPermissionResult-Tw4iXtlf.mjs → applyPermissionResult-BnyVE9eD.mjs}

@@ -1,3 +1,4 @@
+import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
 //#region src/permissions/fields.ts
 /**
 * Field-Level Permissions
@@ -238,6 +239,15 @@ async function evaluateAndApplyPermission(check, context, request, reply, opts)
 			resource: context.resource,
 			action: context.action
 		}, "Permission check threw");
+		if (err instanceof ArcError) {
+			reply.code(err.status).send({
+				code: err.code,
+				message: err.message,
+				status: err.status,
+				...err.meta ? { meta: err.meta } : {}
+			});
+			return false;
+		}
 		reply.code(403).send({
 			code: "arc.forbidden",
 			message: "Permission denied",

package/dist/cleanup/index.d.mts

@@ -0,0 +1,313 @@
+import { L as RequestWithExtras } from "../index-DPRH0Cme.mjs";
+import { A as CleanupWriteFence, C as CleanupResult, D as CleanupRunStore, E as CleanupRunStatus, F as PurgeStrategyKind, I as PurgeVerificationSummary, L as VerificationCheck, M as PurgeActor, N as PurgeEvidence, O as CleanupRunTransitionPatch, P as PurgeResourceResult, R as VerificationResult, S as CleanupRecipe, T as CleanupRunCreateResult, _ as CleanupPermissions, a as CleanupEvidenceStore, b as CleanupPlanItem, c as CleanupInput, d as CleanupLease, f as CleanupLimits, g as CleanupPermissionCheck, h as CleanupOutcomeStatus, i as CleanupContext, j as DEFAULT_CLEANUP_LIMITS, k as CleanupStepResult, l as CleanupJob, m as CleanupManifest, n as CLEANUP_TERMINAL_STATUSES, o as CleanupExecutionContext, p as CleanupLogger, r as CleanupCancelRequest, s as CleanupFinalizationPayload, t as Availability, u as CleanupJobQueue, v as CleanupPlan, w as CleanupRun, x as CleanupProgressSummary, y as CleanupPlanDraft } from "../types-C_ZZRcD6.mjs";
+import { t as ArcModule } from "../types-Cu6vVJmh.mjs";
+import { PurgeStrategyKind as PurgeStrategyKind$1 } from "@classytic/primitives/retention";
+import { canonicalJson } from "@classytic/primitives/canonical";
+import { CleanupStep } from "@classytic/repo-core/cleanup";
+//#region src/cleanup/compose.d.ts
+/** Metadata + steps for {@link recipeFromSteps}. */
+interface RecipeFromStepsInput {
+  /** Stable machine id, unique in the registry (e.g. `'cleanup.rebuild-projections'`). */
+  readonly id: string;
+  /** Plain-language label for the UI. */
+  readonly label: string;
+  /**
+   * Whether this recipe removes data. Defaults to `true` iff ANY step is
+   * destructive (a pure-rebuild recipe is non-destructive).
+   */
+  readonly destructive?: boolean;
+  /** Recipe/plan-schema version (persisted on the run). Defaults to `'1'`. */
+  readonly version?: string;
+  /**
+   * Strategy the run's evidence records. Defaults to `'hard'` when any step is
+   * destructive, `'soft'` otherwise (pure rebuilds remove no source data).
+   */
+  readonly evidenceStrategy?: PurgeStrategyKind$1;
+  /** Exact confirmation phrase; defaults (in the service) to the recipe id. */
+  readonly confirmationPhrase?: string;
+  /** Extra top-level retains beyond per-step `retained` lines. */
+  readonly retains?: readonly string[];
+  /** Extra top-level warnings beyond per-step warnings. */
+  readonly warnings?: readonly string[];
+  /**
+   * Recipe-level availability gate — go-live boundary, feature flag, etc.
+   * STEPS never decide availability (that is host policy). Defaults to always
+   * available.
+   */
+  available?(ctx: CleanupContext): Promise<Availability>;
+  /** Provider steps in EXECUTION ORDER. */
+  readonly steps: readonly CleanupStep[];
+}
+declare function recipeFromSteps(input: RecipeFromStepsInput): CleanupRecipe;
+//#endregion
+//#region src/cleanup/errors.d.ts
+/**
+ * Data Cleanup Center — stable, typed errors.
+ *
+ * Every failure the framework raises carries a stable machine `code` (so
+ * SDK/UI can branch) and an HTTP `status` (so the Arc resource maps cleanly).
+ * The codes are part of the public contract — do not rename.
+ */
+type CleanupErrorCode =
+/** No recipe registered under the requested id. */
+"CLEANUP_UNKNOWN_RECIPE" |
+/** Two recipes share an id at registry construction. */
+"CLEANUP_DUPLICATE_RECIPE" |
+/** The recipe's `available()` returned false. */
+"CLEANUP_RECIPE_UNAVAILABLE" |
+/** Execute called without the exact confirmation phrase. */
+"CLEANUP_CONFIRMATION_REQUIRED" |
+/** Execute called with an empty reason. */
+"CLEANUP_REASON_REQUIRED" |
+/** The re-planned digest differs from the client's — a new preview is required. */
+"CLEANUP_PLAN_CHANGED" |
+/** The plan carries unresolved blockers — a hard stop (§4.4). */
+"CLEANUP_BLOCKED" |
+/** The plan exceeds a framework size limit (items / results / reason / depth). */
+"CLEANUP_PLAN_TOO_LARGE" |
+/** A destructive run is already in progress (single-run fence, §8). */
+"CLEANUP_ALREADY_RUNNING" |
+/** The run id does not exist. */
+"CLEANUP_RUN_NOT_FOUND" |
+/** The action isn't valid for the run's current status (lost a CAS, etc.). */
+"CLEANUP_INVALID_ACTION" |
+/** No authenticated actor could be resolved for a destructive action (fail-closed). */
+"CLEANUP_ACTOR_REQUIRED" |
+/** Caller lacks permission for the operation. */
+"CLEANUP_FORBIDDEN";
+/**
+ * A framework error carrying BOTH `status` (read directly in code/tests) and
+ * `statusCode` (the Fastify convention arc's global error handler recognizes,
+ * step 4 of its classifier — a numeric `statusCode` + a separatored domain
+ * `code` maps to that exact status + code on the wire, never `arc.internal_error`).
+ */
+declare class CleanupError extends Error {
+  readonly code: CleanupErrorCode;
+  readonly status: number;
+  /** Alias of {@link status} — the property arc's error handler classifies on. */
+  readonly statusCode: number;
+  readonly meta?: Record<string, unknown>;
+  constructor(code: CleanupErrorCode, status: number, message: string, meta?: Record<string, unknown>);
+}
+/**
+ * Internal control-flow signal thrown by `throwIfCancelled()` when a run's
+ * durable `cancelRequested` flag is set. NOT a wire error — `processRun`
+ * catches it and CAS-transitions the run to `cancelled`.
+ */
+declare class CleanupCancelled extends Error {
+  readonly runId: string;
+  constructor(runId: string);
+}
+declare const CleanupErrors: {
+  readonly unknownRecipe: (id: string) => CleanupError;
+  readonly duplicateRecipe: (id: string) => CleanupError;
+  readonly unavailable: (id: string, reason: string) => CleanupError;
+  readonly confirmationRequired: (phrase: string) => CleanupError;
+  readonly reasonRequired: () => CleanupError;
+  readonly blocked: (blockers: readonly string[]) => CleanupError;
+  readonly planTooLarge: (detail: string) => CleanupError;
+  readonly actorRequired: () => CleanupError;
+  readonly planChanged: (expected: string, actual: string) => CleanupError;
+  readonly alreadyRunning: (runId: string) => CleanupError;
+  readonly runNotFound: (id: string) => CleanupError;
+  readonly invalidAction: (action: string, status: string) => CleanupError;
+  readonly forbidden: (operation: string) => CleanupError;
+};
+//#endregion
+//#region src/cleanup/memory.d.ts
+/**
+ * In-memory {@link CleanupRunStore}. Single-process only — see the module
+ * docblock for the production caveat.
+ */
+declare class MemoryCleanupRunStore implements CleanupRunStore {
+  #private;
+  /** Live run state, keyed by run id. Exposed for tests/inspection. */
+  readonly runs: Map<string, CleanupRun>;
+  constructor(now?: () => Date);
+  createIfPermitted(run: CleanupRun): Promise<CleanupRunCreateResult>;
+  get(id: string): Promise<CleanupRun | null>;
+  claim(id: string, lease: CleanupLease): Promise<CleanupRun | null>;
+  compareAndTransition(id: string, expected: readonly CleanupRunStatus[], to: CleanupRunStatus, patch?: CleanupRunTransitionPatch, leaseToken?: string): Promise<CleanupRun | null>;
+  reArmIfPermitted(id: string, patch: CleanupRunTransitionPatch): Promise<CleanupRun | null>;
+  requestCancel(id: string, request?: CleanupCancelRequest): Promise<CleanupRun | null>;
+  saveProgress(id: string, progress: CleanupProgressSummary, lease?: CleanupLease): Promise<void>;
+}
+/**
+ * In-memory {@link CleanupEvidenceStore} — idempotent by
+ * `evidence.operationId`, exactly as the port requires.
+ */
+declare class MemoryCleanupEvidenceStore implements CleanupEvidenceStore {
+  #private;
+  readonly evidence: PurgeEvidence[];
+  readonly manifests: CleanupManifest[];
+  finalize(input: {
+    evidence: PurgeEvidence;
+    manifest: CleanupManifest;
+  }): Promise<void>;
+}
+/**
+ * A MANUAL in-memory {@link CleanupJobQueue}: it records enqueued jobs and runs
+ * nothing on its own, so a test drives the worker deterministically
+ * (`for (const job of queue.jobs) await service.processRun(job.runId)`).
+ *
+ * Note this is NOT the service's default queue — omitting `jobQueue` entirely
+ * gives you a microtask-deferred in-process queue that DOES auto-run
+ * `processRun` off the request path.
+ */
+declare class MemoryCleanupJobQueue implements CleanupJobQueue {
+  readonly jobs: CleanupJob[];
+  enqueue(job: CleanupJob): Promise<void>;
+  /** Take everything enqueued so far, clearing the buffer. */
+  drain(): CleanupJob[];
+}
+//#endregion
+//#region src/cleanup/registry.d.ts
+/** UI/SDK-facing description of one recipe (no methods). */
+interface CleanupRecipeInfo {
+  readonly id: string;
+  readonly label: string;
+  readonly destructive: boolean;
+}
+interface CleanupRegistry {
+  /** Get a recipe by id, or throw `CLEANUP_UNKNOWN_RECIPE`. */
+  get(id: string): CleanupRecipe;
+  /** Get a recipe by id, or `undefined`. */
+  find(id: string): CleanupRecipe | undefined;
+  /** Every registered recipe. */
+  all(): readonly CleanupRecipe[];
+  /** Introspection payload for UI/SDK recipe cards. */
+  introspect(): readonly CleanupRecipeInfo[];
+}
+/**
+ * Build a registry from a recipe list. Throws `CLEANUP_DUPLICATE_RECIPE` at
+ * construction if two recipes share an id — a boot-time failure, never a
+ * silent last-wins overwrite.
+ */
+declare function createCleanupRegistry(recipes: readonly CleanupRecipe[]): CleanupRegistry;
+//#endregion
+//#region src/cleanup/service.d.ts
+interface CleanupServiceDeps {
+  registry: CleanupRegistry;
+  runStore: CleanupRunStore;
+  evidenceStore: CleanupEvidenceStore;
+  /** Optional write fence (§8). No-op when absent. */
+  writeFence?: CleanupWriteFence | undefined;
+  /**
+   * Durable job queue (§8). Defaults to a microtask-deferred in-process queue
+   * that calls `processRun` off the request path (single-process only). Inject
+   * BullMQ / SQS / repo-backed for cross-process durability + restart recovery.
+   */
+  jobQueue?: CleanupJobQueue | undefined;
+  /** Framework size caps. Defaults to {@link DEFAULT_CLEANUP_LIMITS}. */
+  limits?: Partial<CleanupLimits> | undefined;
+  /**
+   * Exclusive worker-lease duration. A crashed executor's run becomes
+   * claimable again this long after its last heartbeat (each persisted
+   * progress write renews the lease). Default 5 minutes.
+   */
+  leaseMs?: number | undefined;
+  /**
+   * Minimum interval between PERSISTED progress writes (and their piggybacked
+   * cancellation reads). `0` (default) persists every chunk. Failed steps are
+   * always persisted immediately. Keep well below `leaseMs` — persisted
+   * progress is also the lease heartbeat.
+   */
+  progressThrottleMs?: number | undefined;
+  /** Optional logger for release-failure / recovery diagnostics. */
+  logger?: CleanupContext["logger"];
+  /** Id generator — defaults to `crypto.randomUUID`. */
+  generateId?: () => string;
+  /** Clock — defaults to `() => new Date()`. */
+  now?: () => Date;
+}
+interface PreviewInput extends CleanupInput {
+  recipeId: string;
+  actor: PurgeActor;
+  ambient?: Readonly<Record<string, unknown>> | undefined;
+}
+interface ExecuteInput extends PreviewInput {
+  /** The digest the operator confirmed against — must match the re-plan. */
+  planDigest: string;
+  /** Non-empty justification, persisted on the run + evidence. */
+  reason: string;
+  /** For a destructive recipe: the exact confirmation phrase. */
+  confirmation?: string | undefined;
+}
+interface CancelInput {
+  /** Who requested the cancel (audit — persisted on the run + evidence). */
+  actor?: PurgeActor | undefined;
+  /** Why (audit). */
+  reason?: string | undefined;
+}
+interface CleanupService {
+  preview(input: PreviewInput): Promise<CleanupPlan>;
+  execute(input: ExecuteInput): Promise<CleanupRun>;
+  /** Worker entrypoint — run the persisted, enqueued operation to completion. */
+  processRun(runId: string): Promise<void>;
+  getRun(id: string): Promise<CleanupRun>;
+  cancel(id: string, input?: CancelInput): Promise<CleanupRun>;
+  retry(id: string): Promise<CleanupRun>;
+}
+/** Admission key serializing every destructive run behind one slot. */
+declare const GLOBAL_DESTRUCTIVE_KEY = "global-destructive";
+declare function createCleanupService(deps: CleanupServiceDeps): CleanupService;
+//#endregion
+//#region src/cleanup/module.d.ts
+interface DataCleanupModuleDeps {
+  /** The recipes this deployment exposes. Ids must be unique (boot-checked). */
+  recipes: readonly CleanupRecipe[];
+  /** Durable run store — host-owned persistence (atomic create + CAS transitions). */
+  runStore: CleanupRunStore;
+  /** Durable evidence + manifest store — host-owned, idempotent by operationId. */
+  evidenceStore: CleanupEvidenceStore;
+  /** Permission checks for view / execute / manage. */
+  permissions: CleanupPermissions;
+  /** Optional write fence (§8). */
+  writeFence?: CleanupWriteFence | undefined;
+  /** Optional durable job queue (§8) — defaults to microtask-deferred in-process. */
+  jobQueue?: CleanupJobQueue | undefined;
+  /** Framework size caps. */
+  limits?: Partial<CleanupLimits> | undefined;
+  /** Exclusive worker-lease duration (ms). Default 5 minutes. */
+  leaseMs?: number | undefined;
+  /** Min interval between persisted progress writes (ms). Default 0 (every chunk). */
+  progressThrottleMs?: number | undefined;
+  /** Route prefix. Default `/governance/data-cleanup`. */
+  prefix?: string | undefined;
+  /** Module name. Default `data-cleanup`. */
+  moduleName?: string | undefined;
+  /** App resource names this module supersedes. */
+  owns?: readonly string[] | undefined;
+  /**
+   * Derive the acting party from the request. Default reads `getUserId(req.scope)`
+   * (falling back to `req.user.id`) and FAILS CLOSED — a destructive governance
+   * action with no resolvable authenticated actor throws `CLEANUP_ACTOR_REQUIRED`
+   * (401) rather than attributing the purge to `user:unknown`.
+   */
+  resolveActor?: (req: RequestWithExtras) => PurgeActor;
+  /**
+   * Capture the request's serializable ambient scope (branch/company target) so
+   * the worker rebuilds the exact operation context. Must be JSON-serializable.
+   */
+  resolveAmbient?: (req: RequestWithExtras) => Readonly<Record<string, unknown>> | undefined;
+  /** Injected id generator (tests). */
+  generateId?: () => string;
+  /** Injected clock (tests). */
+  now?: () => Date;
+}
+/**
+ * Build the Data Cleanup Center Arc module. The module's public export is the
+ * live {@link CleanupService} (so other modules / tests can drive it directly).
+ */
+declare function createDataCleanupModule(deps: DataCleanupModuleDeps): ArcModule<CleanupService>;
+//#endregion
+//#region src/cleanup/plan-digest.d.ts
+/** `sha256(canonical(planMaterial))` as a hex digest. */
+declare function computePlanDigest(plan: Omit<CleanupPlan, "digest">): string;
+/**
+ * Integrity checksum of a completed manifest (§5). Excludes the digest field
+ * itself. Dates (e.g. `completedAt`) participate via the strict canonicalizer.
+ */
+declare function computeManifestDigest(manifest: Record<string, unknown>): string;
+//#endregion
+export { type Availability, CLEANUP_TERMINAL_STATUSES, type CancelInput, type CleanupCancelRequest, CleanupCancelled, type CleanupContext, CleanupError, type CleanupErrorCode, CleanupErrors, type CleanupEvidenceStore, type CleanupExecutionContext, type CleanupFinalizationPayload, type CleanupInput, type CleanupJob, type CleanupJobQueue, type CleanupLease, type CleanupLimits, type CleanupLogger, type CleanupManifest, type CleanupOutcomeStatus, type CleanupPermissionCheck, type CleanupPermissions, type CleanupPlan, type CleanupPlanDraft, type CleanupPlanItem, type CleanupProgressSummary, type CleanupRecipe, type CleanupRecipeInfo, type CleanupRegistry, type CleanupResult, type CleanupRun, type CleanupRunCreateResult, type CleanupRunStatus, type CleanupRunStore, type CleanupRunTransitionPatch, type CleanupService, type CleanupServiceDeps, type CleanupStepResult, type CleanupWriteFence, DEFAULT_CLEANUP_LIMITS, type DataCleanupModuleDeps, type ExecuteInput, GLOBAL_DESTRUCTIVE_KEY, MemoryCleanupEvidenceStore, MemoryCleanupJobQueue, MemoryCleanupRunStore, type PreviewInput, type PurgeActor, type PurgeEvidence, type PurgeResourceResult, type PurgeStrategyKind, type PurgeVerificationSummary, type RecipeFromStepsInput, type VerificationCheck, type VerificationResult, canonicalJson, computeManifestDigest, computePlanDigest, createCleanupRegistry, createCleanupService, createDataCleanupModule, recipeFromSteps };