@classytic/arc 2.10.3 → 2.11.0

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

@@ -1,25 +1,25 @@
 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 { t as buildQueryKey } from "./keys-qcD-TVJl.mjs";
-import { n as getUserId } from "./types-Csi3FLfq.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-bxkeltzz.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";
-import { t as ArcQueryParser } from "./queryParser-DBqBB6AC.mjs";
 //#region src/core/AccessControl.ts
-var AccessControl = class AccessControl {
+const log = arcLog("access-control");
+var AccessControl = class {
 	tenantField;
 	idField;
 	_adapterMatchesFilter;
-	/** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
-	*  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
-	static DANGEROUS_REGEX = /(\{[0-9]+,\}[^{]*\{[0-9]+,\})|(\+[^+]*\+)|(\*[^*]*\*)|(\.\*){3,}|\\1/;
-	/** Forbidden paths that could lead to prototype pollution */
-	static FORBIDDEN_PATHS = [
-		"__proto__",
-		"constructor",
-		"prototype"
-	];
+	/**
+	* One-shot latch for the "adapter didn't supply matchesFilter, in-memory
+	* policy-filter re-check is skipped" warning. The primary fetch path
+	* (`getOne(compoundFilter)`) already applied filters at the DB layer;
+	* this warn only fires when `validateItemAccess` runs and the adapter
+	* hasn't provided a native matcher for the post-hoc re-check.
+	*/
+	_warnedNoMatcher = false;
 	constructor(config) {
 		this.tenantField = config.tenantField;
 		this.idField = config.idField;
@@ -40,17 +40,54 @@ var AccessControl = class AccessControl {
 		return filter;
 	}
 	/**
-	* Check if item matches policy filters (for get/update/delete operations)
-	* Validates that fetched item satisfies all policy constraints
+	* Check if a post-fetch item matches the request's `_policyFilters`.
+	*
+	* **When this runs:** only on paths where the primary fetch path did NOT
+	* apply policy filters at the DB layer — notably `validateItemAccess`
+	* (used by `getBySlug` and cache revalidation). The main `fetchDetailed`
+	* path builds a compound filter (`buildIdFilter`) and passes it to
+	* `repository.getOne(compoundFilter)`, so the DB has already enforced
+	* the filter and an in-memory re-check would be redundant.
 	*
-	* Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
-	* otherwise falls back to built-in MongoDB-style matching.
+	* **Evaluation order (fail-closed):**
+	* 1. No `_policyFilters` set → `true` (nothing to enforce).
+	* 2. Adapter supplied `matchesFilter` → delegate to it verbatim. Adapters
+	*    are expected to handle every filter shape the host emits
+	*    (mongokit/sqlitekit evaluate at the DB layer; Prisma/custom engines
+	*    can wrap their own predicate engine).
+	* 3. No adapter matcher → fall back to `simpleEqualityMatcher` — arc's
+	*    built-in flat-key equality helper. This is defense-in-depth for the
+	*    common case: arc's own permission helpers emit flat filters
+	*    (`{userId: …}`, `{organizationId: …}`), which this matcher evaluates
+	*    correctly. Operator-shaped filters (`$in`, `$ne`, `$regex`, `$and`,
+	*    `$or`) are **rejected** (the matcher returns `false`) — fail-closed
+	*    rather than fail-open. A one-shot warn flags the gap so adapter
+	*    authors can wire a richer matcher.
+	*
+	* Arc deliberately does NOT ship a full MongoDB-syntax matcher:
+	* re-implementing Mongo in JS was dead code for mongokit users (the DB
+	* did it) and silently wrong for non-Mongo adapters. The flat-equality
+	* fallback is small (~20 LOC), correct in both dialects, and closes the
+	* previous `getBySlug`-style policy-bypass path.
 	*/
 	checkPolicyFilters(item, req) {
 		const policyFilters = this._meta(req)?._policyFilters;
-		if (!policyFilters) return true;
+		if (!policyFilters || Object.keys(policyFilters).length === 0) return true;
 		if (this._adapterMatchesFilter) return this._adapterMatchesFilter(item, policyFilters);
-		return this.defaultMatchesPolicyFilters(item, policyFilters);
+		if (Object.values(policyFilters).some((v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype && Object.keys(v).some((k) => k.startsWith("$")))) this._warnNoMatcher(policyFilters);
+		return simpleEqualityMatcher(item, policyFilters);
+	}
+	/**
+	* Emit a one-shot warn when policy filters contain operators (`$in`,
+	* `$ne`, `$regex`, etc.) and no `DataAdapter.matchesFilter` is wired —
+	* arc's flat-equality fallback fail-closes on operators, so the host
+	* sees 404s on docs that should match. Latched on `_warnedNoMatcher`
+	* so subsequent requests stay quiet.
+	*/
+	_warnNoMatcher(policyFilters) {
+		if (this._warnedNoMatcher) return;
+		this._warnedNoMatcher = true;
+		log.warn("`_policyFilters` contains operator-shaped entries (e.g. `$in`, `$ne`, `$regex`) but `DataAdapter.matchesFilter` is not set. Arc's flat-equality fallback cannot evaluate operators and will reject these items on non-compound fetches (`validateItemAccess`, `getBySlug`, cache revalidation). Wire up `matchesFilter` on your adapter — use `matchFilter` from `@classytic/repo-core/filter` for IR-based adapters, or your DB's native predicate engine.", { policyFilterKeys: Object.keys(policyFilters) });
 	}
 	/**
 	* Check org/tenant scope for a document — uses configurable tenantField.
@@ -64,7 +101,6 @@ var AccessControl = class AccessControl {
 		const scope = arcContext?._scope;
 		const orgId = scope ? getOrgId(scope) : void 0;
 		if (!item || !orgId) return true;
-		if (scope && isElevated(scope) && !orgId) return true;
 		const itemOrgId = item[this.tenantField];
 		if (!itemOrgId) return false;
 		return String(itemOrgId) === String(orgId);
@@ -122,7 +158,25 @@ var AccessControl = class AccessControl {
 				};
 				if (hasCompoundFilters) {
 					const idOnly = { [this.idField]: id };
-					const rawDoc = await repository.getOne(idOnly);
+					const rawGetOne = repository.getOne.bind(repository);
+					let rawDoc = null;
+					try {
+						rawDoc = await rawGetOne(idOnly);
+					} catch (unscopedErr) {
+						if (translateStatus404(unscopedErr)) return {
+							doc: null,
+							reason: "NOT_FOUND"
+						};
+						try {
+							rawDoc = await rawGetOne(idOnly, queryOptions);
+						} catch (scopedErr) {
+							if (translateStatus404(scopedErr)) return {
+								doc: null,
+								reason: "NOT_FOUND"
+							};
+							throw scopedErr;
+						}
+					}
 					if (rawDoc) {
 						const arcContext = this._meta(req);
 						if (!this.checkOrgScope(rawDoc, arcContext)) return {
@@ -183,101 +237,6 @@ var AccessControl = class AccessControl {
 	_meta(req) {
 		return req.metadata;
 	}
-	/**
-	* Check if a value matches a MongoDB query operator
-	*/
-	matchesOperator(itemValue, operator, filterValue) {
-		const equalsByValue = (a, b) => String(a) === String(b);
-		switch (operator) {
-			case "$eq": return equalsByValue(itemValue, filterValue);
-			case "$ne": return !equalsByValue(itemValue, filterValue);
-			case "$gt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue > filterValue;
-			case "$gte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue >= filterValue;
-			case "$lt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue < filterValue;
-			case "$lte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue <= filterValue;
-			case "$in":
-				if (!Array.isArray(filterValue)) return false;
-				if (Array.isArray(itemValue)) return itemValue.some((v) => filterValue.some((fv) => equalsByValue(v, fv)));
-				return filterValue.some((fv) => equalsByValue(itemValue, fv));
-			case "$nin":
-				if (!Array.isArray(filterValue)) return false;
-				if (Array.isArray(itemValue)) return itemValue.every((v) => filterValue.every((fv) => !equalsByValue(v, fv)));
-				return filterValue.every((fv) => !equalsByValue(itemValue, fv));
-			case "$exists": return filterValue ? itemValue !== void 0 : itemValue === void 0;
-			case "$regex":
-				if (typeof itemValue === "string" && (typeof filterValue === "string" || filterValue instanceof RegExp)) return (typeof filterValue === "string" ? AccessControl.safeRegex(filterValue) : filterValue)?.test(itemValue) ?? false;
-				return false;
-			default: return false;
-		}
-	}
-	/**
-	* Check if item matches a single filter condition
-	* Supports nested paths (e.g., "owner.id", "metadata.status")
-	*/
-	matchesFilter(item, key, filterValue) {
-		const itemValue = key.includes(".") ? this.getNestedValue(item, key) : item[key];
-		if (filterValue && typeof filterValue === "object" && !Array.isArray(filterValue)) {
-			if (Object.keys(filterValue).some((op) => op.startsWith("$"))) {
-				for (const [operator, opValue] of Object.entries(filterValue)) if (!this.matchesOperator(itemValue, operator, opValue)) return false;
-				return true;
-			}
-		}
-		if (Array.isArray(itemValue)) return itemValue.some((v) => String(v) === String(filterValue));
-		return String(itemValue) === String(filterValue);
-	}
-	/**
-	* Built-in MongoDB-style policy filter matching.
-	* Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
-	*/
-	defaultMatchesPolicyFilters(item, policyFilters) {
-		if (policyFilters.$and && Array.isArray(policyFilters.$and)) {
-			if (!policyFilters.$and.every((condition) => {
-				return Object.entries(condition).every(([key, value]) => {
-					return this.matchesFilter(item, key, value);
-				});
-			})) return false;
-		}
-		if (policyFilters.$or && Array.isArray(policyFilters.$or)) {
-			if (!policyFilters.$or.some((condition) => {
-				return Object.entries(condition).every(([key, value]) => {
-					return this.matchesFilter(item, key, value);
-				});
-			})) return false;
-		}
-		for (const [key, value] of Object.entries(policyFilters)) {
-			if (key.startsWith("$")) continue;
-			if (!this.matchesFilter(item, key, value)) return false;
-		}
-		return true;
-	}
-	/**
-	* Get nested value from object using dot notation (e.g., "owner.id")
-	* Security: Validates path against forbidden patterns to prevent prototype pollution
-	*/
-	getNestedValue(obj, path) {
-		if (AccessControl.FORBIDDEN_PATHS.some((p) => path.toLowerCase().includes(p))) return;
-		const keys = path.split(".");
-		let value = obj;
-		for (const key of keys) {
-			if (value == null) return void 0;
-			if (AccessControl.FORBIDDEN_PATHS.includes(key.toLowerCase())) return;
-			value = value[key];
-		}
-		return value;
-	}
-	/**
-	* Create a safe RegExp from a string, guarding against ReDoS.
-	* Returns null if the pattern is invalid or dangerous.
-	*/
-	static safeRegex(pattern) {
-		if (pattern.length > 200) return null;
-		if (AccessControl.DANGEROUS_REGEX.test(pattern)) return null;
-		try {
-			return new RegExp(pattern);
-		} catch {
-			return null;
-		}
-	}
 };
 var BodySanitizer = class {
 	schemaOptions;
@@ -296,10 +255,13 @@ var BodySanitizer = class {
 	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)) {
-			if (rules.systemManaged || rules.readonly) delete sanitized[field];
-			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate)) delete sanitized[field];
+			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;
@@ -336,6 +298,7 @@ var QueryResolver = class {
 	queryParser;
 	maxLimit;
 	defaultLimit;
+	/** `undefined` means "no default sort" (caller passed `false`). */
 	defaultSort;
 	schemaOptions;
 	tenantField;
@@ -343,7 +306,7 @@ var QueryResolver = class {
 		this.queryParser = config.queryParser ?? getDefaultQueryParser();
 		this.maxLimit = config.maxLimit ?? 100;
 		this.defaultLimit = config.defaultLimit ?? 20;
-		this.defaultSort = config.defaultSort ?? "-createdAt";
+		this.defaultSort = config.defaultSort === false ? void 0 : config.defaultSort ?? "-createdAt";
 		this.schemaOptions = config.schemaOptions ?? {};
 		this.tenantField = config.tenantField !== void 0 ? config.tenantField : DEFAULT_TENANT_FIELD;
 	}
@@ -451,29 +414,29 @@ 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;
 	maxLimit;
 	defaultLimit;
+	/** `undefined` means "no default sort" (caller passed `false`). */
 	defaultSort;
 	resourceName;
 	tenantField;
@@ -482,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 = {};
@@ -493,7 +463,7 @@ var BaseController = class {
 		this.queryParser = options.queryParser ?? getDefaultQueryParser();
 		this.maxLimit = options.maxLimit ?? 100;
 		this.defaultLimit = options.defaultLimit ?? 20;
-		this.defaultSort = options.defaultSort ?? "-createdAt";
+		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";
@@ -513,7 +483,7 @@ var BaseController = class {
 			queryParser: this.queryParser,
 			maxLimit: this.maxLimit,
 			defaultLimit: this.defaultLimit,
-			defaultSort: this.defaultSort,
+			defaultSort: options.defaultSort,
 			schemaOptions: this.schemaOptions,
 			tenantField: this.tenantField
 		});
@@ -524,15 +494,63 @@ 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;
 	}
+	/**
+	* Build top-level tenant options to thread into the repository call.
+	*
+	* 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.
+	*
+	* Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
+	* requests, `{}` otherwise. Merges multi-field tenancy from
+	* `_tenantFields` (populated by `multiTenantPreset`).
+	*/
+	tenantRepoOptions(req) {
+		const out = {};
+		if (this.tenantField) {
+			const scope = this.meta(req)?._scope;
+			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;
+		}
+		return out;
+	}
 	/** Extract typed Arc internal metadata from request */
 	meta(req) {
 		return req.metadata;
@@ -542,20 +560,15 @@ var BaseController = class {
 		return this.meta(req)?.arc?.hooks ?? null;
 	}
 	/**
-	* Resolve the repository primary key for mutation calls (update/delete/restore).
-	*
-	* 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`.
+	* Resolve the repository primary key for mutation calls.
 	*
-	* 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.
+	* 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`.
 	*
-	* 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;
@@ -567,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";
@@ -599,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 {
@@ -655,7 +665,11 @@ var BaseController = class {
 	/** Execute list query through hooks (extracted for cache revalidation) */
 	async executeListQuery(options, req) {
 		const hooks = this.getHooks(req);
-		const repoGetAll = async () => this.repository.getAll(options);
+		const getAllParams = {
+			...options,
+			...this.tenantRepoOptions(req)
+		};
+		const repoGetAll = async () => this.repository.getAll(getAllParams);
 		return hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "list", options, repoGetAll, {
 			user: req.user,
 			context: this.meta(req)
@@ -668,7 +682,10 @@ var BaseController = class {
 			error: "ID parameter is required",
 			status: 400
 		};
-		const options = this.queryResolver.resolve(req, this.meta(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) {
@@ -764,7 +781,8 @@ var BaseController = class {
 		}
 		const repoCreate = async () => this.repository.create(processedData, {
 			user,
-			context: arcContext
+			context: arcContext,
+			...this.tenantRepoOptions(req)
 		});
 		let item;
 		if (hooks && this.resourceName) {
@@ -796,7 +814,7 @@ var BaseController = class {
 		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);
+		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,
@@ -829,7 +847,8 @@ var BaseController = class {
 		}
 		const repoUpdate = async () => this.repository.update(repoId, processedData, {
 			user,
-			context: arcContext
+			context: arcContext,
+			...this.tenantRepoOptions(req)
 		});
 		let item;
 		if (hooks && this.resourceName) {
@@ -867,7 +886,7 @@ var BaseController = class {
 		};
 		const arcContext = this.meta(req);
 		const user = req.user;
-		const { doc: existing, reason: deleteReason } = await this.accessControl.fetchDetailed(id, req, this.repository);
+		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,
@@ -898,6 +917,7 @@ var BaseController = class {
 		const repoDelete = async () => this.repository.delete(repoId, {
 			user,
 			context: arcContext,
+			...this.tenantRepoOptions(req),
 			...deleteMode ? { mode: deleteMode } : {}
 		});
 		let result;
@@ -930,404 +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));
-		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: "Bulk delete accepts either `ids` or `filter`, not both",
+				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: "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 };