@classytic/arc 2.22.0 → 2.25.0

package/dist/sseStream-BQ7Qaynp.mjs

@@ -0,0 +1,57 @@
+import { n as forwardedStreamHeaders } from "./streaming-BQcW6_Kq.mjs";
+//#region src/utils/sseStream.ts
+/**
+* Take over the reply socket and open an SSE stream. Call ONLY after every
+* gate (auth, permissions, validation) has passed — after `hijack()` no
+* JSON error can be sent.
+*/
+function openSseStream(request, reply, options = {}) {
+	const { heartbeatMs = 3e4, retryMs } = options;
+	reply.hijack();
+	reply.raw.writeHead(200, {
+		"content-type": "text/event-stream",
+		"cache-control": "no-cache",
+		connection: "keep-alive",
+		"x-accel-buffering": "no",
+		...forwardedStreamHeaders(reply)
+	});
+	reply.raw.flushHeaders();
+	if (retryMs !== void 0) reply.raw.write(`retry: ${retryMs}\n\n`);
+	const cleanups = [];
+	let closed = false;
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		clearInterval(heartbeatTimer);
+		for (const fn of cleanups) try {
+			fn();
+		} catch {}
+		if (!reply.raw.writableEnded) reply.raw.end();
+	};
+	const destroyOnBackpressure = (context) => {
+		request.raw.destroy(/* @__PURE__ */ new Error(`SSE connection terminated: ${context} backpressure`));
+		close();
+	};
+	const heartbeatTimer = setInterval(() => {
+		if (closed) return;
+		if (!reply.raw.write(": heartbeat\n\n")) destroyOnBackpressure("heartbeat");
+	}, heartbeatMs);
+	request.raw.on("close", close);
+	return {
+		write(eventName, data, id) {
+			if (closed) return false;
+			const idField = id !== void 0 ? `id: ${id}\n` : "";
+			if (!reply.raw.write(`${idField}event: ${eventName}\ndata: ${data}\n\n`)) {
+				destroyOnBackpressure("slow client");
+				return false;
+			}
+			return true;
+		},
+		close,
+		onCleanup(fn) {
+			cleanups.push(fn);
+		}
+	};
+}
+//#endregion
+export { openSseStream as t };

package/dist/testing/index.d.mts

