@classytic/arc 2.18.2 → 2.18.4

package/dist/{BaseController-DPwe89qs.mjs → BaseController-B-uXzf6I.mjs}

@@ -1,10 +1,11 @@
-import { o as DEFAULT_TENANT_FIELD } from "./constants-TrJVIJl0.mjs";
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-TrJVIJl0.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
-import { b as isElevated, c as getOrgId } from "./types-Bi0r0vjG.mjs";
-import { I as simpleEqualityMatcher, b as ArcQueryParser, o as scheduleBackground, t as getUserId } from "./utils-BMQK8mRl.mjs";
-import { w as BodySanitizer } from "./routerShared-Dl0A77Ba.mjs";
-import { t as buildQueryKey } from "./keys-DopsCuyQ.mjs";
+import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
+import { I as simpleEqualityMatcher, b as ArcQueryParser, o as scheduleBackground, t as getUserId } from "./utils-xAQeDyU_.mjs";
+import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-3uzwkbQt.mjs";
+import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { t as buildQueryKey } from "./keys-B3yyBEyH.mjs";
 //#region src/core/AccessControl.ts
 const log = arcLog("access-control");
 var AccessControl = class {
@@ -241,6 +242,337 @@ var AccessControl = class {
 	}
 };
 //#endregion
+//#region src/core/BodySanitizer.ts
+/**
+* BodySanitizer - Composable body sanitization logic extracted from BaseController.
+*
+* Strips readonly fields, system-managed fields, and applies field-level
+* write permissions from request bodies before create/update operations.
+*
+* Designed to be used standalone or composed into controllers.
+*/
+const DEFAULT_FIELD_WRITE_DENIAL_POLICY = "reject";
+var BodySanitizer = class {
+	schemaOptions;
+	onFieldWriteDenied;
+	constructor(config) {
+		this.schemaOptions = config.schemaOptions;
+		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
+	}
+	/**
+	* Strip readonly and system-managed fields from request body.
+	* Prevents clients from overwriting _id, timestamps, __v, etc.
+	*
+	* Also applies field-level write permissions when the request has
+	* field permission metadata.
+	*/
+	sanitize(body, _operation, req, meta) {
+		let sanitized = { ...body };
+		for (const field of SYSTEM_FIELDS) delete sanitized[field];
+		const scopeForRules = req ? (meta ?? req.metadata)?._scope ?? PUBLIC_SCOPE : void 0;
+		const scopeIsElevated = scopeForRules ? isElevated(scopeForRules) : false;
+		const fieldRules = this.schemaOptions.fieldRules ?? {};
+		for (const [field, rules] of Object.entries(fieldRules)) {
+			const bypass = Boolean(rules.preserveForElevated) && scopeIsElevated;
+			if ((rules.systemManaged || rules.readonly) && !bypass) delete sanitized[field];
+			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate) && !bypass) delete sanitized[field];
+		}
+		if (req) {
+			const arcContext = meta ?? req.metadata;
+			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
+			if (!isElevated(scope)) {
+				const fieldPerms = arcContext?.arc?.fields;
+				if (fieldPerms) {
+					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
+					const { body: filtered, deniedFields } = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+					if (deniedFields.length > 0 && this.onFieldWriteDenied === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
+					sanitized = filtered;
+				}
+			}
+		}
+		return sanitized;
+	}
+};
+//#endregion
+//#region src/core/crud/requestPipeline.ts
+/**
+* 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.
+*
+* - **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.
+*
+* - **Trace correlation** — `requestId` from Fastify's request id
+*   for stitching logs / events / downstream calls, plus `traceId`
+*   (the 32-hex W3C trace id, canonical repo-option key since
+*   repo-core 0.6) when the requestId plugin validated an incoming
+*   `traceparent` header.
+*
+* - **`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.
+*/
+function buildTenantRepoOptions(req, tenantField, arcContext) {
+	const cached = req._tenantRepoOptions;
+	if (cached) return cached;
+	const out = {};
+	const scope = arcContext?._scope;
+	if (tenantField) {
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (orgId) out[tenantField] = orgId;
+	}
+	const presetFields = req._tenantFields;
+	if (presetFields && typeof presetFields === "object") {
+		for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
+	}
+	if (tenantField && out[tenantField] == null && scope && isElevated(scope)) out.bypassTenant = true;
+	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;
+	const traceparent = req.traceContext?.traceparent;
+	if (traceparent) {
+		const traceId = traceparent.split("-")[1];
+		if (traceId) out.traceId = traceId;
+	}
+	Object.freeze(out);
+	req._tenantRepoOptions = out;
+	return out;
+}
+/**
+* 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`
+* 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.
+*/
+function resolveMutationRepoId(id, existing, idField, repository) {
+	if (idField === "_id") return id;
+	if (!existing) return id;
+	const repoIdField = repository.idField;
+	if (repoIdField && repoIdField === idField) return id;
+	return String(existing["_id"] ?? id);
+}
+/**
+* Build the canonical CRUD 404. Maps the denial reason from
+* `AccessControl.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.
+*/
+function buildNotFoundError(reason, resourceName) {
+	const code = reason ?? "NOT_FOUND";
+	const err = new NotFoundError(resourceName ?? "Resource");
+	err.details = {
+		...err.details ?? {},
+		code
+	};
+	return err;
+}
+/** Resolve cache config for a specific operation, merging per-op overrides. */
+function resolveOpCacheConfig(cfg, operation) {
+	if (!cfg || cfg.disabled) return null;
+	const opOverride = cfg[operation];
+	return {
+		staleTime: opOverride?.staleTime ?? cfg.staleTime ?? 0,
+		gcTime: opOverride?.gcTime ?? cfg.gcTime ?? 60,
+		tags: cfg.tags
+	};
+}
+/**
+* Extract user/org IDs from request for cache key scoping.
+* Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
+* Universal resources (tenantField: false) get shared cache keys.
+*/
+function deriveCacheScope(req, tenantField, arcContext) {
+	return {
+		userId: getUserId(req.user),
+		orgId: tenantField ? (() => {
+			const scope = arcContext?._scope;
+			return scope ? getOrgId(scope) : void 0;
+		})() : void 0
+	};
+}
+/** Shared `x-cache` response envelope builder. */
+function buildCacheEnvelope(data, cacheStatus) {
+	return {
+		data,
+		status: 200,
+		headers: { "x-cache": cacheStatus }
+	};
+}
+/**
+* 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 `executeAfterHook` —
+* typically after success-checking the result (delete checks the repo
+* result, 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 function executeHookedOp(ctx, args, executor) {
+	const { hooks, resourceName, arcContext, user } = ctx;
+	const hookOpts = {
+		user,
+		context: arcContext,
+		...args.meta ? { meta: args.meta } : {}
+	};
+	const pipeProcessed = args.pipeProcessedData !== false;
+	let processedData = args.input;
+	if (hooks && resourceName) try {
+		const beforeReturn = await hooks.executeBefore(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 && resourceName) result = await hooks.executeAround(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 function executeAfterHook(ctx, op, data, meta) {
+	const { hooks, resourceName, arcContext, user } = ctx;
+	if (!hooks || !resourceName) return;
+	await hooks.executeAfter(resourceName, op, data, {
+		user,
+		context: arcContext,
+		...meta ? { meta } : {}
+	});
+}
+//#endregion
+//#region src/utils/repoFeature.ts
+/**
+* Repository feature-detection helper for arc mixins.
+*
+* Arc's `RepositoryLike` is the minimum contract every adapter
+* implements (`getById`, `getOne`, `create`, `update`, `delete`,
+* `find`). Beyond that, kits MAY expose specialized methods —
+* `createMany`, `updateMany`, `deleteMany`, `getTree`, `getBySlug`,
+* `getDeleted`, `restore`, etc. — that arc mixins detect at call
+* time and surface as 501 when missing.
+*
+* Every mixin used to spell out its own narrowing cast inline:
+*
+* ```ts
+* const repo = this.repository as unknown as {
+*   getTree?: (options?: unknown) => Promise<AnyRecord[]>;
+* };
+* ```
+*
+* Centralizing the cast keeps every feature-detection site reading
+* the same shape. The helper does not intersect with `RepositoryLike`
+* on purpose: some standard methods (`createMany`, `updateMany`) live
+* on `StandardRepo` with kit-generic signatures, and intersecting
+* would force the caller's narrowed signature to merge with the wider
+* default, producing mismatched return types. Declare every method
+* you need (base or feature) in `TFeatures`.
+*
+* @example
+* ```ts
+* const repo = withRepoFeatures<{
+*   createMany?: (items: unknown[], options?: unknown) => Promise<AnyRecord[]>;
+* }>(this.repository);
+* if (!repo.createMany) throw createError(501, "...");
+* ```
+*/
+function withRepoFeatures(repo) {
+	return repo;
+}
+//#endregion
+//#region src/core/crud/resourceVerbs.ts
+const isTruthyFlag = (value) => value !== void 0 && value !== "" && value !== "false" && value !== false;
+/**
+* Match a request query against the resource-dispatch verbs. Returns
+* `null` when the request is a regular list query.
+*
+* Verbs (mutually exclusive — first match wins):
+*   - `?_count=true` → `{ kind: 'count' }`
+*   - `?_distinct=field` → `{ kind: 'distinct', field }`
+*   - `?_exists=true` → `{ kind: 'exists' }`
+*/
+function matchResourceVerb(query) {
+	if (!query) return null;
+	if (isTruthyFlag(query._count)) return { kind: "count" };
+	const distinctField = query._distinct;
+	if (typeof distinctField === "string" && distinctField.length > 0) return {
+		kind: "distinct",
+		field: distinctField
+	};
+	if (isTruthyFlag(query._exists)) return { kind: "exists" };
+	return null;
+}
+/**
+* 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`.
+*/
+function isExistsResultTruthy(result) {
+	return result !== null && result !== false && result !== void 0;
+}
+/** `?_count=true` → `repo.count(filter)` */
+async function runCountVerb(repository, resolveScope) {
+	const repo = withRepoFeatures(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 } = resolveScope();
+	return { count: await repo.count(filter, options) };
+}
+/** `?_distinct=field` → `repo.distinct(field, filter)` */
+async function runDistinctVerb(repository, field, resolveScope) {
+	const repo = withRepoFeatures(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 } = resolveScope();
+	return await repo.distinct(field, filter, options);
+}
+/**
+* `?_exists=true` → `repo.exists(filter)`. Returns the RAW repo result —
+* the controller collapses it via its (overridable) `isExistsTruthy`
+* so subclass overrides of the truthiness rule keep working.
+*/
+async function runExistsVerb(repository, resolveScope) {
+	const repo = withRepoFeatures(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 } = resolveScope();
+	return await repo.exists(filter, options);
+}
+//#endregion
 //#region src/core/fieldRulePredicates.ts
 /**
 * True when the field is allowed to appear in client-readable surfaces
@@ -466,6 +798,15 @@ var BaseCrudController = class {
 	_matchesFilter;
 	_presetFields = {};
 	_cacheConfig;
+	/**
+	* Retained construction-time values so partial `configure()` rebuilds
+	* (e.g. `configure({ schemaOptions })`) reuse them instead of silently
+	* falling back to the sub-component defaults (`-createdAt` sort,
+	* `reject` write-denial) — `defaultSort: false` matters for kits
+	* without a `createdAt` column, `strip` for legacy write semantics.
+	*/
+	_defaultSort;
+	_onFieldWriteDenied;
 	constructor(repository, options = {}) {
 		this.repository = repository;
 		this.schemaOptions = options.schemaOptions ?? {};
@@ -478,6 +819,8 @@ var BaseCrudController = class {
 		this._matchesFilter = options.matchesFilter;
 		if (options.cache) this._cacheConfig = options.cache;
 		if (options.presetFields) this._presetFields = options.presetFields;
+		this._defaultSort = options.defaultSort;
+		this._onFieldWriteDenied = options.onFieldWriteDenied;
 		this.accessControl = new AccessControl({
 			tenantField: this.tenantField,
 			idField: this.idField,
@@ -485,13 +828,13 @@ var BaseCrudController = class {
 		});
 		this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
-			onFieldWriteDenied: options.onFieldWriteDenied
+			onFieldWriteDenied: this._onFieldWriteDenied
 		});
 		this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
 			maxLimit: this.maxLimit,
 			defaultLimit: this.defaultLimit,
-			defaultSort: options.defaultSort,
+			defaultSort: this._defaultSort,
 			schemaOptions: this.schemaOptions,
 			tenantField: this.tenantField
 		});
