@classytic/arc 2.22.0 → 2.23.0

package/dist/factory/index.mjs

@@ -1,4 +1,4 @@
-import { a as edgePreset, c as testingPreset, d as getModuleExports, f as orderModules, h as preloadResourcesAsync, i as developmentPreset, l as workerPreset, m as preloadResources, n as createApp, o as getPreset, p as resolveModule, s as productionPreset, t as ArcFactory, u as defineModule } from "../createApp-Ci7yG5gv.mjs";
+import { a as edgePreset, c as testingPreset, d as getModuleExports, f as orderModules, h as preloadResourcesAsync, i as developmentPreset, l as workerPreset, m as preloadResources, n as createApp, o as getPreset, p as resolveModule, s as productionPreset, t as ArcFactory, u as defineModule } from "../createApp-CjOeWJ9_.mjs";
 import { t as healthPlugin } from "../health-ScyjIVo5.mjs";
 import { t as loadResources } from "../loadResources-DpU8pfjV.mjs";
 //#region src/factory/createWorker.ts
@@ -37,28 +37,37 @@ async function createWorker(options, workerOptions = {}) {
 * Convert a Fastify app into a Web Standards fetch handler.
 *
 * The returned function accepts a Web Standard `Request` and returns
-* a Web Standard `Response` — the universal serverless/edge contract.
+* a Web Standard `Response` — the universal serverless contract.
 *
 * Internally uses `app.inject()` which processes the request through
 * the full Fastify pipeline (hooks, plugins, routes) without TCP.
+* Bodies are read as raw bytes (`arrayBuffer()`), so binary payloads
+* (protobuf, images, non-UTF-8 charsets) survive intact — the
+* content-type parser decides how to decode, same as a real socket.
 */
 function toFetchHandler(app, options = {}) {
-	const { autoReady = true } = options;
-	let ready = false;
+	const { autoReady = true, maxRequestBytes = 1048576 } = options;
+	let readyPromise = null;
 	return async (request) => {
-		if (autoReady && !ready) {
-			await app.ready();
-			ready = true;
+		if (autoReady) {
+			readyPromise ??= Promise.resolve(app.ready());
+			await readyPromise;
 		}
 		const url = new URL(request.url);
 		const headers = {};
 		request.headers.forEach((value, key) => {
 			headers[key] = value;
 		});
+		if (maxRequestBytes > 0) {
+			const declared = Number(request.headers.get("content-length"));
+			if (Number.isFinite(declared) && declared > maxRequestBytes) return payloadTooLarge(maxRequestBytes);
+		}
 		let payload;
-		if (request.method !== "GET" && request.method !== "HEAD") try {
-			payload = await request.text();
-		} catch {}
+		if (request.method !== "GET" && request.method !== "HEAD" && request.body !== null) {
+			const bytes = await request.arrayBuffer();
+			if (maxRequestBytes > 0 && bytes.byteLength > maxRequestBytes) return payloadTooLarge(maxRequestBytes);
+			if (bytes.byteLength > 0) payload = Buffer.from(bytes);
+		}
 		const response = await app.inject({
 			method: request.method,
 			url: url.pathname + url.search,
@@ -71,11 +80,22 @@ function toFetchHandler(app, options = {}) {
 			if (Array.isArray(value)) for (const v of value) responseHeaders.append(key, v);
 			else responseHeaders.set(key, String(value));
 		}
-		return new Response(response.payload, {
+		return new Response(response.rawPayload, {
 			status: response.statusCode,
 			headers: responseHeaders
 		});
 	};
 }
+/** Canonical ErrorContract shape for the pre-dispatch 413. */
+function payloadTooLarge(limit) {
+	return new Response(JSON.stringify({
+		code: "arc.payload_too_large",
+		message: `Request body exceeds ${limit} bytes`,
+		status: 413
+	}), {
+		status: 413,
+		headers: { "content-type": "application/json" }
+	});
+}
 //#endregion
 export { ArcFactory, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/{fastify-augmentation-9_fuetB4.d.mts → fastify-augmentation-g_f9omSc.d.mts}

@@ -1,4 +1,4 @@
-import { bn as HookSystem, z as ResourceRegistry } from "./index-DbtgCOCj.mjs";
+import { xn as HookSystem, z as ResourceRegistry } from "./index-BBsvQt7U.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
 import { r as ArcModuleRegistry } from "./module-B4u10iOJ.mjs";
 import { FastifyPluginAsync } from "fastify";

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-DbtgCOCj.mjs";
+import { An as defineHook, Cn as afterCreate, Dn as beforeDelete, En as beforeCreate, On as beforeUpdate, Sn as HookSystemOptions, Tn as afterUpdate, _n as HookHandler, bn as HookRegistration, gn as HookContext, hn as DefineHookOptions, kn as createHookSystem, vn as HookOperation, wn as afterDelete, xn as HookSystem, yn as HookPhase } from "../index-BBsvQt7U.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -77,6 +77,13 @@ declare module "fastify" {
        * ```
        */
       middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+      /**
+       * The resolved backing store. Exposed so non-HTTP executors (MCP
+       * tools via `mcpPlugin`'s execution wiring, jobs, workflows) can run
+       * the same check → lock → execute → record protocol against the same
+       * backend. `undefined` when the plugin is disabled.
+       */
+      store?: IdempotencyStore;
     };
   }
 }

package/dist/idempotency/index.mjs

@@ -1,4 +1,5 @@
 import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
+import { t as createIdempotencyResult } from "../interface-n5hpKg1d.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
@@ -100,21 +101,6 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	};
 }
 //#endregion
-//#region src/idempotency/stores/interface.ts
-/**
-* Helper to create a result object
-*/
-function createIdempotencyResult(statusCode, body, headers, ttlMs) {
-	const now = /* @__PURE__ */ new Date();
-	return {
-		statusCode,
-		headers,
-		body,
-		createdAt: now,
-		expiresAt: new Date(now.getTime() + ttlMs)
-	};
-}
-//#endregion
 //#region src/idempotency/stores/memory.ts
 var MemoryIdempotencyStore = class {
 	name = "memory";
@@ -283,7 +269,8 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		fastify.decorate("idempotency", {
 			invalidate: async () => {},
 			has: async () => false,
-			middleware: async () => {}
+			middleware: async () => {},
+			store: void 0
 		});
 		fastify.decorateRequest("idempotencyKey", void 0);
 		fastify.decorateRequest("idempotencyReplayed", false);
@@ -380,7 +367,8 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		has: async (key) => {
 			return !!await store.findByPrefix(`${key}:`);
 		},
-		middleware: idempotencyMiddleware
+		middleware: idempotencyMiddleware,
+		store
 	});
 	fastify.addHook("preSerialization", async (request, reply, payload) => {
 		if (request.idempotencyReplayed) return payload;

package/dist/{index-DbtgCOCj.d.mts → index-BBsvQt7U.d.mts}

@@ -1097,8 +1097,14 @@ interface JWTPayload {
   [key: string]: unknown;
 }
 /**
- * Standard API response envelope — `{ success, data?, error?, message?, meta? }`.
- * Used by Arc's default response shape.
+ * @deprecated LEGACY envelope — arc's actual wire contract has not used
+ * `{ success, data, error, message }` for a long time. Successes return
+ * DIRECT data (see `IControllerResponse` — `{ data, meta?, status?, headers? }`
+ * flattened onto the wire), and errors return the canonical `ErrorContract`
+ * (`{ code, message, status, details? }` from `@classytic/repo-core/errors`)
+ * emitted by the global error handler. Keeping this type visible teaches new
+ * applications and AI agents to generate an obsolete shape. Scheduled for
+ * removal in v3. Do NOT build new response handling against it.
  */
 interface ApiResponse<T = unknown> {
   success: boolean;
@@ -1423,7 +1429,15 @@ interface IRequestContext<TBody = unknown, TParams extends Record<string, string
   body: TBody;
   /** Authenticated user or null */
   user: TUser | null;
-  /** Request headers */
+  /**
+   * Request headers.
+   *
+   * ⚠ Declared narrow for ergonomics, but on the HTTP path this is
+   * Fastify's headers object passed through — repeated headers arrive as
+   * `string[]` at RUNTIME behind this type. Read via `getHeader(ctx.headers,
+   * name)` from `@classytic/arc/utils` for array-safe, duplicate-deterministic
+   * access. The declared type widens to `ArcHeaders` in v3.
+   */
   headers: Record<string, string | undefined>;
   /** Organization ID (for multi-tenant apps) */
   organizationId?: string;
@@ -4055,6 +4069,14 @@ interface RegistryEntry extends ResourceMetadata {
     roles?: readonly string[];
     redactValue?: unknown;
   }>;
+  /**
+   * The LIVE field-permission map (2.22) — the same object `defineResource`
+   * consumes, surfaced so request-time consumers (the realtime change feed)
+   * can apply `applyFieldReadPermissions` masking to event payloads without
+   * re-reading the resource definition. `fieldPermissions` above stays the
+   * introspection-safe metadata twin.
+   */
+  fields?: FieldPermissionMap;
   /** Pipeline step names (for OpenAPI data) */
   pipelineSteps?: Array<{
     type: string;
@@ -4237,4 +4259,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, UserOrganization as $t, RequestIdOptions as A, ArcCreateResult as An, RouteDefinition as At, defineResource as B, BodySanitizerConfig as Bn, RouteHandler as Bt, RequestContext as C, afterDelete as Cn, PipelineStep as Ct, HealthCheck as D, beforeUpdate as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, beforeDelete as En, ActionDefinition as Et, FastifyWithDecorators as F, BaseControllerOptions as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, JwtContext as Gt, CrudController as H, AuthPluginOptions as Ht, MiddlewareHandler as I, ControllerConfigurableOptions as In, FastifyHandler as It, PresetHook as J, ApiResponse as Jt, ResolvedTenantPurge as K, TokenPair as Kt, RequestWithExtras as L, ControllerConstructionOptions as Ln, IController as Lt, EventsDecorator as M, ArcGetResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ArcListResult as Nn, RateLimitConfig as Nt, HealthOptions as O, createHookSystem as On, ActionHandlerFn as Ot, FastifyWithAuth as P, ArcUpdateResult as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, UserLike as Qt, RegisterOptions as R, ListResult as Rn, IControllerResponse as Rt, QueryParserInterface as S, afterCreate as Sn, PipelineContext as St, CrudRouterOptions as T, beforeCreate as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, Authenticator as Ut, ResourceDefinition as V, AuthHelpers as Vt, ResourcePermissions as W, AuthenticatorContext as Wt, CrudRouteKey as X, JWTPayload as Xt, PresetResult as Y, ArcRequest as Yt, CrudSchemas as Z, ObjectId as Zt, ControllerQueryOptions as _, HookOperation as _n, Guard as _t, InferAdapterDoc as a, SlugExt as an, ResourceExtensions as at, ParsedQuery as b, HookSystem as bn, OperationFilter as bt, TypedController as c, BulkMixin as cn, AggMeasureShorthand as ct, PaginationResult as d, QueryResolverConfig as dn, AggregationDateRangeRequirement as dt, BaseController as en, RouteSchemaOptions as et, IntrospectionData as f, AccessControl as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookHandler as gn, AggregationsMap as gt, ResourceMetadata as h, HookContext as hn, AggregationRateLimit as ht, ValidationResult as i, TreeMixin as in, ResourceHooks as it, ArcDecorator as j, ArcDeleteResult as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, defineHook as kn, ActionsMap as kt, TypedRepository as l, BaseCrudController as ln, AggregationCacheConfig as lt, RegistryStats as m, DefineHookOptions as mn, AggregationMaterializedResult as mt, ConfigError as n, SoftDeleteMixin as nn, FieldRule$1 as nt, InferDocType as o, SlugMixin as on, EventDefinition as ot, RegistryEntry as p, AccessControlConfig as pn, AggregationMaterializedContext as pt, PresetFunction as q, AnyRecord as qt, ValidateOptions as r, TreeExt as rn, ResourceHookContext as rt, InferResourceDoc as s, BulkExt as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, SoftDeleteExt as tn, ArcFieldRule as tt, TypedResourceConfig as u, QueryResolver as un, AggregationConfig as ut, LookupOption as v, HookPhase as vn, Interceptor as vt, ServiceContext as w, afterUpdate as wn, Transform as wt, PopulateOption as x, HookSystemOptions as xn, PipelineConfig as xt, OwnershipCheck as y, HookRegistration as yn, NextFunction as yt, ResourceRegistry as z, BodySanitizer as zn, IRequestContext as zt };
+export { OpenApiSchemas as $, UserLike as $t, RequestIdOptions as A, defineHook as An, RouteDefinition as At, defineResource as B, BodySanitizer as Bn, RouteHandler as Bt, RequestContext as C, afterCreate as Cn, PipelineStep as Ct, HealthCheck as D, beforeDelete as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, beforeCreate as En, ActionDefinition as Et, FastifyWithDecorators as F, ArcUpdateResult as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, AuthenticatorContext as Gt, CrudController as H, AuthHelpers as Ht, MiddlewareHandler as I, BaseControllerOptions as In, FastifyHandler as It, PresetHook as J, AnyRecord as Jt, ResolvedTenantPurge as K, JwtContext as Kt, RequestWithExtras as L, ControllerConfigurableOptions as Ln, IController as Lt, EventsDecorator as M, ArcDeleteResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ArcGetResult as Nn, RateLimitConfig as Nt, HealthOptions as O, beforeUpdate as On, ActionHandlerFn as Ot, FastifyWithAuth as P, ArcListResult as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, ObjectId as Qt, RegisterOptions as R, ControllerConstructionOptions as Rn, IControllerResponse as Rt, QueryParserInterface as S, HookSystemOptions as Sn, PipelineContext as St, CrudRouterOptions as T, afterUpdate as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, AuthPluginOptions as Ut, ResourceDefinition as V, BodySanitizerConfig as Vn, ServerAccessor as Vt, ResourcePermissions as W, Authenticator as Wt, CrudRouteKey as X, ArcRequest as Xt, PresetResult as Y, ApiResponse as Yt, CrudSchemas as Z, JWTPayload as Zt, ControllerQueryOptions as _, HookHandler as _n, Guard as _t, InferAdapterDoc as a, TreeMixin as an, ResourceExtensions as at, ParsedQuery as b, HookRegistration as bn, OperationFilter as bt, TypedController as c, BulkExt as cn, AggMeasureShorthand as ct, PaginationResult as d, QueryResolver as dn, AggregationDateRangeRequirement as dt, UserOrganization as en, RouteSchemaOptions as et, IntrospectionData as f, QueryResolverConfig as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookContext as gn, AggregationsMap as gt, ResourceMetadata as h, DefineHookOptions as hn, AggregationRateLimit as ht, ValidationResult as i, TreeExt as in, ResourceHooks as it, ArcDecorator as j, ArcCreateResult as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, createHookSystem as kn, ActionsMap as kt, TypedRepository as l, BulkMixin as ln, AggregationCacheConfig as lt, RegistryStats as m, AccessControlConfig as mn, AggregationMaterializedResult as mt, ConfigError as n, SoftDeleteExt as nn, FieldRule$1 as nt, InferDocType as o, SlugExt as on, EventDefinition as ot, RegistryEntry as p, AccessControl as pn, AggregationMaterializedContext as pt, PresetFunction as q, TokenPair as qt, ValidateOptions as r, SoftDeleteMixin as rn, ResourceHookContext as rt, InferResourceDoc as s, SlugMixin as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, BaseController as tn, ArcFieldRule as tt, TypedResourceConfig as u, BaseCrudController as un, AggregationConfig as ut, LookupOption as v, HookOperation as vn, Interceptor as vt, ServiceContext as w, afterDelete as wn, Transform as wt, PopulateOption as x, HookSystem as xn, PipelineConfig as xt, OwnershipCheck as y, HookPhase as yn, NextFunction as yt, ResourceRegistry as z, ListResult as zn, IRequestContext as zt };

package/dist/{index-BEu4wjbL.d.mts → index-Ba10fdKp.d.mts}

@@ -1,4 +1,4 @@
-import { Ut as Authenticator } from "./index-DbtgCOCj.mjs";
+import { Wt as Authenticator } from "./index-BBsvQt7U.mjs";
 import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
 import { n as ElevationOptions } from "./elevation-C9s5hFP_.mjs";
 import { a as EventTransport } from "./EventTransport-QmY7A258.mjs";
@@ -7,7 +7,7 @@ import { r as QueryCachePluginOptions } from "./queryCachePlugin-CfYWq-Ak.mjs";
 import { t as ErrorHandlerOptions } from "./errorHandler-C6yv4ZTW.mjs";
 import { l as ResourceLike, n as ArcModuleInput } from "./module-B4u10iOJ.mjs";
 import { t as EventPluginOptions } from "./eventPlugin-A6EbthXR.mjs";
-import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DLwklPlG.mjs";
+import { g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions, x as HealthOptions } from "./versioning-D6PvCwpq.mjs";
 import { r as IdempotencyStore } from "./interface-Uk8ONJv7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 //#region src/testing/preloadResources.d.ts
@@ -672,6 +672,15 @@ interface CreateAppOptions {
      * Requires emitEvents to be enabled (or events plugin registered).
      */
     sse?: SSEOptions | boolean;
+    /**
+     * Realtime resource change feed (2.22) — `GET /realtime/:resource`
+     * streams that resource's created/updated/deleted events over SSE,
+     * gated by its own `list` permission with per-event row filtering,
+     * tenant scoping, and field-level masking. Default: false (opt-in).
+     * Set true for defaults, or pass RealtimeOptions (path, heartbeat,
+     * resource allowlist, operations). Requires events.
+     */
+    realtime?: RealtimeOptions | boolean;
     /**
      * QueryCache — TanStack Query-inspired server cache with SWR.
      * Default: false (opt-in). Set to true for memory store defaults.

package/dist/{index-D8MKYGDa.d.mts → index-CC5ruDGh.d.mts}

@@ -1,7 +1,7 @@
-import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, qt as AnyRecord, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-DbtgCOCj.mjs";
+import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, Jt as AnyRecord, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-BBsvQt7U.mjs";
 import { i as RequestScope } from "./types-DH0GupI7.mjs";
 import { t as PermissionCheck } from "./types-Csxga7d3.mjs";
-import "./fastify-augmentation-9_fuetB4.mjs";
+import "./fastify-augmentation-g_f9omSc.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";

package/dist/{index-ogIHvOjo.d.mts → index-wMoWBLkn.d.mts}

@@ -449,6 +449,72 @@ declare function createOrgPermissions(config: {
  */
 declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
 //#endregion
+//#region src/permissions/grants.d.ts
+/**
+ * The grant-mode lattice, weakest → strongest. Holding a mode satisfies
+ * every mode at or below it (`write` ⊇ `read` ⊇ `list` ⊇ `see`); `manage`
+ * (grant/revoke rights) satisfies everything. Same semantics as Puter's
+ * `see < list < read < write` hierarchy with `manage` folded into the
+ * lattice top instead of a separate string namespace.
+ */
+declare const GRANT_MODES: readonly ["see", "list", "read", "write", "manage"];
+/** One mode from the {@link GRANT_MODES} lattice. */
+type GrantMode = (typeof GRANT_MODES)[number];
+/**
+ * Does a HELD mode satisfy a REQUIRED mode? Lattice implication —
+ * `modeSatisfies('write', 'read') === true`, `modeSatisfies('see', 'read')
+ * === false`. Unknown strings (a corrupted grant row) never satisfy
+ * anything: fail-closed.
+ */
+declare function modeSatisfies(held: string | undefined, required: GrantMode): boolean;
+/**
+ * What a grant `resolve` callback may return:
+ *
+ * - `boolean` — the host did the whole check itself (already compared modes).
+ * - `{ mode }` — the strongest mode the caller holds on `ctx.resourceId`;
+ *   the combinator applies the lattice against the required mode.
+ * - `{ filters }` — list-shaped resolution: row filters that scope the
+ *   query to visible records (flows through `PermissionResult.filters` →
+ *   `_policyFilters` → the repository query). Grants access with the
+ *   filters attached.
+ * - `{ mode, filters }` — mode gates; filters ride along when it passes.
+ *
+ * An empty object (neither `mode` nor `filters`) and a thrown error both
+ * DENY — grant resolution is fail-closed, same stance as `isRevoked`.
+ */
+type GrantResolution = boolean | {
+  mode?: GrantMode | string;
+  filters?: Record<string, unknown>;
+  /** Optional denial reason surfaced on the 403 (clamped by the framework). */
+  reason?: string;
+};
+interface RequireGrantOptions {
+  /** The mode this operation needs (lattice-checked against the held mode). */
+  mode: GrantMode;
+  /**
+   * Look up the caller's grant. Receives the full `PermissionContext`
+   * (`resourceId` for single-record ops, `request` for headers/scope —
+   * e.g. a share-link token). May be sync or async.
+   *
+   * NOTE: unauthenticated callers are NOT rejected up front — share links
+   * grant access to anonymous callers by design. If your grants are
+   * session-only, return `false` when `ctx.user` is null (or compose with
+   * `requireAuth()` via `allOf`).
+   */
+  resolve: (ctx: PermissionContext) => GrantResolution | Promise<GrantResolution>;
+  /** Roles that skip the grant check entirely (platform admins). */
+  bypassRoles?: readonly string[];
+}
+/**
+ * Per-record grant gate. Same combinator tier as `requireOwnership` —
+ * compose with `anyOf`/`allOf` like any other `PermissionCheck`.
+ *
+ * Fail-closed contract: resolver throws → denied (logged via
+ * `ctx.request.log`); resolution carries neither `mode` nor `filters` →
+ * denied; unknown/corrupted mode strings → denied.
+ */
+declare function requireGrant(options: RequireGrantOptions): PermissionCheck;
+//#endregion
 //#region src/permissions/roleHierarchy.d.ts
 /**
  * Role Hierarchy — Composable RBAC Inheritance
@@ -706,4 +772,4 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { requireOwnership as A, requireMandate as B, createOrgPermissions as C, denyAll as D, anyOf as E, normalizePermissionResult as F, RequireAgentScopeOptions as I, RequireMandateOptions as L, roles as M, when as N, not as O, applyPermissionResult as P, requireAgentScope as R, createDynamicPermissionMatrix as S, allowPublic as T, createRoleHierarchy as _, permissionMatrix as a, DynamicPermissionMatrixConfig as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireRoles as j, requireAuth as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, ConnectEventsOptions as v, allOf as w, PermissionEventBus as x, DynamicPermissionMatrix as y, requireDPoP as z };
+export { allOf as A, applyPermissionResult as B, requireGrant as C, PermissionEventBus as D, DynamicPermissionMatrixConfig as E, requireAuth as F, requireDPoP as G, RequireAgentScopeOptions as H, requireOwnership as I, requireMandate as K, requireRoles as L, anyOf as M, denyAll as N, createDynamicPermissionMatrix as O, not as P, roles as R, modeSatisfies as S, DynamicPermissionMatrix as T, RequireMandateOptions as U, normalizePermissionResult as V, requireAgentScope as W, createRoleHierarchy as _, permissionMatrix as a, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, allowPublic as j, createOrgPermissions as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, GRANT_MODES as v, ConnectEventsOptions as w, RequireGrantOptions as x, GrantMode as y, when as z };

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { $t as UserOrganization, A as RequestIdOptions, An as ArcCreateResult, B as defineResource, Bt as RouteHandler, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Fn as BaseControllerOptions, Ft as ControllerLike, H as CrudController, Ht as AuthPluginOptions, In as ControllerConfigurableOptions, Jt as ApiResponse, L as RequestWithExtras, Ln as ControllerConstructionOptions, Lt as IController, Mn as ArcGetResult, N as FastifyRequestExtras, Nn as ArcListResult, Nt as RateLimitConfig, O as HealthOptions, P as FastifyWithAuth, Pn as ArcUpdateResult, Q as MiddlewareConfig, Rn as ListResult, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, X as CrudRouteKey, Xt as JWTPayload, Y as PresetResult, Yt as ArcRequest, Z as CrudSchemas, a as InferAdapterDoc, an as SlugExt, c as TypedController, cn as BulkMixin, ct as AggMeasureShorthand, d as PaginationResult, dt as AggregationDateRangeRequirement, en as BaseController, et as RouteSchemaOptions, f as IntrospectionData, ft as AggregationIndexHint, g as ArcInternalMetadata, gt as AggregationsMap, h as ResourceMetadata, ht as AggregationRateLimit, i as ValidationResult, in as TreeMixin, jn as ArcDeleteResult, k as IntrospectionPluginOptions, l as TypedRepository, ln as BaseCrudController, lt as AggregationCacheConfig, m as RegistryStats, mt as AggregationMaterializedResult, n as ConfigError, nn as SoftDeleteMixin, nt as FieldRule, o as InferDocType, on as SlugMixin, ot as EventDefinition, p as RegistryEntry, pt as AggregationMaterializedContext, q as PresetFunction, qt as AnyRecord, r as ValidateOptions, rn as TreeExt, s as InferResourceDoc, sn as BulkExt, st as AggMeasureInput, t as RouteHandlerMethod, tn as SoftDeleteExt, u as TypedResourceConfig, ut as AggregationConfig, w as ServiceContext, y as OwnershipCheck, zt as IRequestContext } from "./index-DbtgCOCj.mjs";
+import { A as RequestIdOptions, B as defineResource, Bt as RouteHandler, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Fn as ArcUpdateResult, Ft as ControllerLike, H as CrudController, In as BaseControllerOptions, Jt as AnyRecord, L as RequestWithExtras, Ln as ControllerConfigurableOptions, Lt as IController, Mn as ArcDeleteResult, N as FastifyRequestExtras, Nn as ArcGetResult, Nt as RateLimitConfig, O as HealthOptions, P as FastifyWithAuth, Pn as ArcListResult, Q as MiddlewareConfig, Rn as ControllerConstructionOptions, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, U as ResourceConfig, Ut as AuthPluginOptions, V as ResourceDefinition, X as CrudRouteKey, Xt as ArcRequest, Y as PresetResult, Yt as ApiResponse, Z as CrudSchemas, Zt as JWTPayload, a as InferAdapterDoc, an as TreeMixin, c as TypedController, cn as BulkExt, ct as AggMeasureShorthand, d as PaginationResult, dt as AggregationDateRangeRequirement, en as UserOrganization, et as RouteSchemaOptions, f as IntrospectionData, ft as AggregationIndexHint, g as ArcInternalMetadata, gt as AggregationsMap, h as ResourceMetadata, ht as AggregationRateLimit, i as ValidationResult, in as TreeExt, jn as ArcCreateResult, k as IntrospectionPluginOptions, l as TypedRepository, ln as BulkMixin, lt as AggregationCacheConfig, m as RegistryStats, mt as AggregationMaterializedResult, n as ConfigError, nn as SoftDeleteExt, nt as FieldRule, o as InferDocType, on as SlugExt, ot as EventDefinition, p as RegistryEntry, pt as AggregationMaterializedContext, q as PresetFunction, r as ValidateOptions, rn as SoftDeleteMixin, s as InferResourceDoc, sn as SlugMixin, st as AggMeasureInput, t as RouteHandlerMethod, tn as BaseController, u as TypedResourceConfig, un as BaseCrudController, ut as AggregationConfig, w as ServiceContext, y as OwnershipCheck, zn as ListResult, zt as IRequestContext } from "./index-BBsvQt7U.mjs";
 import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Csxga7d3.mjs";
 import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, t as FieldPermission } from "./fields-D3lhgzhD.mjs";
-import "./fastify-augmentation-9_fuetB4.mjs";
-import { A as HOOK_OPERATIONS, B as SYSTEM_FIELDS, C as CrudOperation, D as DEFAULT_SORT, E as DEFAULT_MAX_LIMIT, F as MAX_REGEX_LENGTH, I as MAX_SEARCH_LENGTH, L as MUTATION_OPERATIONS, M as HookOperation, N as HookPhase, O as DEFAULT_TENANT_FIELD, P as MAX_FILTER_DEPTH, R as MutationOperation, S as CRUD_OPERATIONS, T as DEFAULT_LIMIT, f as defineResourceVariants, g as mergeResourceConfig, h as SeamedResourceConfig, j as HOOK_PHASES, k as DEFAULT_UPDATE_METHOD, m as ResourceSeams, p as AdapterLike, s as getControllerScope, v as defineAction, w as DEFAULT_ID_FIELD, x as defineAggregation, z as RESERVED_QUERY_PARAMS } from "./index-D8MKYGDa.mjs";
-import { A as requireOwnership, C as createOrgPermissions, D as denyAll, E as anyOf, N as when, S as createDynamicPermissionMatrix, T as allowPublic, b as DynamicPermissionMatrixConfig, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, h as requireTeamMembership, i as ownerWithAdminBypass, j as requireRoles, k as requireAuth, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, w as allOf, y as DynamicPermissionMatrix } from "./index-ogIHvOjo.mjs";
+import "./fastify-augmentation-g_f9omSc.mjs";
+import { A as HOOK_OPERATIONS, B as SYSTEM_FIELDS, C as CrudOperation, D as DEFAULT_SORT, E as DEFAULT_MAX_LIMIT, F as MAX_REGEX_LENGTH, I as MAX_SEARCH_LENGTH, L as MUTATION_OPERATIONS, M as HookOperation, N as HookPhase, O as DEFAULT_TENANT_FIELD, P as MAX_FILTER_DEPTH, R as MutationOperation, S as CRUD_OPERATIONS, T as DEFAULT_LIMIT, f as defineResourceVariants, g as mergeResourceConfig, h as SeamedResourceConfig, j as HOOK_PHASES, k as DEFAULT_UPDATE_METHOD, m as ResourceSeams, p as AdapterLike, s as getControllerScope, v as defineAction, w as DEFAULT_ID_FIELD, x as defineAggregation, z as RESERVED_QUERY_PARAMS } from "./index-CC5ruDGh.mjs";
+import { A as allOf, E as DynamicPermissionMatrixConfig, F as requireAuth, I as requireOwnership, L as requireRoles, M as anyOf, N as denyAll, O as createDynamicPermissionMatrix, T as DynamicPermissionMatrix, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, h as requireTeamMembership, i as ownerWithAdminBypass, j as allowPublic, k as createOrgPermissions, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, z as when } from "./index-wMoWBLkn.mjs";
 import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-DHcHVAgk.mjs";
 //#region src/index.d.ts
 declare const version: string;

package/dist/index.mjs

@@ -1,10 +1,11 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-DNre0wRg.mjs";
 import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-DkO8Nk6-.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-C6FlRWxF.mjs";
-import { E as requireRoles, F as applyFieldReadPermissions, I as applyFieldWritePermissions, L as fields, O as when, S as denyAll, T as requireOwnership, _ as requireServiceScope, b as allowPublic, c as publicReadAdminWrite, d as createDynamicPermissionMatrix, f as createOrgPermissions, g as requireScopeContext, h as requireOrgRole, i as ownerWithAdminBypass, l as readOnly, m as requireOrgMembership, n as authenticated, o as presets_exports, p as requireOrgInScope, r as fullPublic, s as publicRead, t as adminOnly, v as requireTeamMembership, w as requireAuth, x as anyOf, y as allOf } from "./permissions-BJMuKMl7.mjs";
-import { a as defineResource, c as defineAction, d as defineAggregation, i as defineResourceVariants, o as ResourceDefinition, s as mergeResourceConfig } from "./core-b6fgFgnd.mjs";
-import { l as getControllerScope } from "./actionPermissions-ze70xXJi.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-BQ8KNvWC.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, o as fields } from "./applyPermissionResult-Tw4iXtlf.mjs";
+import { a as defineResource, c as defineAction, d as defineAggregation, i as defineResourceVariants, o as ResourceDefinition, s as mergeResourceConfig } from "./core-DQ6rDTyH.mjs";
+import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf, T as denyAll, _ as requireOrgMembership, b as requireServiceScope, c as publicReadAdminWrite, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, l as readOnly, m as createDynamicPermissionMatrix, n as authenticated, o as presets_exports, r as fullPublic, s as publicRead, t as adminOnly, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "./permissions-tbxFHxjZ.mjs";
+import { l as getControllerScope } from "./actionPermissions-lszoJle1.mjs";
 //#region src/index.ts
-const version = "2.22.0";
+const version = "2.23.0";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAction, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, mergeResourceConfig, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/{init-DleK3p9f.mjs → init-CjO4p_q1.mjs}

@@ -1074,10 +1074,10 @@ const SCAFFOLD_DEP_VERSIONS = {
 	},
 	devCommon: {
 		"@biomejs/biome": "^2.4.15",
-		"mongodb-memory-server": "^11.1.0",
 		"pino-pretty": "^13.1.3",
 		vitest: "^4.1.7"
 	},
+	devMongokit: { "mongodb-memory-server": "^11.1.0" },
 	devTypescript: {
 		"@types/node": "^22.10.0",
 		tsx: "^4.22.3",
@@ -1205,7 +1205,10 @@ function resolveScaffoldDependencies(config) {
 		Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.authJwt);
 		if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.typesJwt);
 	}
-	if (config.adapter === "mongokit") Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.adapterMongokit);
+	if (config.adapter === "mongokit") {
+		Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.adapterMongokit);
+		Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.devMongokit);
+	}
 	if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.devTypescript);
 	applyLatestOverlay(dependencies);
 	applyLatestOverlay(devDependencies);

package/dist/integrations/event-gateway.mjs

@@ -4,7 +4,7 @@ const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 	const { auth = true, orgScoped = false, roomPolicy, maxMessageBytes, maxSubscriptionsPerClient, authenticate } = opts;
 	if (auth && !authenticate && !fastify.hasDecorator("authenticate")) throw new Error("[arc-event-gateway] auth is true but fastify.authenticate is not registered. Register an auth plugin first, provide a custom authenticate function, or set auth: false.");
 	if (opts.sse !== false) {
-		const { default: ssePlugin } = await import("../sse-CfUjwjDk.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("../sse-0u4P4-OI.mjs").then((n) => n.r);
 		await fastify.register(ssePlugin, {
 			path: opts.sse?.path ?? "/events/stream",
 			requireAuth: auth,

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
 import { c as WebSocketClient, l as WebSocketMessage, u as WebSocketPluginOptions } from "../websocket-uuWqM6UY.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-Bc42CUyk.mjs";
+import { _ as ToolDefinition, c as McpAuthResult, d as McpResourceConfig, f as PromptDefinition, g as ToolContext, h as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpPluginOptions } from "../types-5OuqeTDX.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export type { BetterAuthHandler, CallToolResult, CreateMcpServerConfig, CrudOperation, EventGatewayOptions, JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, McpAuthResult, McpPluginOptions, McpResourceConfig, PromptDefinition, QueueStats, StreamlinePluginOptions, ToolAnnotations, ToolContext, ToolDefinition, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription, WorkflowLike, WorkflowRunLike };

package/dist/integrations/mcp/index.d.mts

@@ -1,7 +1,8 @@
-import { Rt as IControllerResponse, V as ResourceDefinition, zt as IRequestContext } from "../../index-DbtgCOCj.mjs";
+import { Rt as IControllerResponse, V as ResourceDefinition, Vt as ServerAccessor, zt as IRequestContext } from "../../index-BBsvQt7U.mjs";
 import { i as RequestScope } from "../../types-DH0GupI7.mjs";
 import { t as PermissionCheck } from "../../types-Csxga7d3.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-Bc42CUyk.mjs";
+import { n as FieldPermissionMap } from "../../fields-D3lhgzhD.mjs";
+import { _ as ToolDefinition, a as CrudDescriptionOverride, c as McpAuthResult, d as McpResourceConfig, f as PromptDefinition, g as ToolContext, h as ToolAnnotations, i as CrudDescriptionMeta, l as McpExecutionWiring, m as SessionEntry, n as CallToolResult, o as CrudOperation, p as PromptResult, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpPluginOptions } from "../../types-5OuqeTDX.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
@@ -299,6 +300,34 @@ declare function customGuard(check: (ctx: ToolContext) => boolean | Promise<bool
 //#endregion
 //#region src/integrations/mcp/buildRequestContext.d.ts
 type McpOperation = "list" | "get" | "create" | "update" | "delete" | "action";
+/**
+ * Optional context extras — the pieces of `IRequestContext` that HTTP's
+ * `createRequestContext` assembles from Fastify decorators and the MCP
+ * synthetic path historically DROPPED. Without them, controller code that
+ * reads `metadata.arc.hooks` (the whole hook system — including the
+ * arcCorePlugin after-hook that publishes `<resource>.<op>d` events) or
+ * `ctx.server.events` silently no-ops on MCP calls: agents could mutate
+ * records without hooks firing, events publishing, realtime feeds updating,
+ * or webhooks dispatching. Thread these through `invokeController` /
+ * `resourceToTools({ wiring })` to restore full HTTP ↔ MCP parity.
+ */
+interface McpContextExtras {
+  /**
+   * Resource wiring — becomes `metadata.arc`, the same frozen shape
+   * `buildArcDecorator` stamps on HTTP requests (`ArcRouteMeta`).
+   */
+  arc?: {
+    readonly resourceName: string;
+    readonly schemaOptions?: unknown;
+    readonly permissions?: unknown;
+    readonly hooks?: unknown;
+    readonly events?: unknown;
+    readonly fields?: unknown;
+    readonly idField?: string;
+  };
+  /** Server accessor — `ctx.server.events/audit/log`, mirroring HTTP. */
+  server?: ServerAccessor;
+}
 /**
  * Build an IRequestContext from MCP tool input and session auth.
  *
@@ -317,7 +346,7 @@ type McpOperation = "list" | "get" | "create" | "update" | "delete" | "action";
  * the session-derived scope is `public` (i.e. MCP called with `auth: false`).
  * An authenticated session scope is never overwritten.
  */
-declare function buildRequestContext(input: Record<string, unknown>, auth: McpAuthResult | null, operation: McpOperation, policyFilters?: Record<string, unknown>, scopeOverride?: RequestScope): IRequestContext;
+declare function buildRequestContext(input: Record<string, unknown>, auth: McpAuthResult | null, operation: McpOperation, policyFilters?: Record<string, unknown>, scopeOverride?: RequestScope, extras?: McpContextExtras): IRequestContext;
 //#endregion
 //#region src/integrations/mcp/invokeController.d.ts
 /**
@@ -349,6 +378,33 @@ interface InvokeControllerOptions {
    * action handler reached through a `string` route handler).
    */
   readonly methodName?: string;
+  /**
+   * Resource field-permission map (`ResourceConfig.fields`). When present,
+   * field-level READ permissions are applied to the response payload before
+   * serialization — the same masking the HTTP wire and realtime frames get.
+   * Omit only for tools whose output carries no resource documents.
+   */
+  readonly fields?: FieldPermissionMap;
+  /**
+   * App-level execution wiring (hooks system, event bus, audit, logger,
+   * idempotency store). When present, the synthetic request context carries
+   * `metadata.arc` + `server` exactly like HTTP's `createRequestContext` —
+   * so resource hooks run, CRUD events publish, and `ctx.server.*` works.
+   * `mcpPlugin` supplies this automatically; omit for dispatch-only calls.
+   */
+  readonly wiring?: McpExecutionWiring;
+  /** Resource `schemaOptions` — rides on `metadata.arc` like HTTP. */
+  readonly schemaOptions?: unknown;
+  /** Resource `idField` — rides on `metadata.arc` for `getEntityIdField()`. */
+  readonly idField?: string;
+  /**
+   * Caller-supplied idempotency key (mutations only). Requires
+   * `wiring.idempotencyStore`; the executor then runs the same
+   * check → lock → execute → record → replay protocol the HTTP
+   * idempotency plugin runs, keyed by tool + input + caller identity.
+   * A concurrent call with the same key gets a 409 `arc.idempotency_conflict`.
+   */
+  readonly idempotencyKey?: string;
 }
 /**
  * Invoke a controller method through the MCP synthetic-context path.
@@ -549,6 +605,13 @@ interface ResourceToToolsConfig extends McpResourceConfig {
   toolNamePrefix?: string;
   /** Per-operation tool name overrides: `{ get: 'get_job_by_id' }` */
   names?: Partial<Record<CrudOperation, string>>;
+  /**
+   * App-level execution wiring (hooks, events, audit, log, idempotency
+   * store). `mcpPlugin` supplies this automatically from its Fastify
+   * instance; standalone callers pass their own or omit it for
+   * dispatch-only tools (no hooks/events/idempotency).
+   */
+  wiring?: McpExecutionWiring;
 }
 /**
  * Convert a ResourceDefinition into MCP ToolDefinitions.

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-ByA2tf6D.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-BtzIL_kM.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-Bc42CUyk.mjs";
+import { c as McpAuthResult, u as McpPluginOptions } from "../../types-5OuqeTDX.mjs";
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {
   /** MCP plugin options (resources, overrides, etc.) — same as mcpPlugin config */

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-ByA2tf6D.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-BtzIL_kM.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities