@classytic/arc 2.9.1 → 2.10.8

package/README.md

@@ -2,7 +2,7 @@
 
 Database-agnostic resource framework for Fastify. Define resources, get CRUD routes, permissions, presets, caching, events, OpenAPI, and MCP tools — without boilerplate.
 
-**v2.9** | Fastify 5+ | Node.js 22+ | ESM only
+**v2.10** | Fastify 5+ | Node.js 22+ | ESM only
 
 ## Install
 
@@ -65,12 +65,14 @@ const app = await createApp({
 Clean DX without growing exclude lists:
 
 ```typescript
-import { Repository } from '@classytic/mongokit';
+import { Repository, methodRegistryPlugin, batchOperationsPlugin } from '@classytic/mongokit';
 
 // app.ts — pass any RepositoryLike (mongokit / prismakit / custom)
 await fastify.register(auditPlugin, {
   autoAudit: { perResource: true },
-  repository: new Repository(AuditModel),  // or omit for in-memory dev
+  // batchOperationsPlugin enables deleteMany, required for purgeOlderThan()
+  repository: new Repository(AuditModel, [methodRegistryPlugin(), batchOperationsPlugin()]),
+  // or omit `repository` for in-memory dev
 });
 
 // order.resource.ts — opt in
@@ -600,7 +602,7 @@ await app.register(eventGatewayPlugin, {
 Functional composition for cross-cutting concerns:
 
 ```typescript
-import { pipe, guard, transform, intercept } from '@classytic/arc';
+import { pipe, guard, transform, intercept } from '@classytic/arc/pipeline';
 
 const isActive = guard('isActive', (ctx) => ctx.query?.filters?.isActive !== false);
 const slugify = transform('slugify', (ctx) => ({ ...ctx, body: { ...ctx.body, slug: toSlug(ctx.body.name) } }));
@@ -737,7 +739,6 @@ Arc sets `"sideEffects": false` in [package.json](package.json), so modern bundl
 | `@classytic/arc/presets` | Preset functions + interfaces |
 | `@classytic/arc/audit` | Audit trail |
 | `@classytic/arc/idempotency` | Idempotency |
-| `@classytic/arc/policies` | Policy engine |
 | `@classytic/arc/schemas` | TypeBox helpers |
 | `@classytic/arc/utils` | Errors, circuit breaker, state machine, query parser |
 | `@classytic/arc/testing` | Test utilities, mocks, in-memory DB |
@@ -750,101 +751,29 @@ Arc sets `"sideEffects": false` in [package.json](package.json), so modern bundl
 | `@classytic/arc/docs` | OpenAPI generation |
 | `@classytic/arc/cli` | CLI commands (programmatic) |
 
-## v2.9.1 Highlights
+## Type imports
 
-`auditPlugin`, `idempotencyPlugin`, and `EventOutbox` take a
-`repository: RepositoryLike` option — pass any `Repository` (mongokit /
-prismakit / your own kit). Arc calls `create` / `getOne` / `findAll` /
-`deleteMany` / `findOneAndUpdate` on it directly:
+Arc owns framework types (`IController`, `IRequestContext`, `ResourceConfig`, `RepositoryLike`, `PaginationResult`). The repository contract lives in `@classytic/repo-core` — import those types directly:
 
 ```typescript
-import { Repository } from '@classytic/mongokit';
-import { auditPlugin } from '@classytic/arc/audit';
-import { idempotencyPlugin } from '@classytic/arc/idempotency';
-import { EventOutbox } from '@classytic/arc/events';
-
-await fastify.register(auditPlugin, { repository: new Repository(AuditModel) });
-await fastify.register(idempotencyPlugin, {
-  repository: new Repository(IdempotencyModel, [
-    methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin(),
-  ]),
-});
-new EventOutbox({ repository: new Repository(OutboxModel), transport });
-```
-
-Memory + Redis stores unchanged via `store` / `customStores`. Requires
-`@classytic/mongokit ≥3.8.0`.
-
-## v2.9 Highlights
-
-**Security defaults (breaking):**
-- **Field-write perms reject by default** — requests with non-writable fields return 403 with denied-field list. Opt into legacy silent-strip via `defineResource({ onFieldWriteDenied: 'strip' })`.
-- **multiTenant preset injects org on UPDATE** — body-supplied `organizationId` is overwritten with caller's scope (prior: CREATE only; a member could hop their own doc to another tenant).
-- **Elevation always emits `arc.scope.elevated`** — privilege elevation can no longer be silently un-audited. Subscribe via `fastify.events.subscribe('arc.scope.elevated', …)`. `onElevation` callback still supported.
-- **`verifySignature` throws on parsed body** — prevents the common `req.body` vs `req.rawBody` footgun that looks like a wrong secret.
-- **Upload `sanitizeFilename` policy** — rejects path separators, NUL, `.`/`..`, >255 chars by default. Flexible: pass `false` / `'*'` / custom function to override.
-- **Idempotency `namespace`** — optional key folded into fingerprint for shared-store deployments (prod + canary on one Redis).
+// Arc framework types
+import type { IRequestContext, RepositoryLike, PaginationResult } from '@classytic/arc';
 
-**Event contract v2 (additive):**
-- `EventMeta` gets `schemaVersion`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `aggregate: { type, id }`
-- `createChildEvent(parent, type, payload)` — auto-chains causation + inherits correlation / userId / organizationId / source / idempotencyKey (aggregate stays explicit)
-- `DeadLetteredEvent<T>` type + optional `transport.deadLetter()` for first-class DLQ
-- `withRetry({ transport })` auto-routes exhausted events to `transport.deadLetter()` — no custom `$deadLetter` plumbing
-- Downstream packages narrow `aggregate.type` to a closed DDD union via interface extension
-
-**Outbox v2 (additive):**
-- `EventOutbox.store()` auto-maps `event.meta.idempotencyKey` → `OutboxWriteOptions.dedupeKey` (caller's explicit `dedupeKey` still wins)
-- `new EventOutbox({ failurePolicy: ({ attempts, error }) => ({ retryAt?, deadLetter? }) })` — centralises retry + DLQ escalation, no more hand-rolled `exponentialBackoff` at every failure site
-- `outbox.getDeadLettered(limit)` returns typed `DeadLetteredEvent[]` — same shape `withRetry` produces, closes the loop between retry DLQ and outbox DLQ state
-- `RelayResult.deadLettered` — per-batch DLQ transition count for dashboards
-- Durable outbox via any `RepositoryLike` — `new EventOutbox({ repository, transport })` (2.9.1); multi-worker claim, TTL purge, dedupe, and session-threaded writes come from the repository's backing kit
-
-**Removed (no replacement kept):**
-- `createActionRouter`, `buildActionBodySchema` — use `defineResource({ actions })`
-- `ResourceConfig.onRegister` — use `actions` or resource `hooks`
-- `PluginResourceResult.additionalRoutes` → `routes: RouteDefinition[]`
-- `PolicyContext` / `PolicyResult` `any` fields → `unknown` (tighten downstream narrowing)
-
-## v2.8.4 Highlights
-
-- **MCP ↔ AI SDK bridge** — expose AI SDK `tool()` definitions over MCP without duplicating code. `bridgeToMcp(bridge)` adapts any AI SDK tool into an MCP tool with automatic auth, guard delegation, and `{ error } → isError` envelope translation. `buildMcpToolsFromBridges(bridges, { include, exclude })` registers a whole catalog at once with per-environment filtering.
-
-```typescript
-import { bridgeToMcp, buildMcpToolsFromBridges, type McpBridge } from '@classytic/arc/mcp';
-
-export const triggerJobBridge: McpBridge = {
-  name: 'trigger_job',
-  description: 'Start a job.',
-  inputSchema: { phase: z.enum(['investigate', 'fix']) },
-  annotations: { destructiveHint: true },
-  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
-};
-
-await app.register(mcpPlugin, {
-  resources,
-  extraTools: buildMcpToolsFromBridges([triggerJobBridge]),
-});
+// Repository contract (repo-core is the single source of truth)
+import type { StandardRepo, WriteOptions, QueryOptions } from '@classytic/repo-core/repository';
+import type { OffsetPaginationResult } from '@classytic/repo-core/pagination';
 ```
 
-## v2.8.1 Highlights
+> Arc 2.10 dropped the legacy `CrudRepository`, `PaginatedResult`, and pass-through `WriteOptions`/`QueryOptions` re-exports. See [CHANGELOG.md](CHANGELOG.md#210) for the migration table.
 
-- **Per-action discriminated validation** — `actions` schemas now enforce required fields via a `oneOf` body schema; missing inputs are rejected at the HTTP layer by AJV (no more silent bypass)
-- **Actions in OpenAPI** — `POST /:id/action` endpoint auto-generated from `ResourceDefinition.actions`, with per-action descriptions and the same discriminated body schema as the runtime router
-- **Route/action metadata preserved** — `mcp: false`, `description`, `annotations` no longer dropped during `routes → additionalRoutes` normalization
-- **Canonical source retained** — `ResourceDefinition.routes` and `ResourceDefinition.actions` now kept as declared, so OpenAPI/MCP/registry can read the original shape
-- **Outbox hardening** — expanded `OutboxStore` contract (`claimPending`, `fail`, write options, dedupe, visibleAt), ownership-mismatch throws, onError reporting, safe multi-worker relay
-- **`slugLookup` fallback** — works with MongoKit's default Repository (no custom `getBySlug` needed)
+## v2.10 Highlights
 
-## v2.8.0 Highlights
+- **Clean-break on repo-core types** — `CrudRepository` / `PaginatedResult` / pass-through repo options removed from arc's public surface. Import `StandardRepo`, `OffsetPaginationResult`, etc. directly from `@classytic/repo-core`. See [CHANGELOG.md](CHANGELOG.md) for the rewrite table.
+- **Outbox bugfix** — `repositoryAsOutboxStore.fail()` now passes `updatePipeline: true` to `findOneAndUpdate`, so retry / DLQ transitions work on mongokit ≥3.10.
+- **Plugin requirements documented** — audit / outbox / idempotency require mongokit's `methodRegistryPlugin` + `batchOperationsPlugin` for `deleteMany`; README snippets + production-ops docs now show the correct chain.
+- **Removed** — `@classytic/arc/policies` (use `permissions/`), `@classytic/arc/rpc`, `@classytic/arc/dynamic` (use `factory/loadResources`).
 
-- **MCP Integration** — expose resources as AI agent tools (stateless by default, service scope, multi-tenancy)
-- **Reply Helpers** — `reply.ok()`, `reply.fail()`, `reply.paginated()`, `reply.stream()` (opt-in)
-- **Error Mappers** — class-based `instanceof` domain error → HTTP response mapping
-- **Multipart Body** — `multipartBody()` middleware for file upload in CRUD routes
-- **Service Scope** — `kind: "service"` RequestScope for machine-to-machine auth (MCP + WebSocket)
-- **BigInt Serialization** — `serializeBigInt: true` auto-converts BigInt → Number
-- **Event WAL** — skips internal `arc.*` events to prevent startup timeout with durable stores
-- **Security** — `auth: false` produces null `ctx.user` (prevents anonymous bypass of `!!ctx.user` guards)
+See [CHANGELOG.md](CHANGELOG.md) for the full v2.9 / v2.8 / v2.7 history.
 
 ## License
 

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

@@ -1,33 +1,26 @@
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-Cxde4rpC.mjs";
+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 { getUserId } from "./types/index.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CU6FlaDV.mjs";
-import { t as getUserRoles } from "./types-ZUu_h0jp.mjs";
-import { r as ForbiddenError } from "./errors-CqWnSqM-.mjs";
-import { t as ArcQueryParser } from "./queryParser-Cs-6SHQK.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";
 //#region src/core/AccessControl.ts
-/**
-* AccessControl - Composable access control logic extracted from BaseController.
-*
-* Handles ID filtering, policy filter checking, org/tenant scope validation,
-* ownership verification, and fetch-with-access-control patterns.
-*
-* Designed to be used standalone or composed into controllers.
-*/
-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;
@@ -48,17 +41,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.
+	*
+	* **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.
 	*
-	* Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
-	* otherwise falls back to built-in MongoDB-style matching.
+	* 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.
@@ -72,7 +102,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);
@@ -130,7 +159,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 {
@@ -191,101 +238,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;
@@ -304,10 +256,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;
@@ -344,6 +299,7 @@ var QueryResolver = class {
 	queryParser;
 	maxLimit;
 	defaultLimit;
+	/** `undefined` means "no default sort" (caller passed `false`). */
 	defaultSort;
 	schemaOptions;
 	tenantField;
@@ -351,7 +307,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;
 	}
@@ -482,6 +438,7 @@ var BaseController = class {
 	queryParser;
 	maxLimit;
 	defaultLimit;
+	/** `undefined` means "no default sort" (caller passed `false`). */
 	defaultSort;
 	resourceName;
 	tenantField;
@@ -501,7 +458,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";
@@ -521,7 +478,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
 		});
@@ -541,6 +498,48 @@ var BaseController = class {
 	getTenantField() {
 		return this.tenantField || void 0;
 	}
+	/**
+	* 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.
+	*
+	* Multi-field tenancy (via `multiTenantPreset({ tenantFields: [...] })`)
+	* resolves additional fields at middleware time and stashes them on
+	* `_tenantFields` — {@link tenantRepoOptions} merges those in too.
+	*/
+	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;
@@ -663,21 +662,15 @@ 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 result = hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "list", options, repoGetAll, {
+		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)
 		}) : await repoGetAll();
-		if (Array.isArray(result)) return {
-			docs: result,
-			page: 1,
-			limit: result.length,
-			total: result.length,
-			pages: 1,
-			hasNext: false,
-			hasPrev: false
-		};
-		return result;
 	}
 	async get(req) {
 		const id = req.params.id;
@@ -686,7 +679,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) {
@@ -782,7 +778,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) {
@@ -814,7 +811,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,
@@ -847,7 +844,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) {
@@ -885,7 +883,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,
@@ -916,6 +914,7 @@ var BaseController = class {
 		const repoDelete = async () => this.repository.delete(repoId, {
 			user,
 			context: arcContext,
+			...this.tenantRepoOptions(req),
 			...deleteMode ? { mode: deleteMode } : {}
 		});
 		let result;
@@ -951,7 +950,10 @@ var BaseController = class {
 	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 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);
@@ -981,27 +983,9 @@ var BaseController = class {
 			status: 501
 		};
 		const parsed = this.queryResolver.resolve(req, this.meta(req));
-		const result = await repo.getDeleted(parsed, parsed);
-		if (Array.isArray(result)) {
-			const docs = result;
-			return {
-				success: true,
-				data: {
-					method: "offset",
-					docs,
-					page: 1,
-					limit: docs.length,
-					total: docs.length,
-					pages: 1,
-					hasNext: false,
-					hasPrev: false
-				},
-				status: 200
-			};
-		}
 		return {
 			success: true,
-			data: result,
+			data: await repo.getDeleted(parsed, parsed),
 			status: 200
 		};
 	}

package/dist/{ResourceRegistry-Dq3_zBQP.mjs → ResourceRegistry-CcN2LVrc.mjs}

@@ -1,4 +1,4 @@
-import { t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
+import { t as CRUD_OPERATIONS } from "./constants-BhY1OHoH.mjs";
 //#region src/registry/ResourceRegistry.ts
 /**
 * Resource Registry

package/dist/actionPermissions-TUVR3uiZ.mjs

@@ -0,0 +1,22 @@
+//#region src/core/actionPermissions.ts
+/**
+* Return the effective `PermissionCheck` for a single action, or `undefined`
+* when the resource declares no gate at any level.
+*
+* Callers decide what "no gate" means:
+*   - HTTP: boot-time throw in `normalizeActionsToRouterConfig`.
+*   - MCP: treated as allow (legacy) — but the HTTP fallback now fills the
+*     gap when `permissions.update` is set, so the MCP hole closes too.
+*   - OpenAPI: docs advertise the endpoint as unauthenticated.
+*/
+function resolveActionPermission(input) {
+	const { action, resourcePermissions, resourceActionPermissions, globalAuth } = input;
+	const explicit = typeof action !== "function" && action.permissions ? action.permissions : void 0;
+	if (explicit) return explicit;
+	if (resourceActionPermissions) return resourceActionPermissions;
+	if (globalAuth) return globalAuth;
+	const updateFallback = resourcePermissions?.update;
+	if (updateFallback) return updateFallback;
+}
+//#endregion
+export { resolveActionPermission as t };