@classytic/arc 2.28.0 → 2.31.0

package/dist/testing/outboxStoreContract.d.mts

@@ -1,3 +1,4 @@
+
 import { OutboxStore } from "@classytic/primitives/outbox";
 //#region src/testing/outboxStoreContract.d.ts
 interface OutboxStoreContractSetupResult {

package/dist/testing/outboxStoreContract.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { OutboxOwnershipError } from "@classytic/primitives/outbox";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 //#region src/testing/outboxStoreContract.ts

package/dist/testing/storageContract.d.mts

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

package/dist/testing/storageContract.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 //#region src/testing/storageContract.ts
 /**

package/dist/{tracing-CsGKQJGg.d.mts → tracing-Dro5eH6j.d.mts}

@@ -1,3 +1,4 @@
+
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Span, Tracer } from "@opentelemetry/api";
 //#region src/plugins/tracing.d.ts

package/dist/{transactionContext-PNdoyLLm.mjs → transactionContext-dAfBVUrk.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context/transactionContext.ts
 /**

package/dist/{typeGuards-C9KXUly6.mjs → typeGuards-B0ryPo3I.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/utils/typeGuards.ts
 /** Check if fastify has the events plugin registered */
 function hasEvents(instance) {

package/dist/types/index.d.mts

@@ -1,5 +1,6 @@
-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, 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 };
+
+import { $ as OpenApiSchemas, A as RequestIdOptions, An as BaseControllerOptions, At as RouteDefinition, Bt as RawRouteHandler, 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 Authenticator, H as CrudController, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, Jt as TokenPair, K as ResolvedTenantPurge, Kt as AuthenticatorContext, 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 AuthHelpers, Vt as RouteHandler, W as ResourcePermissions, Wt as AuthPluginOptions, 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, 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 JwtContext, 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-CpzxqePp.mjs";
+import { i as RequestScope } from "../types-ChuShpCP.mjs";
+import { a as UserBase, d as JWTPayload, f as ObjectId, i as PermissionContext, l as AnyRecord, m as UserOrganization, n as DataPolicy, p as UserLike, r as PermissionCheck, t as AuthorizationDecision, u as ArcRequest } from "../types-B7XeLEgK.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BXCfVcNG.mjs";
+export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, AuthorizationDecision, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, DataPolicy, 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, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RawRouteHandler, 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/index.mjs

@@ -1 +1,2 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 export {};

package/dist/types/storage.d.mts

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

package/dist/types/storage.mjs

@@ -1 +1,2 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 export {};

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

@@ -1,4 +1,5 @@
-import { i as RequestScope } from "./types-DjC-KUCz.mjs";
+
+import { i as RequestScope } from "./types-ChuShpCP.mjs";
 import { FastifyRequest } from "fastify";
 //#region src/types/base.d.ts
 declare module "fastify" {
@@ -53,7 +54,7 @@ interface JWTPayload {
   [key: string]: unknown;
 }
 /**
- * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * Typed Fastify request with Arc decorations. Use in `rawHandler` routes
  * instead of `(req as any).user`.
  *
  * @example
@@ -95,6 +96,56 @@ declare function getUserRoles(user: {
 } | null | undefined): string[];
 //#endregion
 //#region src/permissions/types.d.ts
+/**
+ * Row-level data policy — the constraint every returned/queried row must
+ * satisfy. This is arc's **Mongo-style record dialect** (`{ ownerId }`,
+ * `{ $or: [...] }`, `{ status: { $ne: "archived" } }`), the ONE canonical
+ * internal representation every permission helper emits and every enforcement
+ * seam composes (`conjoinPolicyFilters`).
+ *
+ * It is compiled to the portable repo-core `Filter` IR at the repository
+ * boundary (`core/repositoryFilter.ts` → `policyRecordToFilter`) so it runs
+ * identically on Mongo / SQL / any kit — arc's answer to oso-style "data
+ * filtering" + Postgres RLS, but datastore-portable and in-process. The IR is a
+ * boundary/compile concern, NOT the decision surface: keeping the decision in
+ * one record dialect means composition (`allOf`/`anyOf`/`conjoin`) has a single
+ * well-defined shape instead of a `Filter | Record` union the composer can't
+ * honor.
+ */
+type DataPolicy = Record<string, unknown>;
+/**
+ * The canonical authorization decision (arc 2.30). A single typed value that
+ * cleanly separates the concerns a permission check expresses:
+ *
+ *  - `effect` — allow / deny (Cedar / XACML decision)
+ *  - `reason` — human-readable diagnostic for the denial (explainability)
+ *  - `policy` — row-level {@link DataPolicy} to enforce at the repository
+ *  - `scope`  — identity/context to install on the request (PIP)
+ *
+ * Build one with the `allow()` / `deny()` constructors. A check may also return
+ * a bare `boolean` (terse allow/deny), normalized via `normalizeToDecision`.
+ *
+ * NOTE: arc deliberately does NOT model XACML-style "obligations" on the
+ * decision. Audit and field redaction are first-class arc subsystems already
+ * (`audit: true` on a resource; field-level read/write permissions), so an
+ * obligations channel would be a second, unenforced way to ask for the same
+ * effects. If a future need arises it will ship WITH a dispatcher that every
+ * enforcement surface runs — never as a declared-but-ignored contract.
+ */
+interface AuthorizationDecision {
+  /** Allow or deny. */
+  effect: "allow" | "deny";
+  /** Human-readable denial reason (surfaced in error messages / explain). */
+  reason?: string;
+  /** Row-level data policy to enforce at the repository layer. */
+  policy?: DataPolicy;
+  /**
+   * Scope to install on `request.scope` when allowed — flows to
+   * `metadata._scope` for tenant-field filtering. The clean integration point
+   * for custom auth (API keys, service accounts, gateway headers).
+   */
+  scope?: RequestScope;
+}
 /**
  * User base interface - minimal shape Arc expects
  * Your actual User can have any additional fields
@@ -107,25 +158,33 @@ interface UserBase {
   [key: string]: unknown;
 }
 /**
- * Extract normalized roles from a user object.
+ * Context passed to permission check functions.
  *
- * Reads `user.role` which can be:
- * - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
- * - A string array: `["admin", "user"]` (JWT / custom auth)
- * - A single string: `"admin"`
- */
-/**
- * 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.
- */
-/**
- * Context passed to permission check functions
+ * arc 2.30: checks read FACTS off this context — never off a raw request. Use
+ * `scopeOf(ctx)` (from `./context.js`) to read the scope; it prefers the
+ * first-class {@link PermissionContext.scope} and lets combinators thread an
+ * updated scope to child checks WITHOUT mutating the request. `request` is a
+ * transport escape hatch (present for HTTP; absent for MCP/jobs/ws) and is being
+ * retired as the primary channel.
  */
 interface PermissionContext<TDoc = Record<string, unknown>> {
   /** Authenticated user or null if unauthenticated */
   user: UserBase | null;
-  /** Fastify request object */
-  request: FastifyRequest;
+  /**
+   * Resolved request scope (identity + tenant/org context). First-class so
+   * combinators can thread an accumulated scope purely and non-HTTP transports
+   * need no request. Read via `scopeOf(ctx)`.
+   */
+  scope?: RequestScope;
+  /**
+   * Raw Fastify request — transport escape hatch, present ONLY on the HTTP
+   * surface. It is `undefined` for MCP, jobs, and any non-Fastify transport, so
+   * a permission check must NOT depend on it: read identity via `scopeOf(ctx)`,
+   * inputs via `ctx.data` / `ctx.params`, and host facts via `ctx.attributes`.
+   * Kept solely for genuinely HTTP-coupled checks (e.g. a usage meter on
+   * `request.server`) which are inherently transport-specific.
+   */
+  request?: FastifyRequest;
   /** Resource name being accessed */
   resource: string;
   /** Action being performed (list, get, create, update, delete, or custom operation name) */
@@ -136,93 +195,40 @@ interface PermissionContext<TDoc = Record<string, unknown>> {
   params?: Record<string, string>;
   /** Request body data */
   data?: Partial<TDoc> | Record<string, unknown>;
-}
-/**
- * Result from a permission check.
- *
- * Permission checks can do three things:
- * 1. **Grant or deny** access (`granted`, `reason`)
- * 2. **Attach row-level filters** (`filters`) — these merge into `_policyFilters`
- *    and narrow subsequent queries (e.g. `{ userId: ctx.user.id }` for ownership)
- * 3. **Install the request scope** (`scope`) — when a custom authenticator wants
- *    to set tenant/identity context directly from the permission layer, without
- *    relying on a separate auth plugin
- *
- * The `scope` field is the clean integration point for custom auth strategies
- * (API keys, service accounts, gateway headers). When present, Arc writes it to
- * `request.scope` which then flows through the normal tenant-filtering pipeline
- * (QueryResolver + AccessControl). This is the idiomatic way to wire non-Better-Auth
- * identity providers into Arc's multi-tenancy without touching the auth plugin layer.
- *
- * @example
- * ```typescript
- * // Custom API-key auth — grant access AND install a service scope in one step
- * export function requireApiKey(): PermissionCheck {
- *   return async ({ request }) => {
- *     const apiKey = request.headers['x-api-key'] as string | undefined;
- *     if (!apiKey) return { granted: false, reason: 'Missing API key' };
- *
- *     const client = await ClientModel.findOne({ apiKey });
- *     if (!client) return { granted: false, reason: 'Invalid API key' };
- *
- *     return {
- *       granted: true,
- *       // Install service scope — Arc writes this to request.scope automatically,
- *       // and tenantField filtering picks it up via metadata._scope
- *       scope: {
- *         kind: 'service',
- *         clientId: String(client._id),
- *         organizationId: String(client.companyId),
- *         scopes: client.allowedScopes,
- *       },
- *       // Optional row-level narrowing (e.g. per-project API keys)
- *       filters: client.projectId ? { projectId: client.projectId } : undefined,
- *     };
- *   };
- * }
- * ```
- */
-interface PermissionResult {
-  /** Whether access is granted */
-  granted: boolean;
-  /** Reason for denial (for error messages) */
-  reason?: string;
-  /** Query filters to apply (for ownership / row-level security patterns) */
-  filters?: Record<string, unknown>;
   /**
-   * Install this scope on `request.scope` when granted. Flows through to
-   * `metadata._scope` and is read by QueryResolver / AccessControl for
-   * tenant-field filtering. Use this to wire custom auth (API keys, service
-   * accounts, gateway headers) into Arc's multi-tenancy without a separate
-   * auth plugin.
+   * Transport/host-supplied attributes a check may need for ABAC decisions
+   * (headers, claims, feature flags) without reaching into the raw request.
    */
-  scope?: RequestScope;
+  attributes?: Readonly<Record<string, unknown>>;
 }
 /**
- * Permission Check Function
+ * Permission Check Function — THE way to define permissions in Arc.
  *
- * THE ONLY way to define permissions in Arc.
- * Returns boolean, PermissionResult, or Promise of either.
+ * Returns a `boolean` (terse allow/deny) or an {@link AuthorizationDecision}
+ * (effect + optional data `policy` and `scope`). Build decisions with the
+ * `allow()` / `deny()` constructors from `@classytic/arc/permissions`.
  *
  * @example
  * ```typescript
- * // Simple boolean return
+ * // Simple boolean
  * const isAdmin: PermissionCheck = (ctx) => getUserRoles(ctx.user).includes('admin');
  *
- * // With filters for ownership
- * const ownedByUser: PermissionCheck = (ctx) => ({
- *   granted: true,
- *   filters: { userId: ctx.user?.id }
- * });
+ * // Grant + row-level data policy (ownership)
+ * const ownedByUser: PermissionCheck = (ctx) =>
+ *   allow({ policy: { userId: ctx.user?.id } });
  *
- * // Async check
- * const canAccessOrg: PermissionCheck = async (ctx) => {
- *   const isMember = await checkMembership(ctx.user?.id, ctx.organizationId);
- *   return { granted: isMember, reason: isMember ? undefined : 'Not a member' };
+ * // Custom API-key auth — grant AND install a service scope
+ * const requireApiKey: PermissionCheck = async ({ request }) => {
+ *   const client = await lookup(request.headers['x-api-key']);
+ *   if (!client) return deny('Invalid API key');
+ *   return allow({
+ *     scope: { kind: 'service', clientId: String(client._id), organizationId: String(client.companyId) },
+ *     ...(client.projectId ? { policy: { projectId: client.projectId } } : {}),
+ *   });
  * };
  * ```
  */
-type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | AuthorizationDecision | Promise<boolean | AuthorizationDecision>) & PermissionCheckMeta;
 /**
  * Optional metadata attached to permission check functions.
  * Used for OpenAPI data, introspection, and route-level auth decisions.
@@ -236,8 +242,27 @@ type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionCont
 interface PermissionCheckMeta {
   /** Set by allowPublic() — marks the endpoint as publicly accessible */
   _isPublic?: boolean;
+  /**
+   * Set by requireAuth() — a pure identity gate (must be signed in) that adds NO
+   * row-level or environmental condition. Marked so `allOf` does not mistake it
+   * for an opaque runtime branch and needlessly taint the composite `conditional`.
+   */
+  _requiresAuth?: boolean;
   /** Set by requireRoles() — the roles required for access */
   _roles?: readonly string[];
+  /**
+   * Set by `requirePlatformRole()` — this gate consults PLATFORM roles only and
+   * can never be satisfied by an organization role.
+   *
+   * It exists because that property is otherwise unprovable from outside a
+   * check. `requireRoles(["ops"])` accepts an ORG role named `ops` by default,
+   * and `requireOrgRole("manager")` grants any org's manager — both return a
+   * bare allow with no policy, so a surface that must be platform-wide cannot
+   * tell them apart from a genuine operator gate by inspecting the decision.
+   * A global surface (see `jobsPlugin`'s `managementRoutes`) requires this
+   * marker at boot rather than trusting the caller's intent.
+   */
+  _platformOnly?: boolean;
   /** Set by requireOrgMembership() — org-level permission type */
   _orgPermission?: string;
   /** Set by requireOrgRole() — the org roles required for access */
@@ -285,6 +310,18 @@ interface PermissionCheckMeta {
     scopes?: readonly string[];
     dpop: boolean;
   };
+  /**
+   * Set by `allOf(...)` when its surfaced role/scope meta is NECESSARY but NOT
+   * SUFFICIENT — the conjunction also contains an opaque runtime branch
+   * (ownership / custom / dynamic / flow-mode / quota …) or a contradictory
+   * constraint that flat metadata can't capture. `describePermission` propagates
+   * it as `conditional: true`, so `explainAccess` reports a role/scope MATCH as
+   * `conditional` (server decides) instead of a definitive — and unsound —
+   * `allow`. A role/scope MISMATCH is still a definitive `deny` (a necessary
+   * condition failed). Without this flag a composed gate could tell a UI "you can"
+   * when the runtime check will refuse.
+   */
+  _conditional?: boolean;
 }
 //#endregion
-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 };
+export { UserBase as a, normalizeRoles as c, JWTPayload as d, ObjectId as f, PermissionContext as i, AnyRecord as l, UserOrganization as m, DataPolicy as n, getUserId as o, UserLike as p, PermissionCheck as r, getUserRoles as s, AuthorizationDecision as t, ArcRequest as u };

package/dist/{types-Cc91nXuA.d.mts → types-ByHn9rEO.d.mts}

@@ -1,3 +1,4 @@
+
 import { FastifyRequest } from "fastify";
 //#region src/encryption/types.d.ts
 /** JWE key-management algorithm — the protected-header `alg`. */

package/dist/{types-C_ZZRcD6.d.mts → types-C4QE8qnm.d.mts}

@@ -1,3 +1,4 @@
+
 import { PurgeActor, PurgeEvidence, PurgeResourceResult, PurgeStrategyKind as PurgeStrategyKind$1, PurgeVerificationSummary } from "@classytic/primitives/retention";
 //#region src/cleanup/types.d.ts
 /** Ambient context every recipe method receives. Host-injected — never global. */

package/dist/{types-Cu6vVJmh.d.mts → types-CBgvkp8O.d.mts}

@@ -1,5 +1,6 @@
-import { r as EventHandler } from "./EventTransport-QmY7A258.mjs";
-import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
+
+import { n as DomainEvent, r as EventHandler } from "./EventTransport-2uVV34WU.mjs";
+import { n as ErrorMapper } from "./errorHandler-CpYUJmPA.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import { LockAdapter } from "@classytic/repo-core/lock";
 //#region src/plugins/health.d.ts
@@ -343,6 +344,37 @@ interface EventHandlerDefinition {
    * `inventory.order-created`; Arc does not silently rewrite public names.
    */
   name?: string;
+  /**
+   * Contain handler failures inside an error boundary — arc wraps `handler`
+   * with `wrapWithBoundary`, so a throw is logged (through `fastify.log`, with
+   * `{ err, event, eventId, handler }`) and swallowed instead of reaching the
+   * transport.
+   *
+   * **Off by default, deliberately.** Reaching the transport is what makes the
+   * durable path work: `RedisStreamTransport` leaves the message unacked, so it
+   * is redelivered and eventually DLQ'd. Silently swallowing by default would
+   * turn every module handler into best-effort delivery.
+   *
+   * Turn it ON for fire-and-forget work — projections, cache invalidation,
+   * notification fan-out — where a failure must not block the ack and a retry
+   * would only delay the next event's resync. That is precisely the case where
+   * a module author would otherwise abandon this arm for an imperative
+   * `subscribeWithBoundary` call in `afterResources` and lose arc's
+   * teardown-before-`onClose` guarantee.
+   *
+   * ```ts
+   * defineModule({ name: "search", eventHandlers: [
+   *   { name: "search.reindex", event: "product:*", handler: reindex, boundary: true },
+   * ] })
+   * ```
+   *
+   * The object form adds an `onError` sink (metrics / alerting) in place of the
+   * default log; it runs INSIDE the boundary, so a throwing `onError` is itself
+   * caught and logged rather than escaping.
+   */
+  boundary?: boolean | {
+    onError?: (error: Error, event: DomainEvent) => void | Promise<void>;
+  };
 }
 interface ArcModule<TExports = unknown> {
   /** Stable identifier — appears in boot logs and duplicate-module detection. */
@@ -378,6 +410,13 @@ interface ArcModule<TExports = unknown> {
    * *importing* a dependent until its dependency is ready. Use a thunk to gate
    * whether a module is imported at all (region/tier packs); use `dependsOn`
    * to order modules that are already selected.
+   *
+   * **Convention: every HARD sibling dependency belongs here** — including
+   * ones read lazily. `lazyRequiredModuleExports` defers the export READ to
+   * first use (and eagerly validates the module is composed), but only
+   * `dependsOn` orders composition so the sibling's engine exists before
+   * yours initializes. Omit the edge only for genuinely optional
+   * integrations (`lazyModuleExports` / `getOptionalModuleExports`).
    */
   readonly dependsOn?: readonly string[];
   /**
@@ -445,15 +484,21 @@ interface ArcModule<TExports = unknown> {
    * Semantics:
    *   - Purely a supersede-the-app-fork switch — it filters the *app* resource
    *     list, never the module's own `resources` (those always register).
-   *   - Static + declarative: read at compose time, so it works regardless of
-   *     whether `resources` is an array or a post-bootstrap factory (no early
-   *     factory resolution, no boot-order coupling).
-   *   - Idempotent + tolerant: an `owns` entry with no matching app resource is
-   *     a silent no-op — a module may pre-declare a name before any fork exists.
+   *   - Idempotent + tolerant on the APP side: an `owns` entry with no matching
+   *     app resource is a silent no-op — a module may pre-declare a name before
+   *     any fork exists.
    *   - Collected across ALL modules; the app-side supersession is their union.
    *
-   * Contract: if you `owns` a name, PROVIDE it (in this module's `resources`).
-   * Dropping the app fork without supplying a replacement removes the route.
+   * **Contract (ENFORCED at boot): if you `owns` a name, PROVIDE it** — in
+   * THIS module's own `resources`. Arc resolves module resources first and
+   * fails boot when a claimed name is not among them, naming the module, the
+   * unmet names, and what it did supply. Without that check, a typo or a
+   * resource deleted without updating `owns` booted "successfully" with the
+   * app's route silently removed and nothing serving it.
+   *
+   * A sibling module supplying the name does NOT satisfy the claim — ownership
+   * is local to the module that declares it, which is the colocation this arm
+   * exists for.
    */
   readonly owns?: readonly string[];
   /**
@@ -538,9 +583,34 @@ interface ArcModule<TExports = unknown> {
    */
   readonly scheduledJobs?: ModuleContribution<ScheduleDefinition>;
   /**
-   * Teardown — registered as a Fastify `onClose` hook. Destroy engines, stop
-   * timers, flush the module's outbox. Modules close in REVERSE list order
-   * (last composed, first closed), mirroring init.
+   * Teardown — destroy engines, stop timers, flush the module's outbox.
+   * Modules close in REVERSE composition order (last composed, first closed),
+   * mirroring init, BEFORE the app-level `onClose` and before infra plugins'
+   * own close hooks (so teardown still sees a live DB/Redis).
+   *
+   * Boot is transactional: if any phase fails mid-boot — including THIS
+   * module's own `plugins`/`bootstrap` — arc immediately closes every module
+   * that entered an init phase, this closer included, in reverse order, then
+   * rethrows the original boot error. A closer runs AT MOST ONCE across the
+   * rollback and shutdown paths, and one throwing closer never blocks the
+   * rest (best-effort; failures are logged).
+   *
+   * Because rollback fires after a PARTIAL init — your `bootstrap` opened a
+   * client and threw on the next line, or your `plugins` ran but `bootstrap`
+   * never did — write closers defensively. Guard everything init may not have
+   * reached: `client?.close()`, not `client.close()`.
+   *
+   * ```ts
+   * let client: Client | undefined;
+   * defineModule({
+   *   name: "billing",
+   *   bootstrap: async () => {
+   *     client = await openClient();   // allocated…
+   *     await migrate(client);         // …and this may throw
+   *   },
+   *   onClose: async () => { await client?.close(); },  // still runs
+   * });
+   * ```
    */
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }

package/dist/{types-DjC-KUCz.d.mts → types-ChuShpCP.d.mts}

@@ -1,3 +1,4 @@
+
 //#region src/utils/headers.d.ts
 /**
  * Canonical header typing + accessor.

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

@@ -1,4 +1,5 @@
-import { V as ResourceDefinition } from "./index-DPRH0Cme.mjs";
+
+import { V as ResourceDefinition } from "./index-CpzxqePp.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -306,11 +307,6 @@ interface McpPluginOptions {
    * ```
    */
   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;
   /** Per-resource overrides (operations, descriptions, hideFields, names, toolNamePrefix) */

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

@@ -1,6 +1,7 @@
-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";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-Cj42AntO.mjs";
+import { n as requireSingleHeaderValue } from "./headers-3zvE0rM3.mjs";
+import { t as getUserId$1 } from "./userHelpers-ChYJ6CdK.mjs";
 //#region src/scope/types.ts
 /**
 * Request Scope — The One Standard

package/dist/usage/index.d.mts

@@ -1,5 +1,6 @@
-import { i as RequestScope } from "../types-DjC-KUCz.mjs";
-import { n as PermissionContext, t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
+
+import { i as RequestScope } from "../types-ChuShpCP.mjs";
+import { i as PermissionContext, r as PermissionCheck } from "../types-B7XeLEgK.mjs";
 import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts

package/dist/{userHelpers-Cg_y3fBz.mjs → userHelpers-ChYJ6CdK.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/utils/userHelpers.ts
 /**
 * Extract a user ID from a user object. Accepts `id` or `_id` — returns

package/dist/utils/index.d.mts

@@ -1,8 +1,9 @@
-import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-DPRH0Cme.mjs";
-import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-DjC-KUCz.mjs";
-import { a as getUserId, c as AnyRecord, o as getUserRoles, s as normalizeRoles } from "../types-Dmw-6Qeo.mjs";
-import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
+
+import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-CpzxqePp.mjs";
+import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-ChuShpCP.mjs";
+import { c as normalizeRoles, l as AnyRecord, o as getUserId, s as getUserRoles } from "../types-B7XeLEgK.mjs";
+import { n as ErrorMapper } from "../errorHandler-CpYUJmPA.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-BGdVwP25.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { scheduleBackground } from "@classytic/repo-core/cache";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
@@ -1113,6 +1114,11 @@ declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>
  * - `openapi-3.1`: OpenAPI 3.1 document generation
  */
 type JsonSchemaTarget = "draft-7" | "draft-2020-12" | "openapi-3.0" | "openapi-3.1";
+/**
+ * Which of a Zod schema's two shapes to emit. See the module docblock — this is
+ * the difference between accepting and rejecting a legal request.
+ */
+type SchemaIo = "input" | "output";
 /**
  * Check if an object is already a plain JSON Schema.
  * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
@@ -1152,8 +1158,11 @@ type UnconvertibleMode = "warn" | "throw";
  *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
  * @param mode   Failure policy for unconvertible Zod schemas — see
  *               {@link UnconvertibleMode}. Defaults to `'warn'`.
+ * @param io     Which shape to emit — see {@link SchemaIo} and the module
+ *               docblock. Defaults to `'output'`, matching Zod's own default;
+ *               arc's request-side call sites pass `'input'` explicitly.
  */
-declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode): Record<string, unknown> | undefined;
+declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode, io?: SchemaIo): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
@@ -1313,9 +1322,6 @@ interface StateMachine {
    * Record a transition
    */
   recordTransition?(from: string, to: string, action: string, metadata?: Record<string, unknown>): void;
-  /**
-   * Clear history
-   */
   clearHistory?(): void;
   /**
    * Get available actions for current status
@@ -1508,4 +1514,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };
+export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, type SchemaIo, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };