@classytic/arc 2.11.3 → 2.13.1

package/dist/{BaseController-swXruJ2_.mjs → BaseController-DX_T-bDB.mjs}

@@ -1,11 +1,11 @@
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-BhY1OHoH.mjs";
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-Cxde4rpC.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { _ as isElevated, n as PUBLIC_SCOPE, o as getOrgId, v as isMember } from "./types-AOD8fxIw.mjs";
-import { M as simpleEqualityMatcher, j as getUserId, k as ArcQueryParser } from "./utils-CcYTj09l.mjs";
-import { t as buildQueryKey } from "./keys-CARyUjiR.mjs";
-import { M as applyFieldWritePermissions, P as resolveEffectiveRoles } from "./permissions-gd_aUWrR.mjs";
-import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { r as ForbiddenError } from "./errors-D5c-5BJL.mjs";
+import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
+import { b as isMember, c as getOrgId, n as PUBLIC_SCOPE, y as isElevated } from "./types-C_s5moIu.mjs";
+import { N as simpleEqualityMatcher, _ as ArcQueryParser, r as scheduleBackground, t as getUserId } from "./utils-_h9B3c57.mjs";
+import { d as applyFieldWritePermissions, p as resolveEffectiveRoles } from "./permissions-ohQyv50e.mjs";
+import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { t as buildQueryKey } from "./keys-CGcCbNyu.mjs";
 //#region src/core/AccessControl.ts
 const log = arcLog("access-control");
 var AccessControl = class {
@@ -195,7 +195,10 @@ var AccessControl = class {
 				};
 			}
 			if (this.idField !== "_id") {
-				if (typeof repository.getOne !== "function") throw new Error(`Resource with idField="${this.idField}" requires repository.getOne() to look up by custom field. Arc's BaseController cannot fall back to getById() because it would query by _id.`);
+				if (typeof repository.getOne !== "function") throw createDomainError("arc.adapter.capability_required", `Resource with idField="${this.idField}" requires repository.getOne() to look up by custom field. Arc's BaseController cannot fall back to getById() because it would query by _id.`, 501, {
+					capability: "getOne",
+					idField: this.idField
+				});
 			}
 			const item = await repository.getById(id, queryOptions);
 			if (!item) return {
@@ -311,6 +314,15 @@ var QueryResolver = class {
 		this.tenantField = config.tenantField !== void 0 ? config.tenantField : DEFAULT_TENANT_FIELD;
 	}
 	/**
+	* Swap the underlying parser. Mutates in place so the resolver instance
+	* stays referentially stable (hosts capturing a `queryResolver` ref via
+	* `defineResource({ controller })` keep that ref valid). Single source of
+	* truth — pairs with `BaseCrudController.setQueryParser()`.
+	*/
+	setParser(parser) {
+		this.queryParser = parser;
+	}
+	/**
 	* Resolve a request into parsed query options -- ONE parse per request.
 	* Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
 	*/
@@ -416,11 +428,6 @@ var QueryResolver = class {
 //#endregion
 //#region src/core/BaseCrudController.ts
 /**
-* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
-* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
-*/
-const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
-/**
 * Framework-agnostic CRUD controller implementing IController.
 *
 * Composes AccessControl, BodySanitizer, and QueryResolver. All shared
@@ -436,8 +443,6 @@ var BaseCrudController = class {
 	queryParser;
 	maxLimit;
 	defaultLimit;
-	/** `undefined` means "no default sort" (caller passed `false`). */
-	defaultSort;
 	resourceName;
 	tenantField;
 	idField = "_id";
@@ -448,7 +453,7 @@ var BaseCrudController = class {
 	/**
 	* Composable query resolution (parsing, pagination, sort, select/populate).
 	*
-	* Not `readonly` — `setQueryParser()` rebuilds this resolver to swap in a
+	* Not `readonly` — `setQueryParser()` rebuilds this resolver to swap in a
 	* different parser (e.g. mongokit's `QueryParser`). `defineResource` calls
 	* it automatically when a resource supplies both `controller` and
 	* `queryParser`.
@@ -463,7 +468,6 @@ var BaseCrudController = class {
 		this.queryParser = options.queryParser ?? getDefaultQueryParser();
 		this.maxLimit = options.maxLimit ?? 100;
 		this.defaultLimit = options.defaultLimit ?? 20;
-		this.defaultSort = options.defaultSort === false ? void 0 : options.defaultSort ?? "-createdAt";
 		this.resourceName = options.resourceName;
 		this.tenantField = options.tenantField !== void 0 ? options.tenantField : DEFAULT_TENANT_FIELD;
 		this.idField = options.idField ?? repository?.idField ?? "_id";
@@ -494,29 +498,19 @@ var BaseCrudController = class {
 		this.delete = this.delete.bind(this);
 	}
 	/**
-	* Swap the controller's query parser. Rebuilds the internal `QueryResolver`
-	* with the new parser while preserving every other config.
+	* Swap the controller's query parser. Mutates the existing `QueryResolver`
+	* in place via `QueryResolver.setParser()` — the resolver instance stays
+	* referentially stable, and there is no second copy of `defaultSort` /
+	* `tenantField` / `schemaOptions` for the swap to drift away from.
 	*
 	* Closes the v2.10.9 gap where `defineResource({ controller, queryParser })`
-	* forwarded the parser only to auto-constructed controllers; user-supplied
-	* controllers kept their default `ArcQueryParser`. `defineResource` calls
-	* this via duck-typing when both `controller` and `queryParser` are
-	* supplied — controllers that don't implement `setQueryParser` are left
-	* untouched.
-	*
-	* Idempotent + safe to call repeatedly. Does NOT touch `maxLimit` or
-	* `defaultLimit` — those are construction-time decisions.
+	* forwarded the parser only to auto-constructed controllers. `defineResource`
+	* calls this via duck-typing when both `controller` and `queryParser` are
+	* supplied; controllers that don't implement it are left untouched.
 	*/
 	setQueryParser(queryParser) {
 		this.queryParser = queryParser;
-		this.queryResolver = new QueryResolver({
-			queryParser: this.queryParser,
-			maxLimit: this.maxLimit,
-			defaultLimit: this.defaultLimit,
-			defaultSort: this.defaultSort,
-			schemaOptions: this.schemaOptions,
-			tenantField: this.tenantField
-		});
+		this.queryResolver.setParser(queryParser);
 	}
 	/**
 	* Get the tenant field name if multi-tenant scoping is enabled.
@@ -526,22 +520,46 @@ var BaseCrudController = class {
 		return this.tenantField || void 0;
 	}
 	/**
-	* Build top-level tenant options to thread into the repository call.
+	* Build the canonical repo-options bag from the Fastify request.
+	*
+	* Forwards the cross-kit canonical set (see repo-core's
+	* `STANDARD_REPO_OPTION_KEYS`) into every CRUD repo call so kit
+	* plugins (multi-tenant, audit, audit-trail, observability) get
+	* what they need without per-resource wiring:
+	*
+	* - **Tenant scope** — `[tenantField]: orgId` from `RequestScope`.
+	*   Plugin-scoped repos (mongokit's `multiTenantPlugin`) read tenant
+	*   scope from the TOP of the options bag, not `data.organizationId`.
+	*   Without this stamping, a tenant-scoped repo throws "Missing
+	*   'organizationId' in context" even when arc has injected the
+	*   tenant into the request body.
+	*   Multi-field tenancy from `_tenantFields` (populated by
+	*   `multiTenantPreset`) is merged in.
 	*
-	* Plugin-scoped repos (mongokit's `multiTenantPlugin`) read tenant scope
-	* from the TOP of the operation context — `context.organizationId`, not
-	* `context.data.organizationId`. Without this stamping, a tenant-scoped
-	* repo throws "Missing 'organizationId' in context" even when arc has
-	* injected the tenant into the request body.
+	* - **Audit attribution** — `userId` + `user` from the authenticated
+	*   actor. Mongokit's audit-log / audit-trail plugins read these
+	*   into the `who` column; sqlitekit's audit plugin reads the same
+	*   names. No host-side forwarding needed.
 	*
-	* Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
-	* requests, `{}` otherwise. Merges multi-field tenancy from
-	* `_tenantFields` (populated by `multiTenantPreset`).
+	* - **Trace correlation** — `requestId` from Fastify's request id
+	*   for stitching logs / events / downstream calls.
+	*
+	* - **`session` is intentionally NOT auto-set.** Sessions are tied
+	*   to explicit transaction scopes the controller doesn't manage;
+	*   pass `session` inline at the call site when running inside a
+	*   `withTransaction` helper.
+	*
+	* Method kept named `tenantRepoOptions` for back-compat with hosts
+	* that spread `...this.tenantRepoOptions(req)` (10+ call sites in
+	* arc, plus host overrides). The bag has always grown over time —
+	* hosts that don't want audit forwarding never read those keys.
 	*/
 	tenantRepoOptions(req) {
+		const cached = req._tenantRepoOptions;
+		if (cached) return cached;
 		const out = {};
+		const scope = this.meta(req)?._scope;
 		if (this.tenantField) {
-			const scope = this.meta(req)?._scope;
 			const orgId = scope ? getOrgId(scope) : void 0;
 			if (orgId) out[this.tenantField] = orgId;
 		}
@@ -549,6 +567,13 @@ var BaseCrudController = class {
 		if (presetFields && typeof presetFields === "object") {
 			for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
 		}
+		const userId = getUserId(req.user);
+		if (userId) out.userId = userId;
+		if (req.user) out.user = req.user;
+		const requestId = req.id;
+		if (requestId) out.requestId = requestId;
+		Object.freeze(out);
+		req._tenantRepoOptions = out;
 		return out;
 	}
 	/** Extract typed Arc internal metadata from request */
@@ -563,12 +588,12 @@ var BaseCrudController = class {
 	* Resolve the repository primary key for mutation calls.
 	*
 	* When the resource declares a custom `idField` (slug, jobId, UUID), the
-	* default behavior is to translate the route id → the fetched doc's `_id`
+	* default behavior is to translate the route id → the fetched doc's `_id`
 	* because most Mongo repositories key mutation methods off `_id`.
 	*
 	* Exception: if the repo exposes a matching `idField` property (e.g.
 	* MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
-	* repo handles lookup itself — pass the route id through unchanged.
+	* repo handles lookup itself — pass the route id through unchanged.
 	*/
 	resolveRepoId(id, existing) {
 		if (this.idField === "_id") return id;
@@ -578,24 +603,50 @@ var BaseCrudController = class {
 		return String(existing["_id"] ?? id);
 	}
 	/**
-	* Centralized 404 response builder. Maps the denial reason from
-	* `fetchDetailed()` into a structured `details.code` so consumers can
-	* distinguish "doc doesn't exist" from "doc filtered by policy/org scope"
-	* without parsing error strings.
+	* Read-side preflight for mutable-target operations (`update`, `delete`).
+	*
+	* Bundles the four steps that every mutation must do before touching the
+	* repo: (1) extract `:id`, (2) fetch under access control + tenant scope,
+	* (3) verify ownership, (4) translate the route id to the repo's primary
+	* key. Returning `{id, existing, repoId}` keeps the call sites a single
+	* line and makes drift between `update` and `delete` structurally
+	* impossible — there is one preflight, one denial-reason mapping, one
+	* ownership check.
+	*
+	* Pass `extraFetchOptions` for callers (e.g. soft-delete restore) that
+	* need to widen the fetch (`{ includeDeleted: true }`).
 	*/
-	notFoundResponse(reason = "NOT_FOUND") {
-		const code = reason ?? "NOT_FOUND";
+	async loadMutableTarget(req, extraFetchOptions) {
+		const id = this.requireIdParam(req);
+		const baseOptions = this.tenantRepoOptions(req);
+		const fetchOptions = extraFetchOptions ? {
+			...baseOptions,
+			...extraFetchOptions
+		} : baseOptions;
+		const { doc, reason } = await this.accessControl.fetchDetailed(id, req, this.repository, fetchOptions);
+		if (!doc) this.throwNotFound(reason);
+		if (!this.accessControl.checkOwnership(doc, req)) throw new ForbiddenError("You do not have permission to modify this resource");
 		return {
-			success: false,
-			error: {
-				NOT_FOUND: "Resource not found",
-				POLICY_FILTERED: "Resource not found",
-				ORG_SCOPE_DENIED: "Resource not found"
-			}[code] ?? "Resource not found",
-			status: 404,
-			details: { code }
+			id,
+			existing: doc,
+			repoId: this.resolveRepoId(id, doc)
 		};
 	}
+	/**
+	* Centralized 404 thrower. Maps the denial reason from `fetchDetailed()`
+	* into a `NotFoundError` so consumers can distinguish "doc doesn't
+	* exist" from "doc filtered by policy/org scope" via the error
+	* `details.code` set by the global error handler.
+	*/
+	throwNotFound(reason = "NOT_FOUND") {
+		const code = reason ?? "NOT_FOUND";
+		const err = new NotFoundError(this.resourceName ?? "Resource");
+		err.details = {
+			...err.details ?? {},
+			code
+		};
+		throw err;
+	}
 	/** Resolve cache config for a specific operation, merging per-op overrides */
 	resolveCacheConfig(operation) {
 		const cfg = this._cacheConfig;
@@ -621,47 +672,217 @@ var BaseCrudController = class {
 			})() : void 0
 		};
 	}
-	async list(req) {
-		const options = this.queryResolver.resolve(req, this.meta(req));
+	/** Shared `x-cache` response envelope builder. */
+	cacheResponse(data, cacheStatus) {
+		return {
+			data,
+			status: 200,
+			headers: { "x-cache": cacheStatus }
+		};
+	}
+	/** Required route-id helper shared by get/update/delete. Throws on missing id. */
+	requireIdParam(req) {
+		const id = req.params.id;
+		if (!id) throw createError(400, "ID parameter is required");
+		return id;
+	}
+	/**
+	* Normalizes `repo.exists()` return shapes across adapters. Per
+	* StandardRepo's contract, `exists` may return `boolean`, `{ _id }`,
+	* or `null` — every truthy non-null shape collapses to `true`.
+	*/
+	isExistsTruthy(result) {
+		return result !== null && result !== false && result !== void 0;
+	}
+	/**
+	* Run `executeBefore` then `executeAround` (or just the executor if no
+	* hooks are wired). Returns the around-phase result directly. Throws an
+	* `ArcError` (status 400, code `BEFORE_<OP>_HOOK_ERROR`) when the
+	* before-hook fails — the global error handler emits the canonical
+	* `ErrorContract` shape.
+	*
+	* The caller runs `executeAfter` separately via `runAfterHook` — typically
+	* after success-checking the result (delete checks `isDeleteSuccess`,
+	* update checks `if (!item)`).
+	*
+	* **Knobs:**
+	*   - `meta` — passed verbatim into `executeBefore` / `executeAround` opts.
+	*   - `pipeProcessedData` (default `true`) — whether `executeBefore`'s
+	*     return value flows into `executeAround` as the data parameter.
+	*     Set `false` for delete (current behaviour: discards before's
+	*     return, passes original input to around).
+	*/
+	async runHookedOpUntilResult(req, args, executor) {
+		const hooks = this.getHooks(req);
+		const hookOpts = {
+			user: req.user,
+			context: this.meta(req),
+			...args.meta ? { meta: args.meta } : {}
+		};
+		const pipeProcessed = args.pipeProcessedData !== false;
+		let processedData = args.input;
+		if (hooks && this.resourceName) try {
+			const beforeReturn = await hooks.executeBefore(this.resourceName, args.op, args.input, hookOpts);
+			if (pipeProcessed) processedData = beforeReturn;
+		} catch (err) {
+			throw createError(400, "Hook execution failed", {
+				code: `BEFORE_${args.op.toUpperCase()}_HOOK_ERROR`,
+				message: err.message
+			});
+		}
+		let result;
+		if (hooks && this.resourceName) result = await hooks.executeAround(this.resourceName, args.op, processedData, () => executor(processedData), hookOpts);
+		else result = await executor(processedData);
+		return result;
+	}
+	/**
+	* Run `executeAfter` for the given op + data. No-op when hooks aren't
+	* wired or `resourceName` isn't set. Caller passes the data shape it
+	* wants downstream after-handlers to receive — typically the result for
+	* create/update, the original input (`existing`) for delete.
+	*/
+	async runAfterHook(req, op, data, meta) {
+		const hooks = this.getHooks(req);
+		if (!hooks || !this.resourceName) return;
+		const user = req.user;
+		const arcContext = this.meta(req);
+		await hooks.executeAfter(this.resourceName, op, data, {
+			user,
+			context: arcContext,
+			...meta ? { meta } : {}
+		});
+	}
+	/** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
+	async withListCache(req, options) {
 		const cacheConfig = this.resolveCacheConfig("list");
 		const qc = req.server?.queryCache;
-		if (cacheConfig && qc) {
-			const version = await qc.getResourceVersion(this.resourceName);
-			const { userId, orgId } = this.cacheScope(req);
-			const key = buildQueryKey(this.resourceName, "list", version, options, userId, orgId);
-			const { data, status } = await qc.get(key);
-			if (status === "fresh") return {
-				success: true,
-				data,
-				status: 200,
-				headers: { "x-cache": "HIT" }
-			};
-			if (status === "stale") {
-				scheduleBackground(() => {
-					this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
-				});
-				return {
-					success: true,
-					data,
-					status: 200,
-					headers: { "x-cache": "STALE" }
-				};
-			}
-			const result = await this.executeListQuery(options, req);
-			await qc.set(key, result, cacheConfig);
-			return {
-				success: true,
-				data: result,
-				status: 200,
-				headers: { "x-cache": "MISS" }
-			};
+		if (!cacheConfig || !qc) return null;
+		const version = await qc.getResourceVersion(this.resourceName);
+		const { userId, orgId } = this.cacheScope(req);
+		const key = buildQueryKey(this.resourceName, "list", version, options, userId, orgId);
+		const { data, status } = await qc.get(key);
+		if (status === "fresh") return this.cacheResponse(data, "HIT");
+		if (status === "stale") {
+			scheduleBackground(() => {
+				this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
+			});
+			return this.cacheResponse(data, "STALE");
 		}
+		const result = await this.executeListQuery(options, req);
+		await qc.set(key, result, cacheConfig);
+		return this.cacheResponse(result, "MISS");
+	}
+	/** Cached `get()` flow with SWR semantics. Returns null when cache is disabled. */
+	async withGetCache(req, id, options) {
+		const cacheConfig = this.resolveCacheConfig("byId");
+		const qc = req.server?.queryCache;
+		if (!cacheConfig || !qc) return null;
+		const version = await qc.getResourceVersion(this.resourceName);
+		const { userId, orgId } = this.cacheScope(req);
+		const key = buildQueryKey(this.resourceName, "get", version, {
+			id,
+			...options
+		}, userId, orgId);
+		const { data, status } = await qc.get(key);
+		if (status === "fresh") return this.cacheResponse(data, "HIT");
+		if (status === "stale") {
+			scheduleBackground(() => {
+				this.executeGetQuery(id, options, req).then(({ doc: fresh }) => {
+					if (fresh) qc.set(key, fresh, cacheConfig);
+				}).catch(() => {});
+			});
+			return this.cacheResponse(data, "STALE");
+		}
+		const { doc, reason } = await this.executeGetQuery(id, options, req);
+		if (!doc) this.throwNotFound(reason);
+		await qc.set(key, doc, cacheConfig);
+		return this.cacheResponse(doc, "MISS");
+	}
+	async list(req) {
+		const dispatch = this.dispatchResourceVerb(req);
+		if (dispatch) return dispatch;
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const cached = await this.withListCache(req, options);
+		if (cached) return cached;
 		return {
-			success: true,
 			data: await this.executeListQuery(options, req),
 			status: 200
 		};
 	}
+	/**
+	* Resource-dispatch verbs router. Returns `null` when the request is
+	* a regular list query, otherwise returns the dispatch promise.
+	*
+	* Verbs (mutually exclusive — first match wins):
+	*   - `?_count=true` → `{ count: number }` via `repo.count()`
+	*   - `?_distinct=field` → `unknown[]` via `repo.distinct(field)`
+	*   - `?_exists=true` → `{ exists: boolean }` via `repo.exists()`
+	*
+	* All verbs share the resolved filter (parsed query + policy filters
+	* + tenant scope). Adapters that don't ship the underlying repo
+	* method get a `501` so failures surface loudly instead of falling
+	* back to a full table scan.
+	*/
+	dispatchResourceVerb(req) {
+		const query = req.query;
+		if (!query) return null;
+		const isTruthyFlag = (value) => value !== void 0 && value !== "" && value !== "false" && value !== false;
+		if (isTruthyFlag(query._count)) return this.dispatchCount(req);
+		const distinctField = query._distinct;
+		if (typeof distinctField === "string" && distinctField.length > 0) return this.dispatchDistinct(req, distinctField);
+		if (isTruthyFlag(query._exists)) return this.dispatchExists(req);
+		return null;
+	}
+	/** Resolve filter + tenant/audit options for a dispatch verb. */
+	resolveDispatchScope(req) {
+		return {
+			filter: this.queryResolver.resolve(req, this.meta(req)).filters ?? {},
+			options: this.tenantRepoOptions(req)
+		};
+	}
+	/** `?_count=true` → `repo.count(filter)` */
+	async dispatchCount(req) {
+		const repo = this.repository;
+		if (typeof repo.count !== "function") throw createError(501, "_count is not supported: the resource's storage adapter does not implement repo.count()");
+		const { filter, options } = this.resolveDispatchScope(req);
+		return {
+			data: { count: await repo.count(filter, options) },
+			status: 200
+		};
+	}
+	/** `?_distinct=field` → `repo.distinct(field, filter)` */
+	async dispatchDistinct(req, field) {
+		if (!this.isFieldExposedForRead(field)) throw createError(400, `_distinct field "${field}" is not allowed (hidden or system-managed)`);
+		const repo = this.repository;
+		if (typeof repo.distinct !== "function") throw createError(501, "_distinct is not supported: the resource's storage adapter does not implement repo.distinct()");
+		const { filter, options } = this.resolveDispatchScope(req);
+		return {
+			data: await repo.distinct(field, filter, options),
+			status: 200
+		};
+	}
+	/** `?_exists=true` → `repo.exists(filter)` */
+	async dispatchExists(req) {
+		const repo = this.repository;
+		if (typeof repo.exists !== "function") throw createError(501, "_exists is not supported: the resource's storage adapter does not implement repo.exists()");
+		const { filter, options } = this.resolveDispatchScope(req);
+		const result = await repo.exists(filter, options);
+		return {
+			data: { exists: this.isExistsTruthy(result) },
+			status: 200
+		};
+	}
+	/**
+	* True when `field` is safe to expose via `_distinct`. Mirrors the
+	* `select` allowlist — fields marked `hidden` or `systemManaged` in
+	* `schemaOptions.fieldRules` are NOT exposed (would leak password
+	* hashes, internal flags, etc).
+	*/
+	isFieldExposedForRead(field) {
+		const rules = this.schemaOptions.fieldRules?.[field];
+		if (!rules) return true;
+		return !(rules.hidden || rules.systemManaged);
+	}
 	/** Execute list query through hooks (extracted for cache revalidation) */
 	async executeListQuery(options, req) {
 		const hooks = this.getHooks(req);
@@ -676,59 +897,16 @@ var BaseCrudController = class {
 		}) : await repoGetAll();
 	}
 	async get(req) {
-		const id = req.params.id;
-		if (!id) return {
-			success: false,
-			error: "ID parameter is required",
-			status: 400
-		};
+		const id = this.requireIdParam(req);
 		const options = {
 			...this.queryResolver.resolve(req, this.meta(req)),
 			...this.tenantRepoOptions(req)
 		};
-		const cacheConfig = this.resolveCacheConfig("byId");
-		const qc = req.server?.queryCache;
-		if (cacheConfig && qc) {
-			const version = await qc.getResourceVersion(this.resourceName);
-			const { userId, orgId } = this.cacheScope(req);
-			const key = buildQueryKey(this.resourceName, "get", version, {
-				id,
-				...options
-			}, userId, orgId);
-			const { data, status } = await qc.get(key);
-			if (status === "fresh") return {
-				success: true,
-				data,
-				status: 200,
-				headers: { "x-cache": "HIT" }
-			};
-			if (status === "stale") {
-				scheduleBackground(() => {
-					this.executeGetQuery(id, options, req).then(({ doc: fresh }) => {
-						if (fresh) qc.set(key, fresh, cacheConfig);
-					}).catch(() => {});
-				});
-				return {
-					success: true,
-					data,
-					status: 200,
-					headers: { "x-cache": "STALE" }
-				};
-			}
-			const { doc: cached, reason: cacheReason } = await this.executeGetQuery(id, options, req);
-			if (!cached) return this.notFoundResponse(cacheReason);
-			await qc.set(key, cached, cacheConfig);
-			return {
-				success: true,
-				data: cached,
-				status: 200,
-				headers: { "x-cache": "MISS" }
-			};
-		}
+		const cached = await this.withGetCache(req, id, options);
+		if (cached) return cached;
 		const { doc, reason } = await this.executeGetQuery(id, options, req);
-		if (!doc) return this.notFoundResponse(reason);
+		if (!doc) this.throwNotFound(reason);
 		return {
-			success: true,
 			data: doc,
 			status: 200
 		};
@@ -760,188 +938,71 @@ var BaseCrudController = class {
 		if (this.tenantField && createOrgId) data[this.tenantField] = createOrgId;
 		const userId = getUserId(req.user);
 		if (userId) data.createdBy = userId;
-		const hooks = this.getHooks(req);
 		const user = req.user;
-		let processedData = data;
-		if (hooks && this.resourceName) try {
-			processedData = await hooks.executeBefore(this.resourceName, "create", data, {
-				user,
-				context: arcContext
-			});
-		} catch (err) {
-			return {
-				success: false,
-				error: "Hook execution failed",
-				details: {
-					code: "BEFORE_CREATE_HOOK_ERROR",
-					message: err.message
-				},
-				status: 400
-			};
-		}
-		const repoCreate = async () => this.repository.create(processedData, {
+		const item = await this.runHookedOpUntilResult(req, {
+			op: "create",
+			input: data
+		}, async (processed) => this.repository.create(processed, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req)
-		});
-		let item;
-		if (hooks && this.resourceName) {
-			item = await hooks.executeAround(this.resourceName, "create", processedData, repoCreate, {
-				user,
-				context: arcContext
-			});
-			await hooks.executeAfter(this.resourceName, "create", item, {
-				user,
-				context: arcContext
-			});
-		} else item = await repoCreate();
+		}));
+		await this.runAfterHook(req, "create", item);
 		return {
-			success: true,
 			data: item,
 			status: 201,
 			meta: { message: "Created successfully" }
 		};
 	}
 	async update(req) {
-		const id = req.params.id;
-		if (!id) return {
-			success: false,
-			error: "ID parameter is required",
-			status: 400
-		};
 		const arcContext = this.meta(req);
 		const data = this.bodySanitizer.sanitize(req.body ?? {}, "update", req, arcContext);
 		const user = req.user;
 		const userId = getUserId(user);
 		if (userId) data.updatedBy = userId;
-		const { doc: existing, reason: updateReason } = await this.accessControl.fetchDetailed(id, req, this.repository, this.tenantRepoOptions(req));
-		if (!existing) return this.notFoundResponse(updateReason);
-		if (!this.accessControl.checkOwnership(existing, req)) return {
-			success: false,
-			error: "You do not have permission to modify this resource",
-			details: { code: "OWNERSHIP_DENIED" },
-			status: 403
+		const { id, existing, repoId } = await this.loadMutableTarget(req);
+		const hookMeta = {
+			id,
+			existing
 		};
-		const repoId = this.resolveRepoId(id, existing);
-		const hooks = this.getHooks(req);
-		let processedData = data;
-		if (hooks && this.resourceName) try {
-			processedData = await hooks.executeBefore(this.resourceName, "update", data, {
-				user,
-				context: arcContext,
-				meta: {
-					id,
-					existing
-				}
-			});
-		} catch (err) {
-			return {
-				success: false,
-				error: "Hook execution failed",
-				details: {
-					code: "BEFORE_UPDATE_HOOK_ERROR",
-					message: err.message
-				},
-				status: 400
-			};
-		}
-		const repoUpdate = async () => this.repository.update(repoId, processedData, {
+		const item = await this.runHookedOpUntilResult(req, {
+			op: "update",
+			input: data,
+			meta: hookMeta
+		}, async (processed) => this.repository.update(repoId, processed, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req)
-		});
-		let item;
-		if (hooks && this.resourceName) {
-			item = await hooks.executeAround(this.resourceName, "update", processedData, repoUpdate, {
-				user,
-				context: arcContext,
-				meta: {
-					id,
-					existing
-				}
-			});
-			if (item) await hooks.executeAfter(this.resourceName, "update", item, {
-				user,
-				context: arcContext,
-				meta: {
-					id,
-					existing
-				}
-			});
-		} else item = await repoUpdate();
-		if (!item) return this.notFoundResponse("NOT_FOUND");
+		}));
+		if (!item) this.throwNotFound("NOT_FOUND");
+		await this.runAfterHook(req, "update", item, hookMeta);
 		return {
-			success: true,
 			data: item,
 			status: 200,
 			meta: { message: "Updated successfully" }
 		};
 	}
 	async delete(req) {
-		const id = req.params.id;
-		if (!id) return {
-			success: false,
-			error: "ID parameter is required",
-			status: 400
-		};
 		const arcContext = this.meta(req);
 		const user = req.user;
-		const { doc: existing, reason: deleteReason } = await this.accessControl.fetchDetailed(id, req, this.repository, this.tenantRepoOptions(req));
-		if (!existing) return this.notFoundResponse(deleteReason);
-		if (!this.accessControl.checkOwnership(existing, req)) return {
-			success: false,
-			error: "You do not have permission to delete this resource",
-			details: { code: "OWNERSHIP_DENIED" },
-			status: 403
-		};
-		const repoId = this.resolveRepoId(id, existing);
-		const hooks = this.getHooks(req);
-		if (hooks && this.resourceName) try {
-			await hooks.executeBefore(this.resourceName, "delete", existing, {
-				user,
-				context: arcContext,
-				meta: { id }
-			});
-		} catch (err) {
-			return {
-				success: false,
-				error: "Hook execution failed",
-				details: {
-					code: "BEFORE_DELETE_HOOK_ERROR",
-					message: err.message
-				},
-				status: 400
-			};
-		}
+		const { id, existing, repoId } = await this.loadMutableTarget(req);
+		const hookMeta = { id };
 		const deleteMode = req.query?.hard === "true" || req.query?.hard === true || req.body?.mode === "hard" ? "hard" : void 0;
-		const repoDelete = async () => this.repository.delete(repoId, {
+		const result = await this.runHookedOpUntilResult(req, {
+			op: "delete",
+			input: existing,
+			meta: hookMeta,
+			pipeProcessedData: false
+		}, async () => this.repository.delete(repoId, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req),
 			...deleteMode ? { mode: deleteMode } : {}
-		});
-		let result;
-		if (hooks && this.resourceName) result = await hooks.executeAround(this.resourceName, "delete", existing, repoDelete, {
-			user,
-			context: arcContext,
-			meta: { id }
-		});
-		else result = await repoDelete();
-		if (!(() => {
-			if (typeof result !== "object" || result === null) return !!result;
-			const r = result;
-			if (typeof r.success === "boolean") return r.success;
-			if (typeof r.deletedCount === "number") return r.deletedCount > 0;
-			return true;
-		})()) return this.notFoundResponse("NOT_FOUND");
-		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "delete", existing, {
-			user,
-			context: arcContext,
-			meta: { id }
-		});
-		const deleteResult = typeof result === "object" && result !== null ? result : {};
+		}));
+		if (!result) this.throwNotFound("NOT_FOUND");
+		await this.runAfterHook(req, "delete", existing, hookMeta);
+		const deleteResult = result;
 		return {
-			success: true,
 			data: {
 				message: deleteResult.message || "Deleted successfully",
 				...id ? { id } : {},
@@ -974,17 +1035,9 @@ function BulkMixin(Base) {
 	return class BulkController extends Base {
 		async bulkCreate(req) {
 			const repo = this.repository;
-			if (!repo.createMany) return {
-				success: false,
-				error: "Repository does not support createMany",
-				status: 501
-			};
+			if (!repo.createMany) throw createError(501, "Repository does not support createMany");
 			const rawItems = req.body?.items;
-			if (!Array.isArray(rawItems) || rawItems.length === 0) return {
-				success: false,
-				error: "Bulk create requires a non-empty items array",
-				status: 400
-			};
+			if (!Array.isArray(rawItems) || rawItems.length === 0) throw createError(400, "Bulk create requires a non-empty items array");
 			const items = rawItems;
 			const arcContext = this.meta(req);
 			const user = req.user;
@@ -993,20 +1046,10 @@ function BulkMixin(Base) {
 			if (this.tenantField) {
 				const scope = arcContext?._scope;
 				if (scope) {
-					if (scope.kind === "public") return {
-						success: false,
-						error: "Organization context required to bulk-create resources",
-						details: { code: "ORG_CONTEXT_REQUIRED" },
-						status: 403
-					};
+					if (scope.kind === "public") throw createError(403, "Organization context required to bulk-create resources", { code: "ORG_CONTEXT_REQUIRED" });
 					if (!isElevated(scope)) {
 						const orgId = getOrgId(scope);
-						if (!orgId) return {
-							success: false,
-							error: "Organization context required to bulk-create resources",
-							details: { code: "ORG_CONTEXT_REQUIRED" },
-							status: 403
-						};
+						if (!orgId) throw createError(403, "Organization context required to bulk-create resources", { code: "ORG_CONTEXT_REQUIRED" });
 						const tenantField = this.tenantField;
 						scopedItems = sanitizedItems.map((item) => ({
 							...item,
@@ -1023,7 +1066,6 @@ function BulkMixin(Base) {
 			const inserted = created.length;
 			const skipped = requested - inserted;
 			return {
-				success: true,
 				data: created,
 				status: skipped === 0 ? 201 : inserted === 0 ? 422 : 207,
 				meta: {
@@ -1116,49 +1158,21 @@ function BulkMixin(Base) {
 		}
 		async bulkUpdate(req) {
 			const repo = this.repository;
-			if (!repo.updateMany) return {
-				success: false,
-				error: "Repository does not support updateMany",
-				status: 501
-			};
+			if (!repo.updateMany) throw createError(501, "Repository does not support updateMany");
 			const body = req.body;
-			if (!body.filter || Object.keys(body.filter).length === 0) return {
-				success: false,
-				error: "Bulk update requires a non-empty filter",
-				status: 400
-			};
-			if (!body.data || Object.keys(body.data).length === 0) return {
-				success: false,
-				error: "Bulk update requires non-empty data",
-				status: 400
-			};
+			if (!body.filter || Object.keys(body.filter).length === 0) throw createError(400, "Bulk update requires a non-empty filter");
+			if (!body.data || Object.keys(body.data).length === 0) throw createError(400, "Bulk update requires non-empty data");
 			const scopedFilter = this.buildBulkFilter(body.filter, req);
-			if (scopedFilter === null) return {
-				success: false,
-				error: "Organization context required for bulk update",
-				details: { code: "ORG_CONTEXT_REQUIRED" },
-				status: 403
-			};
+			if (scopedFilter === null) throw createError(403, "Organization context required for bulk update", { code: "ORG_CONTEXT_REQUIRED" });
 			const arcContext = this.meta(req);
 			const user = req.user;
 			const { sanitized, stripped, mixedShape } = this.sanitizeBulkUpdateData(body.data, req, arcContext);
-			if (mixedShape) return {
-				success: false,
-				error: "Bulk update payload cannot mix operator keys ($set, $inc, ...) with flat fields. Pick one shape.",
-				details: { code: "MIXED_UPDATE_SHAPE" },
-				status: 400
-			};
-			if (Object.keys(sanitized).length === 0) return {
-				success: false,
-				error: "Bulk update payload contained only protected fields",
-				details: {
-					code: "ALL_FIELDS_STRIPPED",
-					stripped
-				},
-				status: 400
-			};
+			if (mixedShape) throw createError(400, "Bulk update payload cannot mix operator keys ($set, $inc, ...) with flat fields. Pick one shape.", { code: "MIXED_UPDATE_SHAPE" });
+			if (Object.keys(sanitized).length === 0) throw createError(400, "Bulk update payload contained only protected fields", {
+				code: "ALL_FIELDS_STRIPPED",
+				stripped
+			});
 			return {
-				success: true,
 				data: await repo.updateMany(scopedFilter, sanitized, {
 					user,
 					context: arcContext
@@ -1183,33 +1197,16 @@ function BulkMixin(Base) {
 		*/
 		async bulkDelete(req) {
 			const repo = this.repository;
-			if (!repo.deleteMany) return {
-				success: false,
-				error: "Repository does not support deleteMany",
-				status: 501
-			};
+			if (!repo.deleteMany) throw createError(501, "Repository does not support deleteMany");
 			const body = req.body;
 			let userFilter;
 			if (body.ids && body.ids.length > 0) {
-				if (body.filter && Object.keys(body.filter).length > 0) return {
-					success: false,
-					error: "Bulk delete accepts either `ids` or `filter`, not both",
-					status: 400
-				};
+				if (body.filter && Object.keys(body.filter).length > 0) throw createError(400, "Bulk delete accepts either `ids` or `filter`, not both");
 				userFilter = { [this.idField]: { $in: body.ids } };
 			} else if (body.filter && Object.keys(body.filter).length > 0) userFilter = body.filter;
-			else return {
-				success: false,
-				error: "Bulk delete requires a non-empty `filter` or `ids` array",
-				status: 400
-			};
+			else throw createError(400, "Bulk delete requires a non-empty `filter` or `ids` array");
 			const scopedFilter = this.buildBulkFilter(userFilter, req);
-			if (scopedFilter === null) return {
-				success: false,
-				error: "Organization context required for bulk delete",
-				details: { code: "ORG_CONTEXT_REQUIRED" },
-				status: 403
-			};
+			if (scopedFilter === null) throw createError(403, "Organization context required for bulk delete", { code: "ORG_CONTEXT_REQUIRED" });
 			const hardHint = req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard";
 			const arcContext = this.meta(req);
 			const options = {
@@ -1218,7 +1215,6 @@ function BulkMixin(Base) {
 			};
 			if (hardHint) options.mode = "hard";
 			return {
-				success: true,
 				data: await repo.deleteMany(scopedFilter, options),
 				status: 200
 			};
@@ -1245,14 +1241,17 @@ function SlugMixin(Base) {
 					...options?.filter ?? {}
 				};
 				item = await repo.getOne(filter, options);
-			} else return {
-				success: false,
-				error: "Slug lookup not implemented — repository needs getBySlug() or getOne()",
-				status: 501
-			};
-			if (!this.accessControl.validateItemAccess(item, req)) return this.notFoundResponse(item ? "POLICY_FILTERED" : "NOT_FOUND");
+			} else throw createError(501, "Slug lookup not implemented — repository needs getBySlug() or getOne()");
+			if (!this.accessControl.validateItemAccess(item, req)) {
+				const code = item ? "POLICY_FILTERED" : "NOT_FOUND";
+				const err = new NotFoundError(this.resourceName ?? "Resource");
+				err.details = {
+					...err.details ?? {},
+					code
+				};
+				throw err;
+			}
 			return {
-				success: true,
 				data: item,
 				status: 200
 			};
@@ -1265,39 +1264,21 @@ function SoftDeleteMixin(Base) {
 	return class SoftDeleteController extends Base {
 		async getDeleted(req) {
 			const repo = this.repository;
-			if (!repo.getDeleted) return {
-				success: false,
-				error: "Soft delete not implemented",
-				status: 501
-			};
+			if (!repo.getDeleted) throw createError(501, "Soft delete not implemented");
 			const parsed = this.queryResolver.resolve(req, this.meta(req));
 			return {
-				success: true,
 				data: await repo.getDeleted(parsed, parsed),
 				status: 200
 			};
 		}
 		async restore(req) {
 			const repo = this.repository;
-			if (!repo.restore) return {
-				success: false,
-				error: "Restore not implemented",
-				status: 501
-			};
+			if (!repo.restore) throw createError(501, "Restore not implemented");
 			const id = req.params.id;
-			if (!id) return {
-				success: false,
-				error: "ID parameter is required",
-				status: 400
-			};
+			if (!id) throw createError(400, "ID parameter is required");
 			const existing = await this.accessControl.fetchWithAccessControl(id, req, repo, { includeDeleted: true });
-			if (!existing) return this.notFoundResponse("NOT_FOUND");
-			if (!this.accessControl.checkOwnership(existing, req)) return {
-				success: false,
-				error: "You do not have permission to restore this resource",
-				details: { code: "OWNERSHIP_DENIED" },
-				status: 403
-			};
+			if (!existing) throw new NotFoundError(this.resourceName ?? "Resource");
+			if (!this.accessControl.checkOwnership(existing, req)) throw new ForbiddenError("You do not have permission to restore this resource");
 			const arcContext = this.meta(req);
 			const user = req.user;
 			const repoId = this.resolveRepoId(id, existing);
@@ -1309,15 +1290,10 @@ function SoftDeleteMixin(Base) {
 					meta: { id }
 				});
 			} catch (err) {
-				return {
-					success: false,
-					error: "Hook execution failed",
-					details: {
-						code: "BEFORE_RESTORE_HOOK_ERROR",
-						message: err.message
-					},
-					status: 400
-				};
+				throw createError(400, "Hook execution failed", {
+					code: "BEFORE_RESTORE_HOOK_ERROR",
+					message: err.message
+				});
 			}
 			const repoRestore = () => repo.restore(repoId);
 			let item;
@@ -1327,14 +1303,13 @@ function SoftDeleteMixin(Base) {
 				meta: { id }
 			});
 			else item = await repoRestore();
-			if (!item) return this.notFoundResponse("NOT_FOUND");
+			if (!item) throw new NotFoundError(this.resourceName ?? "Resource");
 			if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "restore", item, {
 				user,
 				context: arcContext,
 				meta: { id }
 			});
 			return {
-				success: true,
 				data: item,
 				status: 200,
 				meta: { message: "Restored successfully" }
@@ -1348,30 +1323,20 @@ function TreeMixin(Base) {
 	return class TreeController extends Base {
 		async getTree(req) {
 			const repo = this.repository;
-			if (!repo.getTree) return {
-				success: false,
-				error: "Tree structure not implemented",
-				status: 501
-			};
+			if (!repo.getTree) throw createError(501, "Tree structure not implemented");
 			const options = this.queryResolver.resolve(req, this.meta(req));
 			return {
-				success: true,
 				data: await repo.getTree(options),
 				status: 200
 			};
 		}
 		async getChildren(req) {
 			const repo = this.repository;
-			if (!repo.getChildren) return {
-				success: false,
-				error: "Tree structure not implemented",
-				status: 501
-			};
+			if (!repo.getChildren) throw createError(501, "Tree structure not implemented");
 			const parentField = this._presetFields.parentField ?? "parent";
 			const parentId = req.params[parentField] ?? req.params.parent ?? req.params.id;
 			const options = this.queryResolver.resolve(req, this.meta(req));
 			return {
-				success: true,
 				data: await repo.getChildren(parentId, options),
 				status: 200
 			};