@@ -547,8 +890,6 @@ var BaseCrudController = class {
 		let rebuildAccessControl = false;
 		let rebuildBodySanitizer = false;
 		let rebuildQueryResolver = false;
-		let bodySanitizerOnFieldWriteDenied;
-		let resolverDefaultSort;
 		if (options.tenantField !== void 0) {
 			this.tenantField = options.tenantField;
 			rebuildAccessControl = true;
@@ -568,7 +909,7 @@ var BaseCrudController = class {
 			rebuildQueryResolver = true;
 		}
 		if (options.onFieldWriteDenied !== void 0) {
-			bodySanitizerOnFieldWriteDenied = options.onFieldWriteDenied;
+			this._onFieldWriteDenied = options.onFieldWriteDenied;
 			rebuildBodySanitizer = true;
 		}
 		if (options.queryParser !== void 0) this.setQueryParser(options.queryParser);
@@ -581,7 +922,7 @@ var BaseCrudController = class {
 			rebuildQueryResolver = true;
 		}
 		if (options.defaultSort !== void 0) {
-			resolverDefaultSort = options.defaultSort;
+			this._defaultSort = options.defaultSort;
 			rebuildQueryResolver = true;
 		}
 		if (options.cache !== void 0) this._cacheConfig = options.cache;
@@ -593,13 +934,13 @@ var BaseCrudController = class {
 		});
 		if (rebuildBodySanitizer) this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
-			onFieldWriteDenied: bodySanitizerOnFieldWriteDenied
+			onFieldWriteDenied: this._onFieldWriteDenied
 		});
 		if (rebuildQueryResolver) this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
 			maxLimit: this.maxLimit,
 			defaultLimit: this.defaultLimit,
