@classytic/arc 2.15.4 → 2.16.1

package/dist/scope/index.mjs

@@ -1,6 +1,6 @@
-import { C as requireClientId, E as requireUserId, S as isService, T as requireTeamId, _ as hasOrgAccess, a as getDPoPJkt, b as isMember, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserRoles, h as getUserId, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as isAuthenticated, w as requireOrgId, x as isOrgInScope, y as isElevated } from "../types-C_s5moIu.mjs";
+import { C as isService, D as requireUserId, E as requireTeamId, S as isOrgInScope, T as requireOrgId, _ as getUserRoles, a as getDPoPJkt, b as isElevated, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserId, h as getTenantFromRequest, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as hasOrgAccess, w as requireClientId, x as isMember, y as isAuthenticated } from "../types-Bi0r0vjG.mjs";
 import { n as normalizeRoles } from "../types-D57iXYb8.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-DgoeTyfX.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-Dci0AYLT.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;
@@ -76,4 +76,4 @@ function resolveOrgFromHeader(options) {
 	};
 }
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getTenantFromRequest, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };

package/dist/{sse-Bz-5ZeTt.mjs → sse-jh5OqFjR.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-C_s5moIu.mjs";
+import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-Bi0r0vjG.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { V as ResourceDefinition, Wt as AnyRecord } from "../index-BswOSJCE.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-DrBaUwyV.mjs";
+import { Kt as AnyRecord, V as ResourceDefinition } from "../index-DBDgy6Hw.mjs";
+import { d as preloadResourcesAsync, r as CreateAppOptions, u as preloadResources } from "../types-Dw--SyTq.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
@@ -464,29 +464,6 @@ declare function createTestTimer(): {
   reset: () => void;
 };
 //#endregion
-//#region src/testing/preloadResources.d.ts
-/** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
-type EagerGlobResult = Record<string, unknown>;
-/** Lazy glob result: `{ '/path/to/file.ts': () => Promise<unknown> }` */
-type LazyGlobResult = Record<string, () => Promise<unknown>>;
-/**
- * Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
- *
- * Accepts either:
- * - `{ import: 'default' }` form: values are the resource directly
- * - default form: values are the full module — picks first export with `toPlugin()`
- *
- * Throws if any module doesn't yield a valid `ResourceLike`.
- */
-declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
-/**
- * Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
- *
- * Use this when resources depend on prior bootstrap (e.g., engine init) and
- * cannot be evaluated at import time of the preload file.
- */
-declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
-//#endregion
 //#region src/testing/testApp.d.ts
 type DbMode = "in-memory" | {
   uri: string;

package/dist/testing/index.mjs

@@ -1,4 +1,5 @@
-import { t as CRUD_OPERATIONS } from "../constants-Cxde4rpC.mjs";
+import { t as CRUD_OPERATIONS } from "../constants-TrJVIJl0.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-BOXzPhKU.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -415,7 +416,10 @@ async function setupBetterAuthTestApp(input) {
 			user: u
 		};
 	}
-	const creatorRec = signedUp[creators[0].key];
+	const creator = creators[0];
+	if (!creator) throw new Error("[arc-testing] setupBetterAuthTestApp: no `isCreator: true` user supplied");
+	const creatorRec = signedUp[creator.key];
+	if (!creatorRec) throw new Error(`[arc-testing] setupBetterAuthTestApp: creator '${creator.key}' missing from signed-up roster`);
 	const orgRes = await helpers.createOrg(app, creatorRec.token, org);
 	if (orgRes.statusCode >= 400 || !orgRes.orgId) throw new Error(`[arc-testing] setupBetterAuthTestApp: createOrg failed. statusCode=${orgRes.statusCode}, orgId=${orgRes.orgId ? "ok" : "missing"}, body=${JSON.stringify(orgRes.body).slice(0, 300)}`);
 	const orgId = orgRes.orgId;
