@classytic/arc 2.10.8 → 2.11.0

package/dist/{BaseController-DVNKvoX4.mjs → BaseController-JNV08qOT.mjs}

@@ -1,12 +1,11 @@
 import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-BhY1OHoH.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 { r as simpleEqualityMatcher, t as ArcQueryParser } from "./queryParser-NR__Qiju.mjs";
-import { t as buildQueryKey } from "./keys-nWQGUTu1.mjs";
-import { n as getUserId } from "./types-CDnTEpga.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CTMWOUDt.mjs";
-import { t as getUserRoles } from "./types-D57iXYb8.mjs";
-import { r as ForbiddenError } from "./errors-BqdUDja_.mjs";
+import { M as simpleEqualityMatcher, j as getUserId, k as ArcQueryParser } from "./utils-D3Yxnrwr.mjs";
+import { t as buildQueryKey } from "./keys-CARyUjiR.mjs";
+import { M as applyFieldWritePermissions, P as resolveEffectiveRoles } from "./permissions-B4vU9L0Q.mjs";
+import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
+import { r as ForbiddenError } from "./errors-D5c-5BJL.mjs";
 //#region src/core/AccessControl.ts
 const log = arcLog("access-control");
 var AccessControl = class {
@@ -415,24 +414,23 @@ var QueryResolver = class {
 	}
 };
 //#endregion
-//#region src/core/BaseController.ts
+//#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. Fall
-* back to queueMicrotask (universal) when setImmediate is absent.
+* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
 */
 const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
 /**
-* Framework-agnostic base controller implementing IController.
+* Framework-agnostic CRUD controller implementing IController.
 *
-* Composes AccessControl, BodySanitizer, and QueryResolver for clean
-* separation of concerns. CRUD methods delegate directly to these
-* composed classes — no intermediate wrapper methods.
+* Composes AccessControl, BodySanitizer, and QueryResolver. All shared
+* state and helpers are `protected` so the preset mixins (SoftDelete,
+* Tree, Slug, Bulk) can extend cleanly.
 *
-* @template TDoc - The document type
-* @template TRepository - The repository type (defaults to RepositoryLike)
+* @template TDoc - The document type.
+* @template TRepository - The repository type (defaults to RepositoryLike).
 */