@@ -1,6 +1,7 @@
-import { V as ResourceDefinition, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
-import { n as ArcModuleInput } from "../module-B4u10iOJ.mjs";
-import { d as preloadResourcesAsync, t as CreateAppOptions, u as preloadResources } from "../index-BEu4wjbL.mjs";
+import { V as ResourceDefinition } from "../index-DPRH0Cme.mjs";
+import { c as AnyRecord } from "../types-Dmw-6Qeo.mjs";
+import { d as ArcModuleInput } from "../index-KUoxjIq1.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-0oe-JSSS.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1,5 +1,5 @@
 import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { d as getModuleExports, h as preloadResourcesAsync, m as preloadResources, n as createApp } from "../createApp-Ci7yG5gv.mjs";
+import { i as createApp, n as preloadResourcesAsync, p as getModuleExports, t as preloadResources } from "../preloadResources-DfyngIN9.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -1116,7 +1116,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-Ci7yG5gv.mjs").then((n) => n.r);
+	const { createApp } = await import("../preloadResources-DfyngIN9.mjs").then((n) => n.a);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/transactionContext-PNdoyLLm.mjs

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context/transactionContext.ts
+/**
+* Transaction Context via AsyncLocalStorage
+*
+* Provides a Unit-of-Work (UoW) hook so any code in the call stack can
+* retrieve the active database session/transaction without it being threaded
+* through every function parameter.
+*
+* Arc is DB-agnostic — the session type is `unknown` so any backend
+* (Mongoose session, Prisma transaction, pg client, Drizzle client) can
+* participate. Kit adapters call `runInTransaction(session, fn)` to install
+* the active context; the outbox's `store()` reads it automatically when no
+* explicit `options.session` is passed.
+*
+* @example
+* ```typescript
+* // In a Mongoose-backed service (mongokit adapter)
+* import { transactionContext } from '@classytic/arc/context';
+*
+* await mongoose.connection.withSession(async (session) => {
+*   await session.withTransaction(async () => {
+*     await transactionContext.run(session, async () => {
+*       await orders.insertOne(order, { session });
+*       // outbox.store() auto-picks up `session` — no manual threading
+*       await outbox.store(orderCreatedEvent);
+*     });
+*   });
+* });
+* ```
+*
+* @example
+* ```typescript
+* // Opt-out: explicit session always wins over the ALS context
+* await outbox.store(event, { session: explicitSession });
+* ```
+*/
+const storage = new AsyncLocalStorage();
+/**
+* Transaction context API.
+*
+* - `run(session, fn)` — install an active DB session for the duration of `fn`
+* - `get()` — read the current session (undefined if outside a transaction scope)
+*/
+const transactionContext = {
+	/**
+	* Run `fn` with `session` as the active DB transaction context.
+	* Any call to `get()` within `fn`'s async call stack returns `session`.
+	*/
+	run(session, fn) {
+		return storage.run(session, fn);
+	},
+	/**
+	* Get the current DB session, or `undefined` if not inside a
+	* `transactionContext.run(...)` scope.
+	*/
+	get() {
+		return storage.getStore();
+	},
+	/** The underlying AsyncLocalStorage instance. Exposed for advanced integrations. */
+	storage
+};
+//#endregion
+export { transactionContext as t };

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OpenApiSchemas, $t as UserOrganization, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Fn as BaseControllerOptions, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as JwtContext, H as CrudController, Ht as AuthPluginOptions, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, Jt as ApiResponse, K as ResolvedTenantPurge, Kt as TokenPair, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Qt as UserLike, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as Authenticator, Vt as AuthHelpers, W as ResourcePermissions, Wt as AuthenticatorContext, X as CrudRouteKey, Xt as JWTPayload, Y as PresetResult, Yt as ArcRequest, Z as CrudSchemas, Zt as ObjectId, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as AnyRecord, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-DbtgCOCj.mjs";
-import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Y as PresetResult, Z as CrudSchemas, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as BaseControllerOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-DPRH0Cme.mjs";
+import { i as RequestScope } from "../types-DjC-KUCz.mjs";
+import { c as AnyRecord, d as ObjectId, f as UserLike, i as UserBase, l as ArcRequest, n as PermissionContext, p as UserOrganization, r as PermissionResult, t as PermissionCheck, u as JWTPayload } from "../types-Dmw-6Qeo.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
-export type { 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, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };
+export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, 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, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/{types-bHblZ9YN.mjs → types-CSyCxl2V.mjs}

@@ -1,4 +1,6 @@
 import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-DkO8Nk6-.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BvlQSDMB.mjs";