@@ -423,6 +427,7 @@ async function setupBetterAuthTestApp(input) {
 		if (u.isCreator === true) continue;
 		if (!addMember) continue;
 		const rec = signedUp[u.key];
+		if (!rec) continue;
 		const res = await addMember({
 			app,
 			creatorToken: creatorRec.token,
@@ -486,6 +491,7 @@ function createTestFixtures() {
 		async clear() {
 			for (let i = tracked.length - 1; i >= 0; i--) {
 				const entry = tracked[i];
+				if (!entry) continue;
 				if (entry.destroy) await entry.destroy(entry.record).catch(() => {});
 			}
 			tracked.length = 0;
@@ -541,7 +547,9 @@ var HttpTestHarness = class {
 		this.runValidation();
 	}
 	runCrud() {
-		const { resource, enabledRoutes, updateMethods } = this;
+		const resource = this.resource;
+		const enabledRoutes = this.enabledRoutes;
+		const updateMethods = this.updateMethods;
 		let createdId = null;
 		describe(`${resource.displayName} HTTP CRUD`, () => {
 			afterAll(async () => {
@@ -663,7 +671,9 @@ var HttpTestHarness = class {
 		});
 	}
 	runPermissions() {
-		const { resource, enabledRoutes, updateMethods } = this;
+		const resource = this.resource;
+		const enabledRoutes = this.enabledRoutes;
+		const updateMethods = this.updateMethods;
 		const protectedOps = {
 			list: opRequiresAuth(resource, "list"),
 			get: opRequiresAuth(resource, "get"),
@@ -737,8 +747,8 @@ var HttpTestHarness = class {
 		});
 	}
 	runValidation() {
-		const { resource, enabledRoutes } = this;
-		if (!enabledRoutes.has("create")) return;
+		const resource = this.resource;
+		if (!this.enabledRoutes.has("create")) return;
 		describe(`${resource.displayName} HTTP Validation`, () => {
 			it("POST with invalid payload should be rejected", async () => {
 				const { app, fixtures } = this.getOptions();
@@ -961,50 +971,6 @@ function createTestTimer() {
 	};
 }
 //#endregion
-//#region src/testing/preloadResources.ts
-/**
-* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
-*
-* Accepts either:
-* - `{ import: 'default' }` form: values are the resource directly
-* - default form: values are the full module — picks first export with `toPlugin()`
-*
-* Throws if any module doesn't yield a valid `ResourceLike`.
-*/
-function preloadResources(globResult) {
-	const resources = [];
-	for (const [path, value] of Object.entries(globResult)) {
-		const resource = pickResource(value);
-		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		resources.push(resource);
-	}
-	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-/**
-* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
-*
-* Use this when resources depend on prior bootstrap (e.g., engine init) and
-* cannot be evaluated at import time of the preload file.
-*/
-async function preloadResourcesAsync(globResult) {
-	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
-		const resource = pickResource(await loader());
-		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		return resource;
-	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-function pickResource(value) {
-	if (!value || typeof value !== "object") return void 0;
-	if (typeof value.toPlugin === "function") return value;
-	const mod = value;
-	const candidates = [
-		mod.default,
-		mod.resource,
-		...Object.values(mod)
-	];
-	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
-}
-//#endregion
 //#region src/testing/testApp.ts
 /**
 * createTestApp — test app factory for arc
@@ -1070,7 +1036,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-PFegs47-.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-DdPBtmzp.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/testing/storageContract.d.mts

@@ -1,4 +1,4 @@
-import { t as Storage } from "../storage-Dfzt4VTl.mjs";
+import { t as Storage } from "../storage-HcAgP5Ni.mjs";
 
 //#region src/testing/storageContract.d.ts
 interface StorageContractSetupResult {

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OpenApiSchemas, A as RequestIdOptions, Bt as Authenticator, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as ApiResponse, H as ActionDefinition, Ht as JwtContext, I as MiddlewareHandler, J as CrudRouteKey, Jt as ObjectId, K as ArcFieldRule, Kt as ArcRequest, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Rt as AuthHelpers, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as TokenPair, Vt as AuthenticatorContext, W as ActionHandlerFn, Wt as AnyRecord, X as EventDefinition, Xt as UserOrganization, Y as CrudSchemas, Yt as UserLike, Z as FieldRule, _ as ControllerQueryOptions, _t as IControllerResponse, a as InferAdapterDoc, at as ResourceConfig, b as ParsedQuery, c as TypedController, ct as ResourcePermissions, d as PaginationResult, dt as RouteMethod, et as PresetFunction, f as IntrospectionData, ft as RouteSchemaOptions, g as ArcInternalMetadata, gt as IController, h as ResourceMetadata, ht as FastifyHandler, i as ValidationResult, it as ResourceCacheConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as RouteDefinition, m as RegistryStats, mt as ControllerLike, n as ConfigError, nt as PresetResult, o as InferDocType, on as BaseControllerOptions, ot as ResourceHookContext, p as RegistryEntry, pt as ControllerHandler, q as CrudController, qt as JWTPayload, r as ValidateOptions, rt as RateLimitConfig, s as InferResourceDoc, st as ResourceHooks, t as RouteHandlerMethod, tt as PresetHook, u as TypedResourceConfig, ut as RouteMcpConfig, v as LookupOption, vt as IRequestContext, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, yt as RouteHandler, zt as AuthPluginOptions } from "../index-BswOSJCE.mjs";
-import { i as RequestScope } from "../types-CTYvcwHe.mjs";
-import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-COhcH3fk.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BXOWoGCF.mjs";
-export { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };
+import { $ as OnTenantDeleteConfig, A as RequestIdOptions, Bt as AuthHelpers, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as TokenPair, H as ActionDefinition, Ht as Authenticator, I as MiddlewareHandler, J as CrudRouteKey, Jt as ArcRequest, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as AuthenticatorContext, Vt as AuthPluginOptions, W as ActionHandlerFn, Wt as JwtContext, X as EventDefinition, Xt as ObjectId, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, Zt as UserLike, _ as ControllerQueryOptions, _t as FastifyHandler, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, ct as ResourceHookContext, d as PaginationResult, dt as RouteDefinition, et as OpenApiSchemas, f as IntrospectionData, ft as RouteMcpConfig, g as ArcInternalMetadata, gt as ControllerLike, h as ResourceMetadata, ht as ControllerHandler, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHooks, m as RegistryStats, mt as RouteSchemaOptions, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMethod, q as CrudController, qt as ApiResponse, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourcePermissions, v as LookupOption, vt as IController, w as ServiceContext, x as PopulateOption, xt as RouteHandler, y as OwnershipCheck, yt as IControllerResponse } from "../index-DBDgy6Hw.mjs";
+import { i as RequestScope } from "../types-CfapW2t8.mjs";
+import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-DqZLp5d6.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-DvwtjDwu.mjs";
+export { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/types/storage.d.mts

@@ -1,2 +1,2 @@
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Dfzt4VTl.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-HcAgP5Ni.mjs";
 export { Storage, StorageContext, StorageFile, StorageReadRange, StorageReadResult, StorageUploadInput };

package/dist/{types-BQsjgQzS.d.mts → types-BD0BCdf6.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-BswOSJCE.mjs";
+import { V as ResourceDefinition } from "./index-DBDgy6Hw.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts
@@ -13,10 +13,30 @@ interface ToolAnnotations {
   /** Tool interacts with external systems beyond this server */
   openWorldHint?: boolean;
 }
-/** Context passed to tool handlers at invocation time */
-interface ToolContext {
-  /** Session identity — null in no-auth mode */
-  session: McpAuthResult | null;
+/**
+ * Context passed to tool handlers at invocation time.
+ *
+ * The `TSession` parameter widens `session` to a host-specific shape — pass
+ * an interface that extends `McpAuthResult` (or omits it entirely for fully
+ * custom auth resolvers) to drop the `as any` casts at call sites:
+ *
+ * ```ts
+ * interface MySession extends McpAuthResult {
+ *   userId: string;            // required, not optional
+ *   organizationId: string;
+ *   tenantPlan: 'free' | 'pro';
+ * }
+ *
+ * defineTool<MySession>('upgrade', {
+ *   handler: async (_input, ctx) => {
+ *     ctx.session?.tenantPlan;  // typed, no cast
+ *   },
+ * });
+ * ```
+ */
+interface ToolContext<TSession = McpAuthResult> {
+  /** Session identity — `null` in no-auth mode */
+  session: TSession | null;
   /** Log to MCP client (best-effort, non-blocking) */
   log: (level: "info" | "warning" | "error" | "debug", message: string) => Promise<void>;
   /** Raw MCP SDK extra context (for advanced use) */
@@ -59,8 +79,11 @@ interface CallToolResult {
  *
  * `inputSchema` is a flat Zod shape `{ name: z.string(), age: z.number() }` —
  * the SDK wraps it in z.object() internally. Do NOT pass z.object() here.
+ *
+ * The `TSession` parameter lets hosts widen the session shape on the
+ * handler — same generic the `defineTool()` builder accepts.
  */
-interface ToolDefinition {
+interface ToolDefinition<TSession = McpAuthResult> {
   name: string;
   description: string;
   title?: string;
@@ -69,7 +92,7 @@ interface ToolDefinition {
   /** Flat Zod shape for structured output validation */
   outputSchema?: Record<string, z.ZodTypeAny>;
   annotations?: ToolAnnotations;
-  handler: (input: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
+  handler: (input: Record<string, unknown>, ctx: ToolContext<TSession>) => Promise<CallToolResult>;
 }
 /** Output of definePrompt() — plain data, not yet registered */
 interface PromptDefinition {
@@ -93,12 +116,57 @@ interface PromptResult {
     };
   }>;
 }
+/**
+ * Metadata threaded into a function-form description override so authors
+ * can produce a context-aware description without re-deriving filter /
+ * sort / operator lists from the resource definition by hand.
+ *
+ * Equivalent to the inputs `defaultCrudDescription()` consumes — the
+ * default description is also passed (`defaultDescription`) so authors
+ * can prepend or append to it without duplicating Arc's auto-derived
+ * filterable-fields blurb.
+ */
+interface CrudDescriptionMeta {
+  readonly operation: CrudOperation;
+  /** Resource display name (e.g. `Posts`) — Arc derives this from `defineResource`. */
+  readonly displayName: string;
+  readonly softDelete: boolean;
+  /** Pre-rendered default description Arc would have used. */
+  readonly defaultDescription: string;
+  readonly filterableFields?: readonly string[];
+  readonly allowedOperators?: readonly string[];
+  readonly sortableFields?: readonly string[];
+}
+/**
+ * Override shape for a single CRUD tool description.
+ *
+ * - `string` — replace the default outright.
+ * - Function — receives the auto-rendered default plus the same metadata
+ *   `defaultCrudDescription()` consumes, returns a final string. Use this
+ *   to append context (`'Note: prefer isActive: true'`) without losing
+ *   Arc's auto-derived filterable-fields blurb.
+ */
+type CrudDescriptionOverride = string | ((meta: CrudDescriptionMeta) => string);
 /** Per-resource MCP configuration overrides */
 interface McpResourceConfig {
   /** Which CRUD operations to expose (default: all enabled on the resource) */
   operations?: CrudOperation[];
-  /** Override tool descriptions per operation */
-  descriptions?: Partial<Record<CrudOperation, string>>;
+  /**
+   * Override tool descriptions per operation.
+   *
+   * Each entry is either a plain replacement string OR a function
+   * `(meta) => string` that receives the auto-rendered default plus the
+   * filterable / sortable metadata Arc would have used. Use the function
+   * form to extend the default without losing the auto-derived blurb:
+   *
+   * ```ts
+   * descriptions: {
+   *   list: ({ defaultDescription }) =>
+   *     `${defaultDescription} Sort by createdAt desc for newest first.`,
+   * }
+   * ```
+   */
+  descriptions?: Partial<Record<CrudOperation, CrudDescriptionOverride>>;
   /** Fields to hide from MCP tool schemas (beyond schemaOptions.hiddenFields) */
   hideFields?: string[];
   /** Per-operation tool name overrides: `{ get: 'get_job_by_id' }` */
@@ -168,9 +236,35 @@ interface McpPluginOptions {
   serverVersion?: string;
   /** Instructions for the LLM — guidance on tool usage, constraints */
   instructions?: string;
-  /** Resources to exclude by name (ignored if `include` is set) */
+  /**
+   * Resources to exclude by name (ignored if `expose`/`include` is set).
+   *
+   * Drift-prone for LLM-facing surfaces: a new `defineResource()` is exposed
+   * by default and you have to remember to add it here. Prefer `expose` when
+   * the principle of least authority matters.
+   */
   exclude?: string[];
-  /** Resources to include by name — only these get MCP tools. Takes priority over `exclude`. */
+  /**
+   * Default-deny allowlist — only resources whose names appear here are
+   * surfaced to MCP. New `defineResource()` calls are auto-denied (the
+   * inverse of `exclude`), matching the principle-of-least-authority that
+   * LLM-driven tool surfaces want.
+   *
+   * Mutually exclusive with `include` (a deprecated alias) — passing both
+   * throws at registration. Mutually exclusive with `exclude`: the deny
+   * default would render the exclude list redundant; passing both throws
+   * with a hint to drop `exclude`.
+   *
+   * @example
+   * ```ts
+   * await app.register(mcpPlugin, { resources, expose: ['post'] });
+   * ```
+   */
+  expose?: string[];
+  /**
+   * @deprecated Use `expose` — same default-deny semantics with a clearer
+   * verb. Kept for backwards compatibility with pre-2.15.5 hosts.
+   */
   include?: string[];
   /** Tool name prefix: 'crm' → 'crm_list_products' */
   toolNamePrefix?: string;
@@ -288,4 +382,4 @@ interface CreateMcpServerConfig {
 /** CRUD operation type */
 type CrudOperation = "list" | "get" | "create" | "update" | "delete";
 //#endregion
-export { McpAuthResolver as a, McpResourceConfig as c, SessionEntry as d, ToolAnnotations as f, CrudOperation as i, PromptDefinition as l, ToolDefinition as m, CallToolResult as n, McpAuthResult as o, ToolContext as p, CreateMcpServerConfig as r, McpPluginOptions as s, BetterAuthHandler as t, PromptResult as u };
+export { CrudDescriptionOverride as a, McpAuthResult as c, PromptDefinition as d, PromptResult as f, ToolDefinition as g, ToolContext as h, CrudDescriptionMeta as i, McpPluginOptions as l, ToolAnnotations as m, CallToolResult as n, CrudOperation as o, SessionEntry as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpResourceConfig as u };

package/dist/{types-C_s5moIu.mjs → types-Bi0r0vjG.mjs}

@@ -47,6 +47,58 @@ function getOrgId(scope) {
 	if (scope.kind === "elevated") return scope.organizationId;
 }
 /**
+* Resolve the tenant (organization) id from an incoming Fastify request,
+* walking the canonical sources in order: `request.scope` → `x-organization-id`
+* header. Returns `{ organizationId, source }` so callers can log or branch
+* on which path won.
+*
+* Use in custom handlers that bypass arc's auto-CRUD path (worker routes,
+* batch importers, cross-engine subscribers) and therefore don't get the
+* tenant injected by `BaseCrudController`. Bridges arc's HTTP shape to
+* the mongokit/kit-side tenant context (e.g. `createTenantContext().run`).
+*
+* Header fallback is intentional: matches `resolveOrgFromHeader` semantics
+* for hosts that select an org via header instead of session/scope. Don't
+* reach for this when `getOrgId(scope)` alone is enough — for standard
+* authenticated routes the scope is already authoritative.
+*
+* @example
+* ```typescript
+* import { getTenantFromRequest } from '@classytic/arc/scope';
+* import { tenantContext } from './lib/mongokit.js';
+*
+* fastify.post('/statements/batch', async (req, reply) => {
+*   const { organizationId } = getTenantFromRequest(req);
+*   if (!organizationId) {
+*     return reply.code(400).send({ error: 'organizationId required' });
+*   }
+*   await tenantContext.run({ tenantId: organizationId }, async () => {
+*     await statementRepository.create(req.body);
+*   });
+* });
+* ```
+*/
+function getTenantFromRequest(req, options = {}) {
+	if (req.scope) {
+		const id = getOrgId(req.scope);
+		if (id) return {
+			organizationId: id,
+			source: "scope"
+		};
+	}
+	const headerName = (options.header ?? "x-organization-id").toLowerCase();
+	const raw = req.headers[headerName];
+	const headerValue = Array.isArray(raw) ? raw[0] : raw;
+	if (typeof headerValue === "string" && headerValue.length > 0) return {
+		organizationId: headerValue,
+		source: "header"
+	};
+	return {
+		organizationId: void 0,
+		source: "none"
+	};
+}
+/**
 * Get stable client identity from a service scope.
 *
 * Returns the `clientId` for machine-to-machine auth (API keys, service accounts),
@@ -342,4 +394,4 @@ const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
 /** Default authenticated scope — used when user is logged in but no org */
 const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
 //#endregion
-export { requireClientId as C, requireUserId as E, isService as S, requireTeamId as T, hasOrgAccess as _, getDPoPJkt as a, isMember as b, getOrgId as c, getScopeContext as d, getScopeContextMap as f, getUserRoles as g, getUserId as h, getClientId as i, getOrgRoles as l, getTeamId as m, PUBLIC_SCOPE as n, getMandate as o, getServiceScopes as p, getAncestorOrgIds as r, getOrgContext as s, AUTHENTICATED_SCOPE as t, getRequestScope as u, isAuthenticated as v, requireOrgId as w, isOrgInScope as x, isElevated as y };
+export { isService as C, requireUserId as D, requireTeamId as E, isOrgInScope as S, requireOrgId as T, getUserRoles as _, getDPoPJkt as a, isElevated as b, getOrgId as c, getScopeContext as d, getScopeContextMap as f, getUserId as g, getTenantFromRequest as h, getClientId as i, getOrgRoles as l, getTeamId as m, PUBLIC_SCOPE as n, getMandate as o, getServiceScopes as p, getAncestorOrgIds as r, getOrgContext as s, AUTHENTICATED_SCOPE as t, getRequestScope as u, hasOrgAccess as v, requireClientId as w, isMember as x, isAuthenticated as y };

package/dist/{types-CTYvcwHe.d.mts → types-CfapW2t8.d.mts}

@@ -229,6 +229,47 @@ declare function hasOrgAccess(scope: RequestScope): boolean;
 declare function isAuthenticated(scope: RequestScope): boolean;
 /** Get organizationId from scope (member, service, or elevated — undefined otherwise) */
 declare function getOrgId(scope: RequestScope): string | undefined;
+/**
+ * Resolve the tenant (organization) id from an incoming Fastify request,
+ * walking the canonical sources in order: `request.scope` → `x-organization-id`
+ * header. Returns `{ organizationId, source }` so callers can log or branch
+ * on which path won.
+ *
+ * Use in custom handlers that bypass arc's auto-CRUD path (worker routes,
+ * batch importers, cross-engine subscribers) and therefore don't get the
+ * tenant injected by `BaseCrudController`. Bridges arc's HTTP shape to
+ * the mongokit/kit-side tenant context (e.g. `createTenantContext().run`).
+ *
+ * Header fallback is intentional: matches `resolveOrgFromHeader` semantics
+ * for hosts that select an org via header instead of session/scope. Don't
+ * reach for this when `getOrgId(scope)` alone is enough — for standard
+ * authenticated routes the scope is already authoritative.
+ *
+ * @example
+ * ```typescript
+ * import { getTenantFromRequest } from '@classytic/arc/scope';
+ * import { tenantContext } from './lib/mongokit.js';
+ *
+ * fastify.post('/statements/batch', async (req, reply) => {
+ *   const { organizationId } = getTenantFromRequest(req);
+ *   if (!organizationId) {
+ *     return reply.code(400).send({ error: 'organizationId required' });
+ *   }
+ *   await tenantContext.run({ tenantId: organizationId }, async () => {
+ *     await statementRepository.create(req.body);
+ *   });
+ * });
+ * ```
+ */
+declare function getTenantFromRequest(req: {
+  scope?: RequestScope;
+  headers: Record<string, string | string[] | undefined>;
+}, options?: {
+  header?: string;
+}): {
+  organizationId: string | undefined;
+  source: "scope" | "header" | "none";
+};
 /**
  * Get stable client identity from a service scope.
  *
@@ -477,4 +518,4 @@ declare const PUBLIC_SCOPE: Readonly<RequestScope>;
 /** Default authenticated scope — used when user is logged in but no org */
 declare const AUTHENTICATED_SCOPE: Readonly<RequestScope>;
 //#endregion
-export { isOrgInScope as C, requireTeamId as D, requireOrgId as E, requireUserId as O, isMember as S, requireClientId as T, getUserId as _, getAncestorOrgIds as a, isAuthenticated as b, getMandate as c, getOrgRoles as d, getRequestScope as f, getTeamId as g, getServiceScopes as h, RequestScope as i, getOrgContext as l, getScopeContextMap as m, Mandate as n, getClientId as o, getScopeContext as p, PUBLIC_SCOPE as r, getDPoPJkt as s, AUTHENTICATED_SCOPE as t, getOrgId as u, getUserRoles as v, isService as w, isElevated as x, hasOrgAccess as y };
+export { isMember as C, requireOrgId as D, requireClientId as E, requireTeamId as O, isElevated as S, isService as T, getTenantFromRequest as _, getAncestorOrgIds as a, hasOrgAccess as b, getMandate as c, getOrgRoles as d, getRequestScope as f, getTeamId as g, getServiceScopes as h, RequestScope as i, requireUserId as k, getOrgContext as l, getScopeContextMap as m, Mandate as n, getClientId as o, getScopeContext as p, PUBLIC_SCOPE as r, getDPoPJkt as s, AUTHENTICATED_SCOPE as t, getOrgId as u, getUserId as v, isOrgInScope as w, isAuthenticated as x, getUserRoles as y };

package/dist/{types-DrBaUwyV.d.mts → types-Dw--SyTq.d.mts}

@@ -1,13 +1,13 @@
-import { r as CacheStore } from "./interface-beEtJyWM.mjs";
-import { Bt as Authenticator } from "./index-BswOSJCE.mjs";
-import { n as ElevationOptions } from "./elevation-BXOWoGCF.mjs";
-import { a as EventTransport } from "./EventTransport-CT_52aWU.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-BD5nw6St.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-CqMdLI2-.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-qXpqTebY.mjs";
-import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-hmkPcDlX.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-DFr45ZG4.mjs";
-import { r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
+import { r as CacheStore } from "./interface-BVkZsvEe.mjs";
+import { Ht as Authenticator } from "./index-DBDgy6Hw.mjs";
+import { n as ElevationOptions } from "./elevation-DvwtjDwu.mjs";
+import { a as EventTransport } from "./EventTransport-B1GFiYUy.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-ClykOQqa.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Do4P_WBC.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-DjEx_J3j.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-5H4930tj.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-DuqTqeqn.mjs";
+import { r as IdempotencyStore } from "./interface-DoE6UoC2.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts
@@ -203,6 +203,29 @@ interface LoadResourcesOptions<TContext = unknown> {
  */
 declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
 //#endregion
+//#region src/testing/preloadResources.d.ts
+/** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
+type EagerGlobResult = Record<string, unknown>;
+/** Lazy glob result: `{ '/path/to/file.ts': () => Promise<unknown> }` */
+type LazyGlobResult = Record<string, () => Promise<unknown>>;
+/**
+ * Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
+ *
+ * Accepts either:
+ * - `{ import: 'default' }` form: values are the resource directly
+ * - default form: values are the full module — picks first export with `toPlugin()`
+ *
+ * Throws if any module doesn't yield a valid `ResourceLike`.
+ */
+declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
+/**
+ * Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
+ *
+ * Use this when resources depend on prior bootstrap (e.g., engine init) and
+ * cannot be evaluated at import time of the preload file.
+ */
+declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
+//#endregion
 //#region src/factory/types.d.ts
 type CorsOptions = Record<string, unknown> & {
   origin?: unknown;
@@ -498,6 +521,29 @@ interface CreateAppOptions {
    * separately by `multipart.limits.fileSize`. (2.15.1)
    */
   bodyLimit?: number;
+  /**
+   * Maximum length of a single URL path parameter (in characters).
+   *
+   * 2.16 — Fastify's default is `100`, which silently 404s modern signed-
+   * token URLs: HMAC tracking tokens (~250 chars), JWT-in-URL, OAuth state
+   * parameters, password-reset / magic-link tokens, etc. Arc's default
+   * is **400** to match the everything-is-a-signed-token reality of
+   * production apps; hosts that need longer params can raise it further
+   * (`1024` for very long JWTs).
+   *
+   * Pass-through to Fastify's `maxParamLength` constructor option — see
+   * https://fastify.dev/docs/latest/Reference/Server/#maxparamlength.
+   *
+   * @example
+   * ```ts
+   * // App expects long HMAC tokens in the URL path
+   * createApp({ preset: 'production', maxParamLength: 1024 });
+   *
+   * // Constrain tighter than arc's default for audit reasons
+   * createApp({ preset: 'production', maxParamLength: 256 });
+   * ```
+   */
+  maxParamLength?: number;
   /**
    * Auth configuration
    *
@@ -1018,4 +1064,4 @@ interface RawBodyOptions {
   runFirst?: boolean;
 }
 //#endregion
-export { CustomPluginAuthOption as a, RawBodyOptions as c, ResourceLike as d, ResourceModule as f, CustomAuthenticatorOption as i, UnderPressureOptions as l, BetterAuthOption as n, JwtAuthOption as o, loadResources as p, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, LoadResourcesOptions as u };
+export { CustomPluginAuthOption as a, RawBodyOptions as c, preloadResourcesAsync as d, LoadResourcesOptions as f, loadResources as h, CustomAuthenticatorOption as i, UnderPressureOptions as l, ResourceModule as m, BetterAuthOption as n, JwtAuthOption as o, ResourceLike as p, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, preloadResources as u };