-var BaseController = class {
+var BaseCrudController = class {
 	repository;
 	schemaOptions;
 	queryParser;
@@ -447,7 +445,14 @@ var BaseController = class {
 	accessControl;
 	/** Composable body sanitization (field permissions, system fields) */
 	bodySanitizer;
-	/** Composable query resolution (parsing, pagination, sort, select/populate) */
+	/**
+	* Composable query resolution (parsing, pagination, sort, select/populate).
+	*
+	* 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`.
+	*/
 	queryResolver;
 	_matchesFilter;
 	_presetFields = {};
@@ -489,11 +494,33 @@ var BaseController = class {
 		this.delete = this.delete.bind(this);
 	}
 	/**
-	* Get the tenant field name if multi-tenant scoping is enabled.
-	* Returns `undefined` when `tenantField` is `false` (platform-universal mode).
+	* Swap the controller's query parser. Rebuilds the internal `QueryResolver`
+	* with the new parser while preserving every other config.
 	*
-	* Use this in subclass overrides instead of accessing `this.tenantField` directly
-	* to avoid TypeScript indexing errors with `string | false`.
+	* 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.
+	*/
+	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
+		});
+	}
+	/**
+	* Get the tenant field name if multi-tenant scoping is enabled.
+	* Returns `undefined` when `tenantField` is `false`.
 	*/
 	getTenantField() {
 		return this.tenantField || void 0;
@@ -501,31 +528,15 @@ var BaseController = class {
 	/**
 	* Build top-level tenant options to thread into the repository call.
 	*
-	* **Why this exists:** repo plugins (e.g. `@classytic/mongokit`'s
-	* `multiTenantPlugin`) read tenant scope from the TOP of the repository
-	* operation context — `context.organizationId`, not `context.data.organizationId`
-	* or `context.context.organizationId`. Without this stamping, a tenant-scoped
-	* repository throws `Missing 'organizationId' in context for '<op>'` even
-	* though arc already injected the tenant into the request body.
-	*
-	* **What this returns:**
-	* - `{ [tenantField]: orgId }` when the resource is tenant-scoped and the
-	*   caller's scope carries an org ID (member, service key bound to an org,
-	*   elevated admin impersonating an org).
-	* - `{}` otherwise — platform-universal resources (`tenantField: false`),
-	*   public/anonymous reads, elevated admins without an org target.
-	*
-	* **Call sites:** every `this.repository.*` CRUD entry — `create`, `update`,
-	* `delete`, `getAll` (via list), plus merged into `QueryOptions` for the
-	* access-controlled read path (`accessControl.fetchDetailed` → `getById`/`getOne`).
-	*
-	* **Name of the field:** uses the instance's own `tenantField` configuration
-	* (default `organizationId`). Matches mongokit's `multiTenantPlugin` default
-	* `contextKey` so host apps don't need to override either side.
+	* 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.
 	*
-	* Multi-field tenancy (via `multiTenantPreset({ tenantFields: [...] })`)
-	* resolves additional fields at middleware time and stashes them on
-	* `_tenantFields` — {@link tenantRepoOptions} merges those in too.
+	* Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
+	* requests, `{}` otherwise. Merges multi-field tenancy from
+	* `_tenantFields` (populated by `multiTenantPreset`).
 	*/
 	tenantRepoOptions(req) {
 		const out = {};
@@ -549,20 +560,15 @@ var BaseController = class {
 		return this.meta(req)?.arc?.hooks ?? null;
 	}
 	/**
-	* Resolve the repository primary key for mutation calls (update/delete/restore).
+	* Resolve the repository primary key for mutation calls.
 	*
-	* When the resource declares a custom `idField` (e.g. `slug`, `jobId`, UUID),
-	* the default behavior is to translate the route id → the fetched doc's `_id`
-	* because most Mongo repositories key their mutation methods off `_id`.
+	* 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 repository itself exposes a matching `idField` property
-	* (e.g. MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
-	* repository already knows how to look up by that field — so we pass the
-	* route id through unchanged and skip the translation.
-	*
-	* This makes `defineResource({ idField: 'id' })` work end-to-end with repos
-	* that natively support custom primary keys, without breaking the slug-style
-	* aliasing that Arc 2.6.3 introduced for repos keyed on `_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.
 	*/
 	resolveRepoId(id, existing) {
 		if (this.idField === "_id") return id;
@@ -574,11 +580,8 @@ var BaseController = class {
 	/**
 	* Centralized 404 response builder. Maps the denial reason from
 	* `fetchDetailed()` into a structured `details.code` so consumers can
-	* programmatically distinguish "doc doesn't exist" from "doc filtered
-	* by policy/org scope" without parsing error strings.
-	*
-	* Error messages are intentionally vague in the `error` field (don't
-	* leak whether the doc exists) — the detail is in `details.code` only.
+	* distinguish "doc doesn't exist" from "doc filtered by policy/org scope"
+	* without parsing error strings.
 	*/
 	notFoundResponse(reason = "NOT_FOUND") {
 		const code = reason ?? "NOT_FOUND";
@@ -606,8 +609,8 @@ var BaseController = class {
 	}
 	/**
 	* Extract user/org IDs from request for cache key scoping.
-	* Only includes orgId when this resource uses tenant-scoped data (tenantField is set).
-	* Universal resources (tenantField: false) get shared cache keys to avoid fragmentation.
+	* Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
+	* Universal resources (tenantField: false) get shared cache keys.
 	*/
 	cacheScope(req) {
 		return {
@@ -947,407 +950,442 @@ var BaseController = class {
 			status: 200
 		};
 	}
-	async getBySlug(req) {
-		const slugField = this._presetFields.slugField ?? "slug";
-		const slug = req.params[slugField] ?? req.params.slug;
-		const options = {
-			...this.queryResolver.resolve(req, this.meta(req)),
-			...this.tenantRepoOptions(req)
-		};
-		const repo = this.repository;
-		let item = null;
-		if (repo.getBySlug) item = await repo.getBySlug(slug, options);
-		else if (repo.getOne) {
-			const filter = {
-				[slugField]: slug,
-				...options?.filter ?? {}
+};
+//#endregion
+//#region src/core/mixins/bulk.ts
+/**
+* BulkMixin — `bulkCreate` / `bulkUpdate` / `bulkDelete` endpoints.
+*
+* Security-critical: every bulk operation routes through the same write
+* permissions, tenant scope, and policy filters as the single-doc paths.
+* Cross-tenant writes are blocked at the controller layer regardless of
+* what middleware the host has wired up.
+*
+* Per-doc lifecycle hooks (`before:create` / `after:create` / etc.) do
+* NOT fire for bulk operations — use the single-doc path if you need
+* them, or subscribe to the bulk lifecycle event from the events plugin.
+*
+* @example
+* ```ts
+* class OrderController extends BulkMixin(BaseCrudController<Order>) {}
+* ```
+*/
+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
 			};
-			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");
-		return {
-			success: true,
-			data: item,
-			status: 200
-		};
-	}
-	async getDeleted(req) {
-		const repo = this.repository;
-		if (!repo.getDeleted) return {
-			success: false,
-			error: "Soft delete not implemented",
-			status: 501
-		};
-		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
-		};
-		const id = req.params.id;
-		if (!id) return {
-			success: false,
-			error: "ID parameter is required",
-			status: 400
-		};
-		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
-		};
-		const arcContext = this.meta(req);
-		const user = req.user;
-		const repoId = this.resolveRepoId(id, existing);
-		const hooks = this.getHooks(req);
-		if (hooks && this.resourceName) try {
-			await hooks.executeBefore(this.resourceName, "restore", existing, {
-				user,
-				context: arcContext,
-				meta: { id }
-			});
-		} catch (err) {
-			return {
+			const rawItems = req.body?.items;
+			if (!Array.isArray(rawItems) || rawItems.length === 0) return {
 				success: false,
-				error: "Hook execution failed",
-				details: {
-					code: "BEFORE_RESTORE_HOOK_ERROR",
-					message: err.message
-				},
+				error: "Bulk create requires a non-empty items array",
 				status: 400
 			};
-		}
-		const repoRestore = () => repo.restore(repoId);
-		let item;
-		if (hooks && this.resourceName) item = await hooks.executeAround(this.resourceName, "restore", existing, repoRestore, {
-			user,
-			context: arcContext,
-			meta: { id }
-		});
-		else item = await repoRestore();
-		if (!item) return this.notFoundResponse("NOT_FOUND");
-		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" }
-		};
-	}
-	async getTree(req) {
-		const repo = this.repository;
-		if (!repo.getTree) return {
-			success: false,
-			error: "Tree structure not implemented",
-			status: 501
-		};
-		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
-		};
-		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
-		};
-	}
-	async bulkCreate(req) {
-		const repo = this.repository;
-		if (!repo.createMany) return {
-			success: false,
-			error: "Repository does not support createMany",
-			status: 501
-		};
-		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
-		};
-		const items = rawItems;
-		const arcContext = this.meta(req);
-		const user = req.user;
-		const sanitizedItems = items.map((item) => this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext));
-		let scopedItems = sanitizedItems;
-		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 (!isElevated(scope)) {
-					const orgId = getOrgId(scope);
-					if (!orgId) return {
+			const items = rawItems;
+			const arcContext = this.meta(req);
+			const user = req.user;
+			const sanitizedItems = items.map((item) => this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext));
+			let scopedItems = sanitizedItems;
+			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
 					};
-					const tenantField = this.tenantField;
-					scopedItems = sanitizedItems.map((item) => ({
-						...item,
-						[tenantField]: orgId
-					}));
+					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
+						};
+						const tenantField = this.tenantField;
+						scopedItems = sanitizedItems.map((item) => ({
+							...item,
+							[tenantField]: orgId
+						}));
+					}
 				}
 			}
