@classytic/arc 2.30.0 → 2.31.0

package/dist/testing/index.mjs

@@ -1,10 +1,13 @@
-import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { t as BaseController } from "../BaseController-B5DwufbB.mjs";
-import { t as defineResource } from "../defineResource-CxWqDCAy.mjs";
-import { t as defineAggregation } from "../defineAggregation-ufWjUwml.mjs";
-import { n as createApp } from "../createApp-CXrKFciH.mjs";
-import { n as getModuleExports } from "../module-_-M7C5ES.mjs";
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-DSY5HGpS.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as CRUD_OPERATIONS } from "../constants-D3Dv4LAV.mjs";
+import { g as getUserId } from "../types-Cys0ko9Z.mjs";
+import { t as BaseController } from "../BaseController-De7GqHck.mjs";
+import { t as defineResource } from "../defineResource-Bv6EtN1x.mjs";
+import { t as defineAggregation } from "../defineAggregation-DbPPS8RI.mjs";
+import { S as requireOrgRole } from "../permissions-L--QDAir.mjs";
+import { n as createApp } from "../createApp-Df89BEni.mjs";
+import { n as getModuleExports } from "../module-0pFJA6YW.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-Dz6BjzM6.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -304,18 +307,30 @@ function createSpy(_name = "spy") {
 	return spy;
 }
 /**
-* Wait for a condition to be true
+* Wait until `condition` holds — the standard way to assert on asynchronous
+* effects in arc's suites.
 *
-* Useful for async testing
+* **Prefer this over `await sleep(n)` + assert.** A fixed delay encodes a guess
+* about scheduling: too short and it flakes the moment the pool is busy, too
+* long and every run pays for the worst case. Polling returns as soon as the
+* effect lands, so the fast path stays fast and a loaded machine simply waits —
+* and the failure mode becomes "this never happened", which is the thing worth
+* asserting.
+*
+* Supply `label`: without it a timeout reports only its own duration, which is
+* the least useful sentence a flaky test can print.
+*
+* @example
+* await waitFor(() => runs >= 3, { label: "3 scheduler ticks" });
 */
 async function waitFor(condition, options = {}) {
-	const { timeout = 5e3, interval = 100 } = options;
+	const { timeout = 5e3, interval = 25, label } = options;
 	const startTime = Date.now();
 	while (Date.now() - startTime < timeout) {
 		if (await condition()) return;
 		await new Promise((resolve) => setTimeout(resolve, interval));
 	}
-	throw new Error(`Timeout waiting for condition after ${timeout}ms`);
+	throw new Error(label ? `Timed out after ${timeout}ms waiting for: ${label}` : `Timed out after ${timeout}ms waiting for a condition (pass "label" to name it)`);
 }
 /**
 * Create a test timer that can be controlled
@@ -363,6 +378,7 @@ function createTestTimer() {
 async function runAuthorizationConformance(opts) {
 	const rows = opts.rows ?? [{ _id: "1" }];
 	let listFilter;
+	let getFilter;
 	let aggFilter;
 	const repo = createMockRepository({
 		getAll: (async (params = {}) => {
@@ -378,6 +394,10 @@ async function runAuthorizationConformance(opts) {
 				hasPrev: false
 			};
 		}),
+		getOne: (async (filter) => {
+			getFilter = filter;
+			return rows[0] ?? null;
+		}),
 		aggregate: (async (req = {}) => {
 			aggFilter = req.filter;
 			return { rows: [{ tally: rows.length }] };
@@ -419,6 +439,10 @@ async function runAuthorizationConformance(opts) {
 		method: "GET",
 		url: "/confs"
 	});
+	const get = await app.inject({
+		method: "GET",
+		url: "/confs/1"
+	});
 	const aggregation = await app.inject({
 		method: "GET",
 		url: "/confs/aggregations/tally"
@@ -428,6 +452,10 @@ async function runAuthorizationConformance(opts) {
 			status: list.statusCode,
 			filter: listFilter
 		},
+		get: {
+			status: get.statusCode,
+			filter: getFilter
+		},
 		aggregation: {
 			status: aggregation.statusCode,
 			filter: aggFilter
@@ -775,6 +803,127 @@ async function setupBetterAuthTestApp(input) {
 	};
 }
 //#endregion
+//#region src/testing/testActor.ts
+/**
+* Test-only actor installation — how a package's HTTP tests say "run this
+* request as a manager in org X".
+*
+* Identity in arc comes from `request.scope` and only from `request.scope`;
+* headers like `x-role` are not identity. That rule left tests with no seam —
+* `bootModuleApp` boots with `auth: false`, so every injected request arrived as
+* `PUBLIC_SCOPE` and any role-gated route answered 401 with no supported way to
+* be somebody.
+*
+* The `x-test-actor` header is a TRANSPORT for the test's intent, not a trusted
+* claim. The authenticator that reads it is installed by `bootModuleApp` alone,
+* behind the `@classytic/arc/testing` entrypoint; `createApp` never registers
+* it, so no production build turns a forged header into identity. It is
+* per-request rather than boot-only because the interesting authorization tests
+* are the ones where a cashier is refused what a manager is allowed.
+*
+* Gate the routes under test with arc's own primitives — `requireRoles`,
+* `requireOrgMembership`, `allOf(...)`. A test-specific gate would be a second
+* implementation of authorization whose semantics could drift from the one
+* actually shipping.
+*/
+/** The header the testing harness uses to carry a request's actor. */
+const TEST_ACTOR_HEADER = "x-test-actor";
+/**
+* Build the headers that make an injected request act as `actor`.
+*
+* A string is shorthand for a single role. `null` means "stay public", so a test
+* can prove an endpoint is reachable anonymously.
+*
+* @example
+* ```ts
+* t.app.inject({ method: 'GET', url: '/pos/shifts/current',
+*   headers: testActorHeaders('manager', ORG) });
+* ```
+*/
+function testActorHeaders(actor, organizationId) {
+	if (actor === null) return {};
+	const org = organizationId !== void 0 ? { organizationId } : {};
+	const spec = typeof actor === "string" ? {
+		roles: [actor],
+		...org
+	} : {
+		...actor,
+		...org
+	};
+	return { [TEST_ACTOR_HEADER]: JSON.stringify(spec) };
+}
+/**
+* Turn a spec into a `RequestScope`.
+*
+* `orgRoles` defaults to `roles`: a test that says "manager" means it at both
+* levels, and making the caller repeat itself only produces tests that pass a
+* global gate and mysteriously fail an org one.
+*/
+function scopeFromTestActor(spec) {
+	const roles = spec.roles ?? [];
+	const userId = spec.userId ?? `test-${roles.join("-") || "anon"}`;
+	if (spec.elevated !== void 0 && spec.elevated !== false) return {
+		kind: "elevated",
+		userId,
+		elevatedBy: spec.elevated === true ? "test" : spec.elevated,
+		...spec.organizationId !== void 0 ? { organizationId: spec.organizationId } : {},
+		...spec.context !== void 0 ? { context: Object.freeze({ ...spec.context }) } : {}
+	};
+	if (spec.organizationId !== void 0) return {
+		kind: "member",
+		userId,
+		userRoles: roles,
+		organizationId: spec.organizationId,
+		orgRoles: spec.orgRoles ?? roles,
+		...spec.teamId !== void 0 ? { teamId: spec.teamId } : {},
+		...spec.context !== void 0 ? { context: Object.freeze({ ...spec.context }) } : {}
+	};
+	return {
+		kind: "authenticated",
+		userId,
+		userRoles: roles
+	};
+}
+/**
+* Build the `auth` option that makes the test actor arc's authenticator.
+*
+* It must be an authenticator, not a hook. Fastify encapsulates plugins and
+* modules register DURING `createApp`, so a hook added to the root instance
+* afterwards never runs for their routes — every request still resolves as
+* public and every role gate still answers 401, which reads exactly like a
+* broken authorization rule in the code under test. Registering as
+* `auth: { type: 'authenticator' }` puts the scope where arc's own auth would,
+* at the phase arc expects, so tenant filtering and permission checks behave
+* identically to production.
+*
+* `defaultActor` applies to requests carrying no header. A malformed header
+* REJECTS rather than falling back to public — a test that meant to be an admin
+* and got quietly demoted is the most expensive way to fail.
+*/
+function testActorAuth(defaultActor) {
+	const authenticate = async (request) => {
+		const req = request;
+		const raw = req.headers[TEST_ACTOR_HEADER];
+		let spec = defaultActor;
+		if (typeof raw === "string") try {
+			spec = JSON.parse(raw);
+		} catch {
+			throw new Error(`[arc-testing] malformed ${TEST_ACTOR_HEADER} header: ${raw}. Build it with testActorHeaders() rather than by hand.`);
+		}
+		if (spec === void 0) return;
+		req.scope = scopeFromTestActor(spec);
+		req.user = {
+			id: getUserId(req.scope) ?? "test-anon",
+			...spec.roles !== void 0 ? { role: spec.roles } : {},
+			...spec.organizationId !== void 0 ? { organizationId: spec.organizationId } : {}
+		};
+	};
+	return {
+		type: "authenticator",
+		authenticate
+	};
+}
+//#endregion
 //#region src/testing/bootModuleApp.ts
 /**
 * The built-in DB factory: in-memory MongoDB via lazy devDep imports.
@@ -807,7 +956,6 @@ async function bootModuleApp(modules, options = {}) {
 	const db = await (options.database ?? mongoMemoryDatabase)({ replset: options.replset ?? false });
 	const ctx = {
 		uri: db.uri,
-		mongoUri: db.uri,
 		connection: db.connection
 	};
 	const resolved = typeof modules === "function" ? await modules(ctx) : modules;
@@ -816,7 +964,17 @@ async function bootModuleApp(modules, options = {}) {
 	try {
 		app = await createApp({
 			preset: "testing",
-			auth: false,
+			/**
+			* The test actor is arc's AUTHENTICATOR rather than a bolted-on hook, so the scope
+			* lands at the phase the rest of the pipeline expects — tenant filtering and
+			* permission checks then behave exactly as they do in production.
+			*
+			* This replaces the old `auth: false`. The authenticator is inert for a request
+			* carrying no `x-test-actor` header and no configured default, so a suite that
+			* never mentions an actor behaves as it did before. `options.app` still wins, so a
+			* suite exercising real auth can override it.
+			*/
+			auth: testActorAuth(options.actor),
 			sensible: false,
 			...options.app,
 			modules: list
