@classytic/arc 2.6.3 → 2.7.3

package/dist/plugins/index.mjs

@@ -1,14 +1,15 @@
 import { p as MUTATION_OPERATIONS } from "../constants-Cxde4rpC.mjs";
-import { i as getOrgId } from "../types-BhtYdxZU.mjs";
-import { t as requestContext } from "../requestContext-DYtmNpm5.mjs";
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
-import { t as HookSystem } from "../HookSystem-COkyWztM.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-C6ngvOnn.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-BSXB-Xr7.mjs";
-import { t as errorHandlerPlugin } from "../errorHandler-r2595m8T.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-Csh4nsvv.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-BF7GR7IB.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-BzfeHmhj.mjs";
+import { o as getOrgId } from "../types-AOD8fxIw.mjs";
+import { t as requestContext } from "../requestContext-xHIKedG6.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
+import { t as HookSystem } from "../HookSystem-D7lfx--K.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-DsHiG9cL.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-5DtLwIqb.mjs";
+import { t as errorHandlerPlugin } from "../errorHandler-CH8wk1eD.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-Qnvwc-LQ.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-uDUIYh7u.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-6W0hjVS_.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-CdBbFefk.mjs";
 import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/core/arcCorePlugin.ts
@@ -409,4 +410,4 @@ var requestId_default = fp(requestIdPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };
+export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/response-cache.mjs

@@ -1,4 +1,4 @@
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.d.mts

@@ -1,2 +1,2 @@
-import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-bz_U4EM1.mjs";
+import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-DEqdGkr-.mjs";
 export { type TracingOptions, createSpan, isTracingAvailable, traced, _default as tracingPlugin };

package/dist/plugins/tracing-entry.mjs

@@ -44,7 +44,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.6.3";
+	const resolvedVersion = serviceVersion ?? "2.7.3";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/policies/index.d.mts

@@ -1,4 +1,4 @@
-import { t as PermissionCheck } from "../types-BNUccdcf.mjs";
+import { t as PermissionCheck } from "../types-B4BNthET.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/policies/PolicyInterface.d.ts

package/dist/presets/index.d.mts

@@ -1,5 +1,5 @@
-import { Gt as PaginatedResult, It as IControllerResponse, Lt as IRequestContext, Z as PresetResult, ot as ResourceConfig, u as AnyRecord } from "../interface-DYH8AXGe.mjs";
-import { MultiTenantOptions, multiTenantPreset } from "./multiTenant.mjs";
+import { Gt as PaginatedResult, It as IControllerResponse, Lt as IRequestContext, Z as PresetResult, ot as ResourceConfig, u as AnyRecord } from "../interface-B91alUzq.mjs";
+import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 
 //#region src/presets/ownedByUser.d.ts
 interface OwnedByUserOptions {
@@ -271,4 +271,4 @@ type PresetInput = string | PresetResult | {
  */
 declare function applyPresets<TDoc = AnyRecord>(config: ResourceConfig<TDoc>, presets?: PresetInput[]): ResourceConfig<TDoc>;
 //#endregion
-export { type AuditedPresetOptions, type BulkOperation, type BulkPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, type MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type TreeOptions, applyPresets, auditedPreset, bulkPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };
+export { type AuditedPresetOptions, type BulkOperation, type BulkPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, type MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type TenantFieldSpec, type TreeOptions, applyPresets, auditedPreset, bulkPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/index.mjs

@@ -1,3 +1,3 @@
 import { multiTenantPreset } from "./multiTenant.mjs";
-import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-BMfdy34e.mjs";
+import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-BFrGvvjL.mjs";
 export { applyPresets, auditedPreset, bulkPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/multiTenant.d.mts

@@ -1,9 +1,59 @@
-import { S as CrudRouteKey, Z as PresetResult } from "../interface-DYH8AXGe.mjs";
+import { S as CrudRouteKey, Z as PresetResult } from "../interface-B91alUzq.mjs";
 
 //#region src/presets/multiTenant.d.ts
+/**
+ * One tenant dimension for multi-field filtering. Discriminated by source:
+ * - `type: 'org'`  → reads `getOrgId(scope)`
+ * - `type: 'team'` → reads `getTeamId(scope)`
+ * - `contextKey`   → reads `getScopeContext(scope, contextKey)` (any custom dimension)
+ */
+type TenantFieldSpec = {
+  field: string;
+  type: "org";
+} | {
+  field: string;
+  type: "team";
+} | {
+  field: string;
+  contextKey: string;
+};
 interface MultiTenantOptions {
-  /** Field name in database (default: 'organizationId') */
+  /**
+   * Single-field form: name of the database field to filter by.
+   * Reads `getOrgId(scope)` as the value source.
+   *
+   * Mutually exclusive with `tenantFields` — pass one or the other, not both.
+   *
+   * @default 'organizationId'
+   */
   tenantField?: string;
+  /**
+   * Multi-field form (2.7.1+): list of tenant dimensions to filter by in
+   * lockstep. Use this when a resource is scoped by more than just
+   * organization — e.g. organization + branch, organization + project,
+   * or organization + team + workspace.
+   *
+   * Each entry is a discriminated `TenantFieldSpec` declaring where the
+   * value comes from. Use `type: 'org'` / `type: 'team'` for built-in scope
+   * fields, or `contextKey: '...'` to read from `scope.context` (set by
+   * your auth function).
+   *
+   * Fail-closed: if any required dimension is missing, the request is
+   * rejected. Elevated scopes apply whatever resolves and skip the rest.
+   *
+   * Mutually exclusive with `tenantField`.
+   *
+   * @example
+   * ```typescript
+   * multiTenantPreset({
+   *   tenantFields: [
+   *     { field: 'organizationId', type: 'org' },
+   *     { field: 'branchId',       contextKey: 'branchId' },
+   *   ],
+   * })
+   * ```
+   */
+  tenantFields?: readonly TenantFieldSpec[];
   /**
    * Routes that allow public access (no auth required)
    * When a route is in this array:
@@ -18,4 +68,4 @@ interface MultiTenantOptions {
 }
 declare function multiTenantPreset(options?: MultiTenantOptions): PresetResult;
 //#endregion
-export { MultiTenantOptions, multiTenantPreset };
+export { MultiTenantOptions, TenantFieldSpec, multiTenantPreset };

package/dist/presets/multiTenant.mjs

@@ -1,31 +1,59 @@
-import { o as DEFAULT_TENANT_FIELD } from "../constants-Cxde4rpC.mjs";
-import { d as isElevated, f as isMember, i as getOrgId, n as PUBLIC_SCOPE } from "../types-BhtYdxZU.mjs";
+import "../constants-Cxde4rpC.mjs";
+import { _ as isElevated, c as getRequestScope, f as getTeamId, h as hasOrgAccess, l as getScopeContext, o as getOrgId } from "../types-AOD8fxIw.mjs";
 //#region src/presets/multiTenant.ts
-/** Read request.scope safely */
-function getScope(request) {
-	return request.scope ?? PUBLIC_SCOPE;
+/**
+* Resolve a single TenantFieldSpec against the current scope.
+* Returns `undefined` if the source value isn't present on the scope.
+*/
+function resolveSpec(scope, spec) {
+	if ("contextKey" in spec) return getScopeContext(scope, spec.contextKey);
+	if (spec.type === "org") return getOrgId(scope);
+	if (spec.type === "team") return getTeamId(scope);
+}
+/** Resolve every spec — returns the partial map of fields that have a value. */
+function resolveAll(scope, specs) {
+	const resolved = {};
+	const missing = [];
+	for (const spec of specs) {
+		const value = resolveSpec(scope, spec);
+		if (value !== void 0) resolved[spec.field] = value;
+		else missing.push(spec.field);
+	}
+	return {
+		resolved,
+		missing
+	};
 }
 /**
-* Create tenant filter middleware
-* Adds tenant filter to query for list/get operations.
-* Reads `request.scope` for org context and elevation bypass.
+* Create tenant filter middleware (strict).
+* Walks the configured tenant fields and applies all of them in lockstep.
+* Fails closed if any non-elevated caller is missing a required dimension.
 */
-function createTenantFilter(tenantField) {
+function createTenantFilter(specs) {
 	return async (request, reply) => {
-		const scope = getScope(request);
+		const scope = getRequestScope(request);
 		if (isElevated(scope)) {
-			const orgId = getOrgId(scope);
-			if (orgId) request._policyFilters = {
+			const { resolved } = resolveAll(scope, specs);
+			if (Object.keys(resolved).length > 0) request._policyFilters = {
 				...request._policyFilters ?? {},
-				[tenantField]: orgId
+				...resolved
 			};
 			return;
 		}
-		if (isMember(scope)) {
-			request._policyFilters = {
-				...request._policyFilters ?? {},
-				[tenantField]: scope.organizationId
-			};
+		if (hasOrgAccess(scope)) {
+			const { resolved, missing } = resolveAll(scope, specs);
+			if (missing.length === 0) {
+				request._policyFilters = {
+					...request._policyFilters ?? {},
+					...resolved
+				};
+				return;
+			}
+			reply.code(403).send({
+				success: false,
+				error: "Forbidden",
+				message: `Tenant context incomplete — missing: ${missing.join(", ")}`
+			});
 			return;
 		}
 		if (scope.kind === "public") {
@@ -44,57 +72,71 @@ function createTenantFilter(tenantField) {
 	};
 }
 /**
-* Create flexible tenant filter middleware
-* For routes in allowPublic: only filter when org context is present
-* No org context = allow through (public data)
-* Org context present = require auth and apply filter
+* Create flexible tenant filter middleware (allowPublic).
+* Same policy as the strict variant for authenticated callers, but
+* allows public/unauthenticated requests through without filtering.
 */
-function createFlexibleTenantFilter(tenantField) {
-	return async (request, _reply) => {
-		const scope = getScope(request);
+function createFlexibleTenantFilter(specs) {
+	return async (request, reply) => {
+		const scope = getRequestScope(request);
 		if (isElevated(scope)) {
-			const orgId = getOrgId(scope);
-			if (orgId) request._policyFilters = {
+			const { resolved } = resolveAll(scope, specs);
+			if (Object.keys(resolved).length > 0) request._policyFilters = {
 				...request._policyFilters ?? {},
-				[tenantField]: orgId
+				...resolved
 			};
 			return;
 		}
-		if (isMember(scope)) {
-			request._policyFilters = {
-				...request._policyFilters ?? {},
-				[tenantField]: scope.organizationId
-			};
+		if (hasOrgAccess(scope)) {
+			const { resolved, missing } = resolveAll(scope, specs);
+			if (missing.length === 0) {
+				request._policyFilters = {
+					...request._policyFilters ?? {},
+					...resolved
+				};
+				return;
+			}
+			reply.code(403).send({
+				success: false,
+				error: "Forbidden",
+				message: `Tenant context incomplete — missing: ${missing.join(", ")}`
+			});
 			return;
 		}
 	};
 }
 /**
-* Create tenant injection middleware
-* Injects tenant ID into request body on create.
-* Reads `request.scope` for org context.
+* Create tenant injection middleware.
+* Walks the configured tenant fields and writes each into the request body.
+* Fails closed if any required dimension is missing for non-elevated callers.
 */
-function createTenantInjection(tenantField) {
+function createTenantInjection(specs) {
 	return async (request, reply) => {
-		const scope = getScope(request);
-		const orgId = getOrgId(scope);
-		if (isElevated(scope) && !orgId) return;
-		if (!orgId) {
+		const scope = getRequestScope(request);
+		if (isElevated(scope) && !getOrgId(scope)) return;
+		const { resolved, missing } = resolveAll(scope, specs);
+		if (missing.length > 0) {
 			reply.code(403).send({
 				success: false,
 				error: "Forbidden",
-				message: "Organization context required to create resources"
+				message: `Tenant context incomplete — missing: ${missing.join(", ")}`
 			});
 			return;
 		}
-		if (request.body) request.body[tenantField] = orgId;
+		if (request.body) Object.assign(request.body, resolved);
 	};
 }
 function multiTenantPreset(options = {}) {
-	const { tenantField = DEFAULT_TENANT_FIELD, allowPublic = [] } = options;
-	const strictTenantFilter = createTenantFilter(tenantField);
-	const flexibleTenantFilter = createFlexibleTenantFilter(tenantField);
-	const tenantInjection = createTenantInjection(tenantField);
+	const { tenantField, tenantFields, allowPublic = [] } = options;
+	if (tenantField !== void 0 && tenantFields !== void 0) throw new Error("multiTenantPreset: pass either `tenantField` (single-field) or `tenantFields` (multi-field), not both");
+	const specs = tenantFields ?? [{
+		field: tenantField ?? "organizationId",
+		type: "org"
+	}];
+	if (specs.length === 0) throw new Error("multiTenantPreset: `tenantFields` must contain at least one entry");
+	const strictTenantFilter = createTenantFilter(specs);
+	const flexibleTenantFilter = createFlexibleTenantFilter(specs);
+	const tenantInjection = createTenantInjection(specs);
 	const getFilter = (route) => allowPublic.includes(route) ? flexibleTenantFilter : strictTenantFilter;
 	return {
 		name: "multiTenant",

package/dist/{presets-BMfdy34e.mjs → presets-BFrGvvjL.mjs}

@@ -1,6 +1,6 @@
-import { d as isElevated, n as PUBLIC_SCOPE } from "./types-BhtYdxZU.mjs";
+import { _ as isElevated, n as PUBLIC_SCOPE } from "./types-AOD8fxIw.mjs";
 import { multiTenantPreset } from "./presets/multiTenant.mjs";
-import { d as requireRoles, n as allowPublic, s as requireAuth } from "./permissions-C8ImI8gC.mjs";
+import { f as requireRoles, n as allowPublic, s as requireAuth } from "./permissions-CH4cNwJi.mjs";
 //#region src/presets/ownedByUser.ts
 /**
 * Create ownership check middleware.

package/dist/{queryCachePlugin-DcmETvcB.d.mts → queryCachePlugin-Ckl71mkc.d.mts}

@@ -1,4 +1,4 @@
-import { i as CacheStore } from "./interface-D_BWALyZ.mjs";
+import { i as CacheStore } from "./interface-CG7oRZjX.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/cache/QueryCache.d.ts

package/dist/{queryCachePlugin-XtFplYO9.mjs → queryCachePlugin-CwTpR04-.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { i as versionKey, r as tagVersionKey } from "./keys-qcD-TVJl.mjs";
-import { t as hasEvents } from "./typeGuards-Cj5Rgvlg.mjs";
-import { t as MemoryCacheStore } from "./memory-BFAYkf8H.mjs";
+import { t as hasEvents } from "./typeGuards-CcFZXgU7.mjs";
+import { t as MemoryCacheStore } from "./memory-Cp7_cAko.mjs";
 import fp from "fastify-plugin";
 //#region src/cache/QueryCache.ts
 var QueryCache = class {

package/dist/{redis-D0Qc-9EW.d.mts → redis-3TQxm2VZ.d.mts}

@@ -1,4 +1,4 @@
-import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-gr-7qo9j.mjs";
+import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-CSbZdv_3.mjs";
 
 //#region src/idempotency/stores/redis.d.ts
 interface RedisClient {

package/dist/{redis-stream-BW9UKLZM.d.mts → redis-stream-Dag5LFa9.d.mts}

@@ -1,4 +1,4 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-wc5hSLik.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-C4VheKeC.mjs";
 
 //#region src/events/transports/redis-stream.d.ts
 interface RedisStreamLike {

package/dist/registry/index.d.mts

@@ -1,4 +1,4 @@
-import { Bt as ResourceRegistry, R as IntrospectionPluginOptions, zt as RegisterOptions } from "../interface-DYH8AXGe.mjs";
+import { Bt as ResourceRegistry, R as IntrospectionPluginOptions, zt as RegisterOptions } from "../interface-B91alUzq.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/registry/introspectionPlugin.d.ts

package/dist/registry/index.mjs

@@ -1,3 +1,3 @@
-import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-I-ogLgL9.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-C6ngvOnn.mjs";
+import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-B3lRFBWo.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-DsHiG9cL.mjs";
 export { ResourceRegistry, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };

package/dist/replyHelpers-uDUIYh7u.mjs

@@ -0,0 +1,40 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import fp from "fastify-plugin";
+//#region src/plugins/replyHelpers.ts
+var replyHelpers_exports = /* @__PURE__ */ __exportAll({ replyHelpersPlugin: () => replyHelpersPlugin });
+async function replyHelpersPluginFn(fastify) {
+	fastify.decorateReply("ok", function(data, statusCode = 200) {
+		return this.code(statusCode).send({
+			success: true,
+			data
+		});
+	});
+	fastify.decorateReply("fail", function(error, statusCode = 400) {
+		if (Array.isArray(error)) return this.code(statusCode).send({
+			success: false,
+			errors: error
+		});
+		return this.code(statusCode).send({
+			success: false,
+			error
+		});
+	});
+	fastify.decorateReply("paginated", function(result) {
+		return this.code(200).send({
+			success: true,
+			...result
+		});
+	});
+	fastify.decorateReply("stream", function(source, options) {
+		this.code(options.statusCode ?? 200);
+		this.header("content-type", options.contentType);
+		if (options.filename) this.header("content-disposition", `attachment; filename="${options.filename}"`);
+		return this.send(source);
+	});
+}
+const replyHelpersPlugin = fp(replyHelpersPluginFn, {
+	name: "arc-reply-helpers",
+	fastify: "5.x"
+});
+//#endregion
+export { replyHelpers_exports as n, replyHelpersPlugin as t };

package/dist/{resourceToTools-nCJWnG1r.mjs → resourceToTools-BJkoQoUP.mjs}

@@ -1,5 +1,6 @@
-import { t as BaseController } from "./BaseController-DzRtluEF.mjs";
-import { t as pluralize } from "./pluralize-CcT6qF0a.mjs";
+import { t as BaseController } from "./BaseController-CpMfCXdn.mjs";
+import { n as normalizePermissionResult } from "./applyPermissionResult-D6GPMsvh.mjs";
+import { t as pluralize } from "./pluralize-Dckfq6US.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
@@ -88,7 +89,9 @@ const PAGINATION_SHAPE = {
 	page: z.number().int().min(1).optional().describe("Page number (1-based)"),
 	limit: z.number().int().min(1).max(100).optional().describe("Items per page (max 100)"),
 	sort: z.string().optional().describe("Sort field, prefix with - for descending"),
-	search: z.string().optional().describe("Full-text search query")
+	search: z.string().optional().describe("Full-text search query"),
+	select: z.string().optional().describe("Comma-separated field list to project (e.g. 'name,price'). Prefix with '-' to exclude (e.g. '-description')."),
+	populate: z.string().optional().describe("Comma-separated relation paths to hydrate (e.g. 'supplier,category'). Follows Mongoose populate syntax when the adapter is MongoKit.")
 };
 /**
 * Convert Arc fieldRules to a flat Zod shape.
@@ -179,6 +182,7 @@ function buildListShape(fieldRules, options) {
 		if (allHidden.has(name)) continue;
 		const rule = fieldRules[name];
 		if (!rule) continue;
+		if (rule.hidden || rule.systemManaged) continue;
 		const filterField = buildFieldSchema(rule);
 		shape[name] = filterField.optional();
 		if (allowedOperators?.length) {
@@ -212,11 +216,19 @@ function buildListShape(fieldRules, options) {
 * | create    | {}         | {}                   | all input fields    |
 * | update    | { id }     | {}                   | input minus id      |
 * | delete    | { id }     | {}                   | undefined           |
+*
+* **scopeOverride** — when a permission check (e.g. `requireApiKey()`) returns
+* `PermissionResult.scope`, the MCP tool handler must install it on the request
+* context the same way CRUD/action routes do. This parameter follows the exact
+* same non-downgrade rule as `applyPermissionResult`: it overrides only when
+* the session-derived scope is `public` (i.e. MCP called with `auth: false`).
+* An authenticated session scope is never overwritten.
 */
-function buildRequestContext(input, auth, operation, policyFilters) {
-	const scope = buildScope(auth);
+function buildRequestContext(input, auth, operation, policyFilters, scopeOverride) {
+	const sessionScope = buildScope(auth);
+	const scope = scopeOverride && sessionScope.kind === "public" ? scopeOverride : sessionScope;
 	const base = {
-		user: auth ? {
+		user: auth?.userId ? {
 			id: auth.userId,
 			_id: auth.userId,
 			...auth
@@ -264,7 +276,30 @@ function buildRequestContext(input, auth, operation, policyFilters) {
 		};
 	}
 }
-/** Convert MCP operator keys (`price_gt`) to MongoKit bracket notation (`price[gt]`). */
+/**
+* Convert MCP operator keys (`price_gt`, `location_withinRadius`) to the
+* nested object shape MongoKit's QueryParser expects (`{ price: { gt: ... } }`,
+* `{ location: { withinRadius: ... } }`).
+*
+* **Comparison operators** (price_gt, age_lte, …): coerce filter values via
+* the parser's coercion path.
+*
+* **Set operators** (status_in, role_nin, …): MongoKit accepts both
+* comma-separated strings and arrays.
+*
+* **Existence** (deletedAt_exists): coerced to boolean by the parser.
+*
+* **Geo operators** (location_near, location_withinRadius, location_geoWithin,
+* location_nearSphere): MongoKit 3.5.5+ — values are coordinate strings the
+* parser's geo primitive handles. Without these in the allowlist, MCP agents
+* couldn't pass geo filters at all and Arc would silently leak unfiltered docs.
+*
+* Keep this set in sync with MongoKit's QueryParser operators map (search for
+* `private readonly operators` in QueryParser.ts) plus the geo operators
+* recognized by `isGeoOperator` in primitives/geo.ts. We deliberately list
+* them explicitly here rather than asking the parser at runtime — Arc must
+* not import MongoKit internals just to know what an operator looks like.
+*/
 const OPERATOR_SUFFIXES = new Set([
 	"eq",
 	"ne",
@@ -274,7 +309,16 @@ const OPERATOR_SUFFIXES = new Set([
 	"lte",
 	"in",
 	"nin",
-	"exists"
+	"exists",
+	"size",
+	"type",
+	"like",
+	"contains",
+	"regex",
+	"near",
+	"nearSphere",
+	"withinRadius",
+	"geoWithin"
 ]);
 function expandOperatorKeys(input) {
 	const out = {};
@@ -300,17 +344,23 @@ function expandOperatorKeys(input) {
 }
 function buildScope(auth) {
 	if (!auth) return { kind: "public" };
+	if (auth.clientId && auth.organizationId) return {
+		kind: "service",
+		clientId: auth.clientId,
+		organizationId: auth.organizationId,
+		scopes: auth.scopes
+	};
 	if (auth.organizationId) return {
 		kind: "member",
 		userId: auth.userId,
-		userRoles: [],
+		userRoles: auth.roles ?? [],
 		organizationId: auth.organizationId,
-		orgRoles: []
+		orgRoles: auth.orgRoles ?? []
 	};
 	return {
 		kind: "authenticated",
 		userId: auth.userId,
-		userRoles: []
+		userRoles: auth.roles ?? []
 	};
 }
 //#endregion
@@ -648,15 +698,15 @@ function createHandler(op, controller, resourceName, permissions) {
 				}],
 				isError: true
 			};
-			const policyFilters = await evaluatePermission(permissions?.[op], ctx.session, resourceName, op, input);
-			if (policyFilters === false) return {
+			const permResult = await evaluatePermission(permissions?.[op], ctx.session, resourceName, op, input);
+			if (permResult && !permResult.granted) return {
 				content: [{
 					type: "text",
-					text: `Permission denied: ${op} on ${resourceName}`
+					text: `Permission denied: ${op} on ${resourceName}${permResult.reason ? ` — ${permResult.reason}` : ""}`
 				}],
 				isError: true
 			};
-			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op, policyFilters || void 0)));
+			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op, permResult?.filters, permResult?.scope)));
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			ctx.log("error", `${resourceName}.${op}: ${msg}`).catch(() => {});
@@ -698,10 +748,13 @@ function createAdditionalRouteHandler(route, controller, hasId) {
 /**
 * Evaluate a resource's permission check in MCP context.
 *
-* Returns:
-* - `false` if permission denied
-* - `Record<string, unknown>` if granted with filters (ownership patterns)
-* - `null` if granted without filters (or no permission check defined)
+* Returns the full normalized `PermissionResult` so the caller can honor
+* ALL side-effects (filters + scope) consistently with CRUD/action routes.
+* Returns `null` when no permission is defined (= allow, no side effects).
+*
+* Promoting booleans to `PermissionResult` via the shared `normalizePermissionResult`
+* helper keeps the contract aligned with the rest of Arc — there is a single
+* normalization path for every call site.
 */
 async function evaluatePermission(check, session, resource, action, input) {
 	if (!check) return null;
@@ -710,7 +763,7 @@ async function evaluatePermission(check, session, resource, action, input) {
 		_id: session.userId,
 		...session
 	} : null;
-	const result = await check({
+	return normalizePermissionResult(await check({
 		user,
 		request: {
 			user,
@@ -724,11 +777,7 @@ async function evaluatePermission(check, session, resource, action, input) {
 		resourceId: typeof input.id === "string" ? input.id : void 0,
 		params: {},
 		data: input
-	});
-	if (typeof result === "boolean") return result ? null : false;
-	const permResult = result;
-	if (!permResult.granted) return false;
-	return permResult.filters ?? null;
+	}));
 }
 /**
 * Derive a fieldRules-shaped object from the adapter's auto-generated body

package/dist/rpc/index.d.mts

@@ -1,4 +1,4 @@
-import { r as CircuitBreakerOptions } from "../circuitBreaker-JP2GdJ4b.mjs";
+import { r as CircuitBreakerOptions } from "../circuitBreaker-BBPDt-J_.mjs";
 
 //#region src/rpc/serviceClient.d.ts
 interface RetryConfig {

package/dist/rpc/index.mjs

@@ -1,4 +1,4 @@
-import { t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
+import { t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.mjs";
 //#region src/rpc/serviceClient.ts
 /**
 * Service Client — Resource-Oriented RPC