-		}
-		const created = await repo.createMany(scopedItems, {
-			user,
-			context: arcContext
-		});
-		const requested = items.length;
-		const inserted = created.length;
-		const skipped = requested - inserted;
-		return {
-			success: true,
-			data: created,
-			status: skipped === 0 ? 201 : inserted === 0 ? 422 : 207,
-			meta: {
-				count: inserted,
-				requested,
-				inserted,
-				skipped,
-				...skipped > 0 && {
-					partial: true,
-					reason: inserted === 0 ? "all_invalid" : "some_invalid"
+			const created = await repo.createMany(scopedItems, {
+				user,
+				context: arcContext
+			});
+			const requested = items.length;
+			const inserted = created.length;
+			const skipped = requested - inserted;
+			return {
+				success: true,
+				data: created,
+				status: skipped === 0 ? 201 : inserted === 0 ? 422 : 207,
+				meta: {
+					count: inserted,
+					requested,
+					inserted,
+					skipped,
+					...skipped > 0 && {
+						partial: true,
+						reason: inserted === 0 ? "all_invalid" : "some_invalid"
+					}
 				}
+			};
+		}
+		/**
+		* Build a tenant-scoped filter for bulk update/delete.
+		*
+		* Mirrors `AccessControl.buildIdFilter` semantics:
+		*   - Always merge `_policyFilters` (from permission middleware)
+		*   - `member` scope on a tenant resource → add org filter
+		*   - `elevated` scope → no org filter (admin cross-org operation)
+		*   - `public` scope on a tenant resource → deny
+		*   - No scope at all (unit tests) → leave filter unchanged
+		*
+		* Returns the merged filter, or `null` when access must be denied.
+		*/
+		buildBulkFilter(userFilter, req) {
+			const filter = { ...userFilter };
+			const arcContext = this.meta(req);
+			const policyFilters = arcContext?._policyFilters;
+			if (policyFilters) Object.assign(filter, policyFilters);
+			if (this.tenantField) {
+				const scope = arcContext?._scope;
+				if (!scope) return filter;
+				if (scope.kind === "public") return null;
+				if (isElevated(scope)) return filter;
+				const orgId = getOrgId(scope);
+				if (!orgId) return null;
+				filter[this.tenantField] = orgId;
 			}
-		};
-	}
-	/**
-	* Build a tenant-scoped filter for bulk update/delete.
-	*
-	* Mirrors `AccessControl.buildIdFilter` semantics for single-doc ops:
-	*   - Always merge `_policyFilters` (from permission middleware)
-	*   - When `tenantField` is set AND a `member` scope is present, add the
-	*     org filter so cross-tenant data can't be touched.
-	*   - When the scope is `elevated` (platform admin), no org filter is
-	*     applied — admins can bulk-update across orgs intentionally.
-	*   - When the scope is `public` on a tenant-scoped resource, deny.
-	*   - When NO scope is present at all (e.g., direct controller calls in
-	*     unit tests, or app routes without auth middleware), the controller
-	*     stays lenient — it's the middleware layer's job to fail-close.
-	*     Apps that want fail-close on bulk routes should run the multi-tenant
-	*     preset middleware (or equivalent) ahead of these handlers.
-	*
-	* Returns the merged filter, or `null` when access must be denied.
-	*/
-	buildBulkFilter(userFilter, req) {
-		const filter = { ...userFilter };
-		const arcContext = this.meta(req);
-		const policyFilters = arcContext?._policyFilters;
-		if (policyFilters) Object.assign(filter, policyFilters);
-		if (this.tenantField) {
-			const scope = arcContext?._scope;
-			if (!scope) return filter;
-			if (scope.kind === "public") return null;
-			if (isElevated(scope)) return filter;
-			const orgId = getOrgId(scope);
-			if (!orgId) return null;
-			filter[this.tenantField] = orgId;
+			return filter;
 		}
-		return filter;
-	}
-	/**
-	* Sanitize a bulk update data payload through the same write-permission
-	* pipeline as single-doc update(). Handles both shapes:
-	*
-	*   - Flat:           `{ name: 'x', status: 'y' }`
-	*   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 }, $unset: { tag: '' } }`
-	*
-	* For each operand, runs `bodySanitizer.sanitize('update', ...)` so that
-	* system fields, systemManaged/readonly/immutable rules, AND field-level
-	* write permissions are enforced. Without this, a tenant-scoped user could
-	* pass `{ $set: { organizationId: 'org-b' } }` to move records across orgs.
-	*
-	* Returns the sanitized payload along with the list of stripped fields for
-	* audit/error reporting.
-	*/
-	sanitizeBulkUpdateData(data, req, arcContext) {
-		const stripped = /* @__PURE__ */ new Set();
-		const keys = Object.keys(data);
-		const operatorKeys = keys.filter((k) => k.startsWith("$"));
-		const flatKeys = keys.filter((k) => !k.startsWith("$"));
-		const isOperatorShape = operatorKeys.length > 0;
-		if (isOperatorShape && flatKeys.length > 0) return {
-			sanitized: {},
-			stripped: [],
-			mixedShape: true
-		};
-		if (!isOperatorShape) {
-			const before = new Set(Object.keys(data));
-			const sanitized = this.bodySanitizer.sanitize(data, "update", req, arcContext);
-			for (const key of before) if (!(key in sanitized)) stripped.add(key);
+		/**
+		* Sanitize a bulk update data payload through the same write-permission
+		* pipeline as single-doc update. Handles both shapes:
+		*   - Flat:           `{ name: 'x', status: 'y' }`
+		*   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 } }`
+		*
+		* Mixed shapes (operator + flat keys) are rejected — mongo silently
+		* drops the flat keys in operator mode, which is a footgun.
+		*/
+		sanitizeBulkUpdateData(data, req, arcContext) {
+			const stripped = /* @__PURE__ */ new Set();
+			const keys = Object.keys(data);
+			const operatorKeys = keys.filter((k) => k.startsWith("$"));
+			const flatKeys = keys.filter((k) => !k.startsWith("$"));
+			const isOperatorShape = operatorKeys.length > 0;
+			if (isOperatorShape && flatKeys.length > 0) return {
+				sanitized: {},
+				stripped: [],
+				mixedShape: true
+			};
+			if (!isOperatorShape) {
+				const before = new Set(Object.keys(data));
+				const sanitized = this.bodySanitizer.sanitize(data, "update", req, arcContext);
+				for (const key of before) if (!(key in sanitized)) stripped.add(key);
+				return {
+					sanitized,
+					stripped: [...stripped],
+					mixedShape: false
+				};
+			}
+			const sanitized = {};
+			for (const [op, operand] of Object.entries(data)) {
+				if (!op.startsWith("$") || operand === null || typeof operand !== "object") {
+					sanitized[op] = operand;
+					continue;
+				}
+				const operandObj = operand;
+				const before = new Set(Object.keys(operandObj));
+				const sanitizedOperand = this.bodySanitizer.sanitize(operandObj, "update", req, arcContext);
+				for (const key of before) if (!(key in sanitizedOperand)) stripped.add(key);
+				if (Object.keys(sanitizedOperand).length > 0) sanitized[op] = sanitizedOperand;
+			}
 			return {
 				sanitized,
 				stripped: [...stripped],
 				mixedShape: false
 			};
 		}
-		const sanitized = {};
-		for (const [op, operand] of Object.entries(data)) {
-			if (!op.startsWith("$") || operand === null || typeof operand !== "object") {
-				sanitized[op] = operand;
-				continue;
-			}
-			const operandObj = operand;
-			const before = new Set(Object.keys(operandObj));
-			const sanitizedOperand = this.bodySanitizer.sanitize(operandObj, "update", req, arcContext);
-			for (const key of before) if (!(key in sanitizedOperand)) stripped.add(key);
-			if (Object.keys(sanitizedOperand).length > 0) sanitized[op] = sanitizedOperand;
+		async bulkUpdate(req) {
+			const repo = this.repository;
+			if (!repo.updateMany) return {
+				success: false,
+				error: "Repository does not support updateMany",
+				status: 501
+			};
+			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
+			};
+			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
+			};
+			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
+			};
+			return {
+				success: true,
+				data: await repo.updateMany(scopedFilter, sanitized, {
+					user,
+					context: arcContext
+				}),
+				status: 200,
+				...stripped.length > 0 && { meta: { stripped } }
+			};
 		}
-		return {
-			sanitized,
-			stripped: [...stripped],
-			mixedShape: false
-		};
-	}
-	async bulkUpdate(req) {
-		const repo = this.repository;
-		if (!repo.updateMany) return {
-			success: false,
-			error: "Repository does not support updateMany",
-			status: 501
-		};
-		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
-		};
-		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
-		};
-		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
-		};
-		return {
-			success: true,
-			data: await repo.updateMany(scopedFilter, sanitized, {
-				user,
+		/**
+		* Bulk delete by `filter` or `ids`.
+		*
+		* Body shape (one of):
+		*   - `{ filter: { status: 'archived' } }` — delete by query filter
+		*   - `{ ids: ['id1', 'id2', 'id3'] }`     — delete specific docs by id
+		*
+		* The `ids` form translates to `{ [idField]: { $in: ids } }` using the
+		* resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
+		* UUID). Tenant scope and policy filters are merged in either way.
+		*
+		* Both forms perform a single `repo.deleteMany()` DB call — no per-doc
+		* fetch loop. Per-doc lifecycle hooks do NOT fire.
+		*/
+		async bulkDelete(req) {
+			const repo = this.repository;
+			if (!repo.deleteMany) return {
+				success: false,
+				error: "Repository does not support deleteMany",
+				status: 501
+			};
+			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
+				};
+				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
+			};
+			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
+			};
+			const hardHint = req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard";
+			const arcContext = this.meta(req);
+			const options = {
+				user: req.user,
 				context: arcContext
-			}),
-			status: 200,
-			...stripped.length > 0 && { meta: { stripped } }
-		};
-	}
-	/**
-	* Bulk delete by `filter` or `ids`.
-	*
-	* Body shape (one of):
-	*   - `{ filter: { status: 'archived' } }`     — delete by query filter
-	*   - `{ ids: ['id1', 'id2', 'id3'] }`         — delete specific docs by id
-	*
-	* The `ids` form translates to `{ [idField]: { $in: ids } }` using the
-	* resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
-	* UUID, etc.). Tenant scope and policy filters are merged in either way,
-	* so cross-tenant deletes are blocked at the controller layer.
-	*
-	* Both forms perform a single `repo.deleteMany()` DB call — no per-doc
-	* fetch loop. Per-doc lifecycle hooks (`before:delete`/`after:delete`) do
-	* NOT fire for bulk operations; use the single-doc `delete()` if you need
-	* them, or subscribe to the bulk lifecycle event from the events plugin.
-	*/
-	async bulkDelete(req) {
-		const repo = this.repository;
-		if (!repo.deleteMany) return {
-			success: false,
-			error: "Repository does not support deleteMany",
-			status: 501
-		};
-		const body = req.body;
-		let userFilter;
-		if (body.ids && body.ids.length > 0) {
-			if (body.filter && Object.keys(body.filter).length > 0) return {
+			};
+			if (hardHint) options.mode = "hard";
+			return {
+				success: true,
+				data: await repo.deleteMany(scopedFilter, options),
+				status: 200
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/mixins/slug.ts
+function SlugMixin(Base) {
+	return class SlugController extends Base {
+		async getBySlug(req) {
+			const slugField = this._presetFields.slugField ?? "slug";
+			const slug = req.params[slugField] ?? req.params.slug;
+			const options = {
+				...this.queryResolver.resolve(req, this.meta(req)),
+				...this.tenantRepoOptions(req)
+			};
+			const repo = this.repository;
+			let item = null;
+			if (repo.getBySlug) item = await repo.getBySlug(slug, options);
+			else if (repo.getOne) {
+				const filter = {
+					[slugField]: slug,
+					...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");
+			return {
+				success: true,
+				data: item,
+				status: 200
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/mixins/softDelete.ts
+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
+			};
+			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: "Bulk delete accepts either `ids` or `filter`, not both",
+				error: "Restore not implemented",
+				status: 501
+			};
+			const id = req.params.id;
+			if (!id) return {
+				success: false,
+				error: "ID parameter is required",
 				status: 400
 			};
-			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
-		};
-		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
-		};
-		const hardHint = req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard";
-		const arcContext = this.meta(req);
-		const options = {
-			user: req.user,
-			context: arcContext
-		};
-		if (hardHint) options.mode = "hard";
-		return {
-			success: true,
-			data: await repo.deleteMany(scopedFilter, options),
-			status: 200
-		};
-	}
-};
+			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
+			};
+			const arcContext = this.meta(req);
+			const user = req.user;
+			const repoId = this.resolveRepoId(id, existing);
+			const hooks = this.getHooks(req);
+			if (hooks && this.resourceName) try {
+				await hooks.executeBefore(this.resourceName, "restore", existing, {
+					user,
+					context: arcContext,
+					meta: { id }
+				});
+			} catch (err) {
+				return {
+					success: false,
+					error: "Hook execution failed",
+					details: {
+						code: "BEFORE_RESTORE_HOOK_ERROR",
+						message: err.message
+					},
+					status: 400
+				};
+			}
+			const repoRestore = () => repo.restore(repoId);
+			let item;
+			if (hooks && this.resourceName) item = await hooks.executeAround(this.resourceName, "restore", existing, repoRestore, {
+				user,
+				context: arcContext,
+				meta: { id }
+			});
+			else item = await repoRestore();
+			if (!item) return this.notFoundResponse("NOT_FOUND");
+			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" }
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/mixins/tree.ts
+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
+			};
+			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
+			};
+			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
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/BaseController.ts
+/**
+* Fully-composed controller: `BaseCrudController` + SoftDelete + Tree +
+* Slug + Bulk. Drop-in replacement for the pre-2.11 god class. The
+* companion interface above gives every method full generic precision
+* on `TDoc` via declaration merging.
+*/
+var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { AccessControl as i, QueryResolver as n, BodySanitizer as r, BaseController as t };
+export { BulkMixin as a, BodySanitizer as c, SlugMixin as i, AccessControl as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t };