+import { t as getUserId$1 } from "./userHelpers-Cg_y3fBz.mjs";
 //#region src/scope/types.ts
 /**
 * Request Scope — The One Standard
@@ -87,8 +89,7 @@ function getTenantFromRequest(req, options = {}) {
 		};
 	}
 	const headerName = (options.header ?? "x-organization-id").toLowerCase();
-	const raw = req.headers[headerName];
-	const headerValue = Array.isArray(raw) ? raw[0] : raw;
+	const headerValue = requireSingleHeaderValue(req.headers, headerName);
 	if (typeof headerValue === "string" && headerValue.length > 0) return {
 		organizationId: headerValue,
 		source: "header"
@@ -259,8 +260,13 @@ function isOrgInScope(scope, targetOrgId) {
 * ```
 */
 function getUserId(scope) {
-	if (scope.kind === "public") return void 0;
-	return scope.userId;
+	switch (scope.kind) {
+		case "authenticated":
+		case "member":
+		case "elevated": return scope.userId;
+		case "public":
+		case "service": return;
+	}
 }
 /**
 * Throwing variant of `getOrgId`. Returns the organization id when the
@@ -356,9 +362,12 @@ function getUserRoles(scope) {
 */
 function getOrgContext(request) {
 	const scope = request.scope ?? { kind: "public" };
+	const requestedOrgId = requireSingleHeaderValue(request.headers, "x-organization-id");
+	const rawOrganizationId = request.user?.organizationId;
+	const userOrganizationId = rawOrganizationId === void 0 || rawOrganizationId === null ? void 0 : String(rawOrganizationId) || void 0;
 	return {
-		userId: getUserId(scope) ?? request.user?.id ?? request.user?._id,
-		organizationId: getOrgId(scope) ?? request.user?.organizationId ?? request.headers?.["x-organization-id"],
+		userId: getUserId(scope) ?? getUserId$1(request.user),
+		organizationId: getOrgId(scope) ?? userOrganizationId ?? requestedOrgId,
 		roles: getUserRoles(scope),
 		orgRoles: getOrgRoles(scope)
 	};
@@ -389,9 +398,31 @@ function getOrgContext(request) {
 function getRequestScope(request) {
 	return request.scope ?? PUBLIC_SCOPE;
 }
+function scopeFirstCtx(req, options = {}) {
+	let actorId;
+	let organizationId;
+	const s = req.scope;
+	if (s && "kind" in s) {
+		actorId = getUserId(s) ?? getClientId(s);
+		organizationId = getOrgId(s);
+	} else if (s) {
+		actorId = s.userId;
+		organizationId = s.organizationId;
+	}
+	actorId = actorId ?? options.fallbackActorId;
+	if (!organizationId && options.orgHeader !== false && req.headers) {
+		const headerName = (options.orgHeader ?? "x-organization-id").toLowerCase();
+		const headerValue = requireSingleHeaderValue(req.headers, headerName);
+		if (typeof headerValue === "string" && headerValue.length > 0) organizationId = headerValue;
+	}
+	return {
+		...actorId !== void 0 ? { actorId } : {},
+		...organizationId !== void 0 ? { organizationId } : {}
+	};
+}
 /** Default public scope — used as initial decoration value */
 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 { 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 };
+export { isService as C, requireUserId as D, requireTeamId as E, scopeFirstCtx as O, 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-DH0GupI7.d.mts → types-DjC-KUCz.d.mts}

@@ -1,24 +1,39 @@
-//#region src/scope/types.d.ts
+//#region src/utils/headers.d.ts
 /**
- * Request Scope — The One Standard
- *
- * Discriminated union representing the access context of every request.
- * Replaces scattered orgScope/orgRoles/organizationId/bypassRoles.
- *
- * Set once by auth adapters, read everywhere by permissions/presets/guards.
+ * Canonical header typing + accessor.
+ *
+ * Node/Fastify header values are `string | string[] | undefined` — repeated
+ * headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+ * `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+ * adapter passes Fastify's headers object through unchanged, so `string[]`
+ * CAN appear at runtime behind the narrower type (the declared type is
+ * scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+ * through {@link getHeader} instead of indexing — it's honest about arrays
+ * and deterministic about duplicates.
+ */
+/** What a headers bag actually contains at runtime — HTTP or synthetic MCP. */
+type ArcHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Read a single header value. Lowercases the name (Node normalizes incoming
+ * header names to lowercase) and returns the FIRST value when the header
+ * was repeated.
+ *
+ * Duplicate policy: first-value is deterministic, but for security-sensitive
+ * headers (authorization material, forwarded-for chains, content-length) a
+ * duplicate usually signals smuggling or a broken proxy — consumers that
+ * care should check `Array.isArray(headers[name])` and REJECT instead of
+ * picking a winner.
+ */
+declare function getHeader(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+/**
+ * Read an identity-bearing or protocol header and reject repeated values.
  *
- * @example
- * ```typescript
- * // In a permission check
- * const scope = request.scope;
- * if (isElevated(scope)) return true;
- * if (isMember(scope) && scope.orgRoles.includes('admin')) return true;
- *
- * // Get user identity from scope
- * const userId = getUserId(scope);
- * const globalRoles = getUserRoles(scope);
- * ```
+ * Repeated security-sensitive headers are ambiguous at proxy boundaries and
+ * may indicate request smuggling. Callers must not silently choose a winner.
  */
+declare function requireSingleHeaderValue(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+//#endregion
+//#region src/scope/types.d.ts
 /**
  * A capability mandate — declarative, time-boxed, optionally cap-bounded
  * authorization for a single high-value action by an AI agent or service.
@@ -118,7 +133,9 @@ interface Mandate {
  * | elevated      | Platform admin, explicit elevation               |
  *
  * **Identity fields by kind:**
- * - `userId` / `userRoles` — available on `authenticated`, `member`, `elevated` (a real human)
+ * - `userId` — available on `authenticated`, `member`, `elevated` (a real human)
+ * - `userRoles` — available on `authenticated` and `member`; elevated scope
+ *   bypasses role gates explicitly and therefore does not carry role claims
  * - `clientId` — available on `service` (a machine identity, NOT a user)
  * - `organizationId` — required on `member` and `service`, optional on `elevated`
  * - `orgRoles` — org-level roles, only on `member` (from membership records)
@@ -517,9 +534,90 @@ declare function getOrgContext(request: {
 declare function getRequestScope(request: {
   scope?: RequestScope;
 }): RequestScope;
+/** Options for {@link scopeFirstCtx}. */
+interface ScopeFirstCtxOptions {
+  /**
+   * Tenant-selection header consulted ONLY when the scope carries no org —
+   * the custom-auth/public bridge (same semantics as `getTenantFromRequest`).
+   * A validated scope org always wins; the header never overrides it.
+   * Default `'x-organization-id'`; pass `false` to disable the bridge and
+   * read strictly from scope.
+   */
+  orgHeader?: string | false;
+  /**
+   * Actor id substituted when the scope carries no user/client identity
+   * (e.g. `'system'` / `'anonymous'`). When provided, the returned `actorId`
+   * narrows to `string`; omit to receive `actorId: undefined` on
+   * unauthenticated requests and apply your own policy.
+   */
+  fallbackActorId?: string;
+}
+/** Return shape of {@link scopeFirstCtx}. */
+interface ScopeFirstCtx {
+  actorId?: string;
+  organizationId?: string;
+}
+/**
+ * Request shape accepted by {@link scopeFirstCtx} — deliberately structural so
+ * ONE helper serves both surfaces:
+ * - a raw `FastifyRequest`, whose `scope` is the discriminated {@link RequestScope}
+ * - arc's `IRequestContext` (controller overrides, pipeline handlers, actions),
+ *   whose `scope` is the FLAT projection (`{ organizationId?, userId?, orgRoles? }`
+ *   lifted from `metadata._scope` — see `RequestScopeProjection`)
+ */
+interface ScopeFirstCtxRequest {
+  scope?: RequestScope | {
+    organizationId?: string | undefined;
+    userId?: string | undefined;
+    orgRoles?: string[] | undefined;
+  } | undefined;
+  /** `ArcHeaders` — readonly, repeated headers may arrive as arrays. Fastify's `IncomingHttpHeaders` assigns cleanly. */
+  headers?: ArcHeaders | undefined;
+}
+/**
+ * The ONE shared actor/org derivation for resource handlers and module
+ * packages (`arc-*` fleet) — scope-FIRST, per the canonical precedence:
+ *
+ * 1. `request.scope` (arc's validated `RequestScope`, set by auth adapters):
+ *    `userId` (human) or `clientId` (service) → `actorId`; `getOrgId(scope)`
+ *    → `organizationId`.
+ * 2. The `x-organization-id` header — ONLY when the scope carries no org.
+ *    This is the bridge for custom-auth/public routes where arc leaves scope
+ *    unpopulated; it never overrides a validated scope.
+ *
+ * Replaces per-package hand-rolled clones of
+ * `req.user?._id ?? req.user?.id ?? headers['x-organization-id']` — that
+ * pattern re-implements (and drifts from) arc's canonical resolution. A
+ * package's `ctxOf(req)` should call this for the shared
+ * `{ actorId, organizationId }` and only ADD its kernel-specific fields
+ * (`actorKind` / `correlationId` / `roles` / `idempotencyKey`).
+ *
+ * Structural request shape — works on a raw `FastifyRequest` AND on arc's
+ * `IRequestContext` (see {@link ScopeFirstCtxRequest}: the discriminated
+ * `RequestScope` and the flat controller projection are both understood).
+ *
+ * @example
+ * ```typescript
+ * import { scopeFirstCtx } from '@classytic/arc/scope';
+ *
+ * // Guaranteed actor (kernel context requires one):
+ * const { actorId, organizationId } = scopeFirstCtx(req, { fallbackActorId: 'system' });
+ *
+ * // Optional actor (package applies its own policy):
+ * const ctx = scopeFirstCtx(req);
+ * if (ctx.actorId) audit.record({ actor: ctx.actorId });
+ * ```
+ */
+declare function scopeFirstCtx(req: ScopeFirstCtxRequest, options: ScopeFirstCtxOptions & {
+  fallbackActorId: string;
+}): {
+  actorId: string;
+  organizationId?: string;
+};
+declare function scopeFirstCtx(req: ScopeFirstCtxRequest, options?: ScopeFirstCtxOptions): ScopeFirstCtx;
 /** Default public scope — used as initial decoration value */
 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 { 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 };
+export { requireOrgId as A, hasOrgAccess as C, isOrgInScope as D, isMember as E, getHeader as F, requireSingleHeaderValue as I, requireUserId as M, scopeFirstCtx as N, isService as O, ArcHeaders as P, getUserRoles as S, isElevated as T, getScopeContextMap as _, ScopeFirstCtx as a, getTenantFromRequest as b, getAncestorOrgIds as c, getMandate as d, getOrgContext as f, getScopeContext as g, getRequestScope as h, RequestScope as i, requireTeamId as j, requireClientId as k, getClientId as l, getOrgRoles as m, Mandate as n, ScopeFirstCtxOptions as o, getOrgId as p, PUBLIC_SCOPE as r, ScopeFirstCtxRequest as s, AUTHENTICATED_SCOPE as t, getDPoPJkt as u, getServiceScopes as v, isAuthenticated as w, getUserId as x, getTeamId as y };

package/dist/{types-Csxga7d3.d.mts → types-Dmw-6Qeo.d.mts}

@@ -1,5 +1,99 @@
-import { i as RequestScope } from "./types-DH0GupI7.mjs";
+import { i as RequestScope } from "./types-DjC-KUCz.mjs";
 import { FastifyRequest } from "fastify";
+//#region src/types/base.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    /** Request scope — set by auth adapter, read by permissions/presets/guards */
+    scope: RequestScope;
+    /**
+     * Current user — set by auth adapter (Better Auth, JWT, custom).
+     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
+     * Guard with `if (request.user)` on routes that allow anonymous access.
+     *
+     * Kept as required (not `user?`) because `@fastify/jwt` declares it
+     * as required — declaration merges must have identical modifiers.
+     * The `| undefined` in the type achieves the same DX.
+     */
+    user: Record<string, unknown> | undefined;
+    /** Policy-injected query filters (e.g. ownership, org-scoping) */
+    _policyFilters?: Record<string, unknown>;
+    /** Field mask — fields to include/exclude in responses */
+    fieldMask?: {
+      include?: string[];
+      exclude?: string[];
+    };
+    /** Arbitrary policy metadata for downstream consumers */
+    policyMetadata?: Record<string, unknown>;
+    /** Document loaded by policy middleware for ownership checks */
+    document?: unknown;
+    /** Ownership check context (field name + user field) */
+    _ownershipCheck?: Record<string, unknown>;
+  }
+}
+type AnyRecord = Record<string, unknown>;
+/** MongoDB ObjectId — accepts string or any object with a `toString()` (e.g. mongoose ObjectId). */
+type ObjectId = string | {
+  toString(): string;
+};
+/**
+ * Flexible user type that accepts any object with id/_id properties.
+ * The actual user structure is defined by your app's auth system.
+ */
+type UserLike = UserBase & {
+  /** User email (optional) */
+  email?: string;
+};
+interface UserOrganization {
+  userId: string;
+  organizationId: string;
+  [key: string]: unknown;
+}
+interface JWTPayload {
+  sub: string;
+  [key: string]: unknown;
+}
+/**
+ * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * instead of `(req as any).user`.
+ *
+ * @example
+ * ```typescript
+ * import type { ArcRequest } from '@classytic/arc';
+ *
+ * handler: async (req: ArcRequest, reply) => {
+ *   req.user?.id;                    // typed
+ *   req.scope.organizationId;        // typed (when member)
+ *   req.signal;                      // AbortSignal (Fastify 5)
+ * }
+ * ```
+ */
+type ArcRequest = FastifyRequest & {
+  scope: RequestScope;
+  user: Record<string, unknown> | undefined;
+  signal: AbortSignal;
+};
+//#endregion
+//#region src/utils/userHelpers.d.ts
+/**
+ * Extract a user ID from a user object. Accepts `id` or `_id` — returns
+ * `undefined` when neither is present. Used by arc's controllers to
+ * populate `createdBy` / `updatedBy` fields and for cache scoping.
+ *
+ * @example
+ * ```ts
+ * import { getUserId } from '@classytic/arc/utils';
+ * const uid = getUserId(request.user);
+ * ```
+ */
+declare function getUserId(user: UserLike | null | undefined): string | undefined;
+/** Normalize a raw role value from Better Auth, JWT, or a custom identity provider. */
+declare function normalizeRoles(value: unknown): string[];
+/** Extract normalized roles from a user-like object. */
+declare function getUserRoles(user: {
+  role?: unknown;
+  roles?: unknown;
+} | null | undefined): string[];
+//#endregion
 //#region src/permissions/types.d.ts
 /**
  * User base interface - minimal shape Arc expects
@@ -24,8 +118,6 @@ interface UserBase {
  * Normalize a raw role value (string, comma-separated string, or array) into a string[].
  * Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
  */
-declare function normalizeRoles(value: unknown): string[];
-declare function getUserRoles(user: UserBase | null | undefined): string[];
 /**
  * Context passed to permission check functions
  */
@@ -195,4 +287,4 @@ interface PermissionCheckMeta {
   };
 }
 //#endregion
-export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };
+export { getUserId as a, AnyRecord as c, ObjectId as d, UserLike as f, UserBase as i, ArcRequest as l, PermissionContext as n, getUserRoles as o, UserOrganization as p, PermissionResult as r, normalizeRoles as s, PermissionCheck as t, JWTPayload as u };