@@ -830,7 +988,6 @@ async function bootModuleApp(modules, options = {}) {
 	return {
 		app,
 		uri: db.uri,
-		mongoUri: db.uri,
 		connection: db.connection,
 		exports: (name) => getModuleExports(app, name),
 		close: async () => {
@@ -1156,6 +1313,63 @@ function createHttpTestHarness(resource, optionsOrGetter) {
 	return new HttpTestHarness(resource, optionsOrGetter);
 }
 //#endregion
+//#region src/testing/scopeRoleGate.ts
+/**
+* `scopeRoleGate` — the ONE role gate for package tests.
+*
+* ## Why this is in the framework
+*
+* Nine `@classytic/arc-*` packages had their own copy of this helper, and all nine were
+* wrong in the same two ways:
+*
+* 1. They read the role from an `x-role` HEADER and INSTALLED the request scope from
+*    inside the check — so identity came from the caller's own claim, and it arrived too
+*    late for arc's tenant-filtering pipeline to see it.
+* 2. They returned the pre-2.30 `{ granted: boolean }` shape, which is neither a boolean
+*    nor an `AuthorizationDecision`. It passed through `normalizeToDecision` untouched,
+*    arrived with `effect: undefined`, and was read as DENY — the gate said yes and arc
+*    refused anyway. Nothing type-errored, because the gate is cast at the call site.
+*
+* Two of the nine had already been fixed by hand, each with a docstring describing this
+* exact discovery. The knowledge reached neither of the other seven. That is the whole
+* case for a shared seam: a copy does not fail, it diverges.
+*
+* A test role gate is generic — "does the verified scope hold one of these roles" has no
+* domain in it — so it belongs here, beside the contract it depends on.
+*
+* Identity itself comes from `testActorHeaders()` + `bootModuleApp`'s authenticator
+* (see `testActor.ts`), which puts the scope where production puts it. This stays a pure
+* predicate over what arc verified.
+*
+* Kept in its own module rather than beside `testActor.ts` so the two can be edited
+* independently.
+*/
+/**
+* Grants iff the caller is an org member holding one of `allowed` as an ORG role.
+*
+* This is `requireOrgRole` under a name package tests reach for — deliberately a
+* delegation, not a reimplementation. It previously read `scope.userRoles` while
+* requiring an organization, so it disagreed with production for any actor whose
+* global and org roles differ: given
+* `{ roles: ["employee"], orgRoles: ["manager"], organizationId: "org-1" }`,
+* `requireOrgRole("manager")` allowed and this denied. The tests never caught it
+* because `scopeFromTestActor` defaults `orgRoles` to `roles`, making the two
+* dimensions identical for the common actor.
+*
+* Delegating also inherits the semantics a hand-rolled gate kept missing:
+* elevated scopes pass, and a service (API-key) identity is refused with a
+* message naming `requireServiceScope` instead of silently failing a role test.
+*
+* **Pair it with an org-bearing actor.** `testActorHeaders('manager', ORG)`
+* yields a `member` scope and passes; `testActorHeaders('manager')` yields an
+* `authenticated` scope with no tenant, which is refused — arc's generated CRUD
+* filters by tenant, so a gate that waves a tenant-less request through is how a
+* green test reads another org's rows.
+*/
+function scopeRoleGate(...allowed) {
+	return requireOrgRole(...allowed);
+}
+//#endregion
 //#region src/testing/testApp.ts
 /**
 * createTestApp — test app factory for arc
@@ -1221,7 +1435,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-CXrKFciH.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-Df89BEni.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;
@@ -1291,4 +1505,4 @@ function createMinimalTestApp(options = {}) {
 	});
 }
 //#endregion
-export { HttpTestHarness, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { HttpTestHarness, TEST_ACTOR_HEADER, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, scopeFromTestActor, scopeRoleGate, setupBetterAuthTestApp, testActorAuth, testActorHeaders, waitFor };

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-Q5gzEIWY.mjs";
-import { i as RequestScope } from "../types-DjC-KUCz.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-ChvvVNP8.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, 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, 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-ChvvVNP8.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
@@ -241,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 */
@@ -290,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 { 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-D_n8L6VY.d.mts → types-CBgvkp8O.d.mts}

@@ -1,5 +1,6 @@
-import { n as DomainEvent, 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
@@ -409,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[];
   /**
@@ -476,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[];
   /**
@@ -569,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-Bmmn-fO0.d.mts → types-CwcUQ610.d.mts}

@@ -1,4 +1,5 @@
-import { V as ResourceDefinition } from "./index-Q5gzEIWY.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 { i as PermissionContext, r as PermissionCheck } from "../types-ChvvVNP8.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