-			defaultSort: resolverDefaultSort,
+			defaultSort: this._defaultSort,
 			schemaOptions: this.schemaOptions,
 			tenantField: this.tenantField
 		});
@@ -612,62 +953,20 @@ var BaseCrudController = class {
 		return this.tenantField || void 0;
 	}
 	/**
-	* 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.
-	*
-	* - **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.
-	*
-	* - **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.
+	* Build the canonical repo-options bag (tenant scope, audit
+	* attribution, trace correlation) from the Fastify request. Full
+	* contract + rationale on `buildTenantRepoOptions` in
+	* `crud/requestPipeline.ts` — this delegate exists so host overrides
+	* and duck-typed consumers (aggregation router, MCP bridge) keep the
+	* same `protected` entry point.
 	*
 	* 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 —
+	* 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 orgId = scope ? getOrgId(scope) : void 0;
-			if (orgId) out[this.tenantField] = orgId;
-		}
-		const presetFields = req._tenantFields;
-		if (presetFields && typeof presetFields === "object") {
-			for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
-		}
-		if (this.tenantField && out[this.tenantField] == null && scope && isElevated(scope)) out.bypassTenant = true;
-		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;
+		return buildTenantRepoOptions(req, this.tenantField, this.meta(req));
 	}
 	/** Extract typed Arc internal metadata from request */
 	meta(req) {
@@ -678,22 +977,13 @@ var BaseCrudController = class {
 		return this.meta(req)?.arc?.hooks ?? null;
 	}
 	/**
-	* 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`
-	* 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.
+	* Resolve the repository primary key for mutation calls. Translates a
+	* custom route `idField` (slug, jobId, UUID) to the fetched doc's `_id`
+	* unless the repo declares a matching `idField` of its own — see
+	* `resolveMutationRepoId` in `crud/requestPipeline.ts`.
 	*/
 	resolveRepoId(id, existing) {
-		if (this.idField === "_id") return id;
-		if (!existing) return id;
-		const repoIdField = this.repository.idField;
-		if (repoIdField && repoIdField === this.idField) return id;
-		return String(existing["_id"] ?? id);
+		return resolveMutationRepoId(id, existing, this.idField, this.repository);
 	}
 	/**
 	* Read-side preflight for mutable-target operations (`update`, `delete`).
@@ -732,24 +1022,11 @@ var BaseCrudController = class {
 	* `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;
+		throw buildNotFoundError(reason, this.resourceName);
 	}
 	/** Resolve cache config for a specific operation, merging per-op overrides */
 	resolveCacheConfig(operation) {
-		const cfg = this._cacheConfig;
-		if (!cfg || cfg.disabled) return null;
-		const opOverride = cfg[operation];
-		return {
-			staleTime: opOverride?.staleTime ?? cfg.staleTime ?? 0,
-			gcTime: opOverride?.gcTime ?? cfg.gcTime ?? 60,
-			tags: cfg.tags
-		};
+		return resolveOpCacheConfig(this._cacheConfig, operation);
 	}
 	/**
 	* Extract user/org IDs from request for cache key scoping.
@@ -757,21 +1034,11 @@ var BaseCrudController = class {
 	* Universal resources (tenantField: false) get shared cache keys.
 	*/
 	cacheScope(req) {
-		return {
-			userId: getUserId(req.user),
-			orgId: this.tenantField ? (() => {
-				const scope = this.meta(req)?._scope;
-				return scope ? getOrgId(scope) : void 0;
-			})() : void 0
-		};
+		return deriveCacheScope(req, this.tenantField, this.meta(req));
 	}
 	/** Shared `x-cache` response envelope builder. */
 	cacheResponse(data, cacheStatus) {
-		return {
-			data,
-			status: 200,
-			headers: { "x-cache": cacheStatus }
-		};
+		return buildCacheEnvelope(data, cacheStatus);
 	}
 	/** Required route-id helper shared by get/update/delete. Throws on missing id. */
 	requireIdParam(req) {
@@ -785,48 +1052,26 @@ var BaseCrudController = class {
 	* or `null` — every truthy non-null shape collapses to `true`.
 	*/
 	isExistsTruthy(result) {
-		return result !== null && result !== false && result !== void 0;
+		return isExistsResultTruthy(result);
+	}
+	/** Assemble the per-request hook context from the protected accessors. */
+	hookOpContext(req) {
+		return {
+			hooks: this.getHooks(req),
+			resourceName: this.resourceName,
+			arcContext: this.meta(req),
+			user: req.user
+		};
 	}
 	/**
 	* 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).
+	* before-hook fails. Full contract on `executeHookedOp` in
+	* `crud/requestPipeline.ts`.
 	*/
 	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;
+		return executeHookedOp(this.hookOpContext(req), args, executor);
 	}
 	/**
 	* Run `executeAfter` for the given op + data. No-op when hooks aren't
@@ -835,15 +1080,7 @@ var BaseCrudController = class {
 	* 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 } : {}
-		});
+		return executeAfterHook(this.hookOpContext(req), op, data, meta);
 	}
 	/** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
 	async withListCache(req, options) {
@@ -908,25 +1145,23 @@ var BaseCrudController = class {
 	* 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()`
+	* 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.
+	* back to a full table scan. Matching + repo invocation live in
+	* `crud/resourceVerbs.ts`.
 	*/
 	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;
+		const verb = matchResourceVerb(req.query);
+		if (!verb) return null;
+		if (verb.kind === "count") return this.dispatchCount(req);
+		if (verb.kind === "distinct") return this.dispatchDistinct(req, verb.field);
+		return this.dispatchExists(req);
 	}
 	/** Resolve filter + tenant/audit options for a dispatch verb. */
 	resolveDispatchScope(req) {
@@ -935,33 +1170,24 @@ var BaseCrudController = class {
 			options: this.tenantRepoOptions(req)
 		};
 	}
-	/** `?_count=true` → `repo.count(filter)` */
+	/** `?_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) },
+			data: await runCountVerb(this.repository, () => this.resolveDispatchScope(req)),
 			status: 200
 		};
 	}
-	/** `?_distinct=field` → `repo.distinct(field, filter)` */
+	/** `?_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),
+			data: await runDistinctVerb(this.repository, field, () => this.resolveDispatchScope(req)),
 			status: 200
 		};
 	}
-	/** `?_exists=true` → `repo.exists(filter)` */
+	/** `?_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);
+		const result = await runExistsVerb(this.repository, () => this.resolveDispatchScope(req));
 		return {
 			data: { exists: this.isExistsTruthy(result) },
 			status: 200
@@ -1109,45 +1335,6 @@ var BaseCrudController = class {
 	}
 };
 //#endregion
-//#region src/utils/repoFeature.ts
-/**
-* Repository feature-detection helper for arc mixins.
-*
-* Arc's `RepositoryLike` is the minimum contract every adapter
-* implements (`getById`, `getOne`, `create`, `update`, `delete`,
-* `find`). Beyond that, kits MAY expose specialized methods —
-* `createMany`, `updateMany`, `deleteMany`, `getTree`, `getBySlug`,
-* `getDeleted`, `restore`, etc. — that arc mixins detect at call
-* time and surface as 501 when missing.
-*
-* Every mixin used to spell out its own narrowing cast inline:
-*
-* ```ts
-* const repo = this.repository as unknown as {
-*   getTree?: (options?: unknown) => Promise<AnyRecord[]>;
-* };
-* ```
-*
-* Centralizing the cast keeps every feature-detection site reading
-* the same shape. The helper does not intersect with `RepositoryLike`
-* on purpose: some standard methods (`createMany`, `updateMany`) live
-* on `StandardRepo` with kit-generic signatures, and intersecting
-* would force the caller's narrowed signature to merge with the wider
-* default, producing mismatched return types. Declare every method
-* you need (base or feature) in `TFeatures`.
-*
-* @example
-* ```ts
-* const repo = withRepoFeatures<{
-*   createMany?: (items: unknown[], options?: unknown) => Promise<AnyRecord[]>;
-* }>(this.repository);
-* if (!repo.createMany) throw createError(501, "...");
-* ```
-*/
-function withRepoFeatures(repo) {
-	return repo;
-}
-//#endregion
 //#region src/core/mixins/bulk.ts
 /**
 * BulkMixin — `bulkCreate` / `bulkUpdate` / `bulkDelete` endpoints.
@@ -1489,4 +1676,4 @@ function TreeMixin(Base) {
 */
 var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { BulkMixin as a, collectReadBlockedFields as c, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, AccessControl as u };
+export { BulkMixin as a, collectReadBlockedFields as c, DEFAULT_FIELD_WRITE_DENIAL_POLICY as d, AccessControl as f, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, BodySanitizer as u };