package/dist/{types-Bc42CUyk.d.mts → types-QFGc3Cjv.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-DbtgCOCj.mjs";
+import { V as ResourceDefinition } from "./index-DPRH0Cme.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -157,6 +157,41 @@ interface CrudDescriptionMeta {
  *   Arc's auto-derived filterable-fields blurb.
  */
 type CrudDescriptionOverride = string | ((meta: CrudDescriptionMeta) => string);
+/**
+ * Execution wiring for MCP tools — the app-level services HTTP requests
+ * receive via Fastify decorators (`fastify.arc.hooks`, `fastify.events`,
+ * `fastify.audit`, `fastify.log`, `fastify.idempotency`) and MCP's
+ * synthetic-context path historically dropped.
+ *
+ * When present, tool handlers thread it into the request context so the
+ * controller pipeline achieves FULL HTTP parity: resource hooks run
+ * (before/around/after), the arcCorePlugin after-hook publishes
+ * `<resource>.<op>d` events (→ realtime feeds, webhooks, event-driven
+ * cache invalidation all see MCP-originated mutations), `ctx.server.*`
+ * works inside handlers, and mutating CRUD tools accept an optional
+ * `_idempotencyKey` input for retry-safe execution.
+ *
+ * `mcpPlugin` builds this automatically from its Fastify instance (lazy
+ * getters — decorator registration order doesn't matter). Standalone
+ * `resourceToTools()` / `createMcpServer()` callers pass their own, or
+ * omit it to keep the legacy dispatch-only behavior.
+ */
+interface McpExecutionWiring {
+  /** Shared `HookSystem` — `fastify.arc.hooks`. */
+  readonly hooks?: unknown;
+  /** Event bus decorator — `fastify.events`. */
+  readonly events?: unknown;
+  /** Audit decorator — `fastify.audit`. */
+  readonly audit?: unknown;
+  /** Structured logger — `fastify.log`. */
+  readonly log?: unknown;
+  /**
+   * Idempotency store (the `IdempotencyStore` contract from
+   * `@classytic/arc/idempotency`). Presence advertises `_idempotencyKey`
+   * on mutating CRUD tools and enables executor-level check/lock/replay.
+   */
+  readonly idempotencyStore?: unknown;
+}
 /** Per-resource MCP configuration overrides */
 interface McpResourceConfig {
   /** Which CRUD operations to expose (default: all enabled on the resource) */
@@ -392,4 +427,4 @@ interface CreateMcpServerConfig {
 /** CRUD operation type */
 type CrudOperation = "list" | "get" | "create" | "update" | "delete";
 //#endregion
-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 };
+export { ToolDefinition as _, CrudDescriptionOverride as a, McpAuthResult as c, McpResourceConfig as d, PromptDefinition as f, ToolContext as g, ToolAnnotations as h, CrudDescriptionMeta as i, McpExecutionWiring as l, SessionEntry as m, CallToolResult as n, CrudOperation as o, PromptResult as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpPluginOptions as u };

package/dist/usage/index.d.mts

@@ -1,5 +1,6 @@
-import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { n as PermissionContext, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { i as RequestScope } from "../types-DjC-KUCz.mjs";
+import { n as PermissionContext, t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
+import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts
 interface QuotaOptions {
@@ -28,56 +29,6 @@ interface QuotaOptions {
 }
 declare function requireQuota(options: QuotaOptions): PermissionCheck;
 //#endregion
-//#region src/usage/stores/interface.d.ts
-/**
- * Usage store contract — period-bucketed counters per actor.
- *
- * CANONICAL HOME: `@classytic/repo-core/usage` (>=0.10) owns this
- * contract for the ecosystem — kits implement it there without ever
- * depending on arc (`@classytic/mongokit/usage`, ...). This file is a
- * deliberate STRUCTURAL MIRROR of that shape — same trick as
- * `ScheduleLockLike` vs repo-core's `LockAdapter` — so arc's emitted
- * declarations carry no repo-core@>=0.10 subpath reference and the
- * peer floor stays honest. Any conforming adapter assigns directly.
- *
- * The deliberately tiny surface (one increment, one read) is what makes
- * every backend trivial: memory (dev/tests), Redis (`HINCRBY`), or any kit
- * (Mongo `$inc` upsert) implements it in a handful of lines. Aggregation
- * happens IN the store — arc never buffers counters in process memory
- * beyond the built-in memory store, so multi-replica deployments stay
- * correct as long as the store is shared.
- *
- * This is the HORIZONTAL usage layer (per-actor, per-period platform
- * accounting for quotas/plans/billing). Itemized vertical records — e.g.
- * `@classytic/arc-ai/usage`'s per-run AI token/cost tracking — keep their
- * own richer stores and can sink into this one (`kind: 'ai.tokens'`).
- */
-/** One counter cell: (actor, period, kind). */
-interface UsageBucket {
-  /** Who consumed — org / user / client id, or an IP-derived fallback. */
-  actor: string;
-  /** Aggregation period, `YYYY-MM` (see `usagePeriod()`). */
-  period: string;
-  /** Namespaced counter, dot-separated: `api.requests`, `ai.tokens`, `storage.bytes`. */
-  kind: string;
-}
-interface UsageStore {
-  /** Store name for diagnostics (e.g. 'memory', 'redis', 'mongo'). */
-  readonly name: string;
-  /** Add `amount` to the bucket's counter, creating it at 0 first. MUST be atomic per bucket. */
-  increment(bucket: UsageBucket, amount: number): Promise<void> | void;
-  /** Every counter for an actor in a period: `{ 'api.requests': 40231, ... }`. */
-  summary(actor: string, period: string): Promise<Record<string, number>>;
-  /** Optional cleanup hook (connections, timers). */
-  close?(): Promise<void>;
-}
-/**
- * Canonical period key for a date — calendar month, UTC: `2026-07`.
- * Monthly is the billing-native granularity; stores that want finer
- * windows can shard internally without changing the contract.
- */
-declare function usagePeriod(date?: Date): string;
-//#endregion
 //#region src/usage/stores/memory.d.ts
 declare class MemoryUsageStore implements UsageStore {
   #private;