@classytic/arc 2.34.0 → 2.36.0

package/dist/{subscribe-helpers-CLIOHsOK.mjs → subscribe-helpers-B4fNHRNc.mjs}

@@ -1,61 +1,27 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { r as createEvent } from "./EventTransport-tq4CEB-q.mjs";
+/*! @classytic/arc v2.36.0 | MIT | https://classytic.com */
+import { r as createEvent } from "./EventTransport-D23Uvhg4.mjs";
 //#region src/events/defineEvent.ts
 /**
-* defineEvent — Typed Event Definitions with Optional Schema Validation
+* Typed event declarations, a registry for introspection, and `.create()` to
+* build a `DomainEvent` with generated metadata.
 *
-* Provides:
-* 1. defineEvent() — declare an event with name, schema, version, description
-* 2. EventRegistry — catalog of all known events + payload validation
-* 3. .create() helper — build DomainEvent with auto-generated metadata
-*
-* The built-in validator checks: object type, required fields, and top-level
-* property types. It does NOT recurse into nested objects, validate arrays,
-* enums, patterns, formats, or $ref. This is intentional — it's a lightweight
-* guard, not a full JSON Schema engine.
-*
-* For full validation, pass a custom `validate` function to `createEventRegistry()`:
-*
-* @example
-* ```typescript
-* import Ajv from 'ajv';
-* const ajv = new Ajv();
-*
-* const registry = createEventRegistry({
-*   validate: (schema, payload) => {
-*     const valid = ajv.validate(schema, payload);
-*     return valid
-*       ? { valid: true }
-*       : { valid: false, errors: ajv.errorsText().split(', ') };
-*   },
-* });
-* ```
+* The BUILT-IN validator is deliberately shallow: object type, required
+* fields, and top-level property types only. It does not recurse, nor handle
+* arrays, enums, patterns, formats, or `$ref` — it is a guard, not a JSON
+* Schema engine. Pass `validate` to `createEventRegistry()` to delegate to AJV
+* or similar when you need the real thing.
 *
 * @example
 * ```typescript
-* import { defineEvent, createEventRegistry } from '@classytic/arc/events';
-*
 * const OrderCreated = defineEvent({
 *   name: 'order.created',
 *   version: 1,
-*   schema: {
-*     type: 'object',
-*     properties: {
-*       orderId: { type: 'string' },
-*       total: { type: 'number' },
-*     },
-*     required: ['orderId', 'total'],
-*   },
+*   schema: { type: 'object', properties: { orderId: { type: 'string' } },
+*             required: ['orderId'] },
 * });
 *
-* // Type-safe event creation
-* const event = OrderCreated.create({ orderId: 'o-1', total: 100 });
+* const event = OrderCreated.create({ orderId: 'o-1' });
 * await fastify.events.publish(event.type, event.payload, event.meta);
-*
-* // Registry for introspection + validation
-* const registry = createEventRegistry();
-* registry.register(OrderCreated);
-* const result = registry.validate('order.created', payload);
 * ```
 */
 /**
@@ -171,9 +137,15 @@ function validatePayload(payload, schema) {
 				if (expectedType) {
 					const value = record[key];
 					const actualType = Array.isArray(value) ? "array" : typeof value;
-					if (expectedType === "integer") {
-						if (actualType !== "number" || !Number.isInteger(value)) errors.push(`Field '${key}': expected integer, got ${actualType}`);
-					} else if (expectedType !== actualType) errors.push(`Field '${key}': expected ${expectedType}, got ${actualType}`);
+					/**
+					* `type` may be a UNION (`['string','null']`) — that is how every
+					* nullable field compiles. Comparing the array to a `typeof` string
+					* is never equal, so a union-typed field failed for EVERY value it
+					* allows, and the array stringified into the message as the
+					* self-contradictory "expected string,null, got string".
+					*/
+					const allowed = Array.isArray(expectedType) ? expectedType : [expectedType];
+					if (!allowed.some((t) => t === "integer" ? actualType === "number" && Number.isInteger(value) : t === actualType)) errors.push(`Field '${key}': expected ${allowed.join(" | ")}, got ${actualType}`);
 				}
 			}
 		}

package/dist/sync/changelog.mjs

@@ -1,3 +1,3 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.36.0 | MIT | https://classytic.com */
 import { CursorExpiredError, MemoryChangeLogStore } from "@classytic/repo-core/sync";
 export { CursorExpiredError, MemoryChangeLogStore };

package/dist/testing/cleanupStoreContract.mjs

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

package/dist/testing/index.d.mts

@@ -1,10 +1,10 @@
 
-import { i as RequestScope } from "../types-ChuShpCP.mjs";
-import { l as PermissionCheck, t as AnyRecord } from "../base-Csjc2oF-.mjs";
-import { V as ResourceDefinition } from "../index-BcR2bFZQ.mjs";
-import { n as ArcModuleInput, o as ModuleDisposer, s as ModuleSetupContext } from "../types-BcTumAz_.mjs";
-import "../index-C5NnMEKF.mjs";
-import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-g07ldtzh.mjs";
+import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
+import { l as PermissionCheck, t as AnyRecord } from "../base-C-NL2fTi.mjs";
+import { V as ResourceDefinition } from "../index-C01wWGJt.mjs";
+import { n as ArcModuleInput, o as ModuleDisposer, s as ModuleSetupContext } from "../types-DDD5RKTu.mjs";
+import "../index-C50BUxKs.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-BuutdWgr.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { StandardRepo } from "@classytic/repo-core/repository";
 import { FastifyInstance, FastifyServerOptions } from "fastify";

package/dist/testing/index.mjs

@@ -1,13 +1,12 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { t as CRUD_OPERATIONS } from "../constants-BxCoxmiN.mjs";
-import { g as getUserId } from "../types-CoqIRrkY.mjs";
-import { t as BaseController } from "../BaseController-CbkuhNI2.mjs";
-import { t as defineResource } from "../defineResource-ZhuLonLm.mjs";
-import { t as defineAggregation } from "../defineAggregation-Nv-DwfOf.mjs";
-import { E as requireOrgRole } from "../permissions-CP47jdi7.mjs";
-import { r as createApp } from "../createApp-zR-DEesr.mjs";
-import { n as getModuleExports } from "../module-CwKsgZXp.mjs";
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-BkyqeTDz.mjs";
+/*! @classytic/arc v2.36.0 | MIT | https://classytic.com */
+import { t as CRUD_OPERATIONS } from "../constants-DUoKAGYD.mjs";
+import { g as getUserId } from "../types-B8lwJv9Q.mjs";
+import { t as BaseController } from "../BaseController-CTJKm6Cb.mjs";
+import { t as defineResource } from "../defineResource-DWzjyxb2.mjs";
+import { t as defineAggregation } from "../defineAggregation-CpQfcM8R.mjs";
+import { E as requireOrgRole } from "../permissions-DgPrZsJh.mjs";
+import { a as createApp, n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CjnW4iIX.mjs";
+import { n as getModuleExports } from "../module-CQNHzE7g.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -1505,7 +1504,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-zR-DEesr.mjs").then((n) => n.i);
+	const { createApp } = await import("../preloadResources-CjnW4iIX.mjs").then((n) => n.o);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/testing/outboxStoreContract.mjs

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

package/dist/testing/storageContract.mjs

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

package/dist/{transactionContext-BYtWnwAS.mjs → transactionContext-D2HwJM2z.mjs}

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

package/dist/{typeGuards-jjKJDN13.mjs → typeGuards-IE1laMDf.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.36.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,6 +1,6 @@
 
-import { i as RequestScope } from "../types-ChuShpCP.mjs";
-import { a as UserLike, c as DataPolicy, d as UserBase, i as ObjectId, l as PermissionCheck, n as ArcRequest, o as UserOrganization, r as JWTPayload, s as AuthorizationDecision, t as AnyRecord, u as PermissionContext } from "../base-Csjc2oF-.mjs";
-import { $ as OpenApiSchemas, A as RequestIdOptions, An as WriteVerbKey, At as RouteDefinition, C as RequestContext, D as HealthCheck, Dn as MutationWriteContext, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Fn as IControllerResponse, Ft as AuthPluginOptions, G as OnTenantDeleteConfig, H as CrudController, I as MiddlewareHandler, In as IRequestContext, It as Authenticator, J as PresetHook, K as ResolvedTenantPurge, L as RequestWithExtras, Ln as RawRouteHandler, Lt as AuthenticatorContext, M as EventsDecorator, Mn as ControllerLike, Mt as RouteMethod, N as FastifyRequestExtras, Nn as FastifyHandler, Nt as RateLimitConfig, O as HealthOptions, On as ResourceWrites, Ot as ActionHandlerFn, P as FastifyWithAuth, Pn as IController, Pt as AuthHelpers, Q as MiddlewareConfig, Rn as RouteHandler, Rt as JwtContext, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, W as ResourcePermissions, 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, jn as ControllerHandler, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as WriteContext, 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, 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, xn as BaseControllerOptions, y as OwnershipCheck, zt as TokenPair } from "../index-BcR2bFZQ.mjs";
+import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
+import { a as UserLike, c as DataPolicy, d as UserBase, i as ObjectId, l as PermissionCheck, n as ArcRequest, o as UserOrganization, r as JWTPayload, s as AuthorizationDecision, t as AnyRecord, u as PermissionContext } from "../base-C-NL2fTi.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, An as WriteVerbKey, At as RouteDefinition, C as RequestContext, D as HealthCheck, Dn as MutationWriteContext, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Fn as IControllerResponse, Ft as AuthPluginOptions, G as OnTenantDeleteConfig, H as CrudController, I as MiddlewareHandler, In as IRequestContext, It as Authenticator, J as PresetHook, K as ResolvedTenantPurge, L as RequestWithExtras, Ln as RawRouteHandler, Lt as AuthenticatorContext, M as EventsDecorator, Mn as ControllerLike, Mt as RouteMethod, N as FastifyRequestExtras, Nn as FastifyHandler, Nt as RateLimitConfig, O as HealthOptions, On as ResourceWrites, Ot as ActionHandlerFn, P as FastifyWithAuth, Pn as IController, Pt as AuthHelpers, Q as MiddlewareConfig, Rn as RouteHandler, Rt as JwtContext, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, W as ResourcePermissions, 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, jn as ControllerHandler, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as WriteContext, 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, 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, xn as BaseControllerOptions, y as OwnershipCheck, zt as TokenPair } from "../index-C01wWGJt.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, MutationWriteContext, 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, ResourceWrites, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, WriteContext, WriteVerbKey };

package/dist/types/index.mjs

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

package/dist/types/storage.mjs

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

package/dist/{types-CoqIRrkY.mjs → types-B8lwJv9Q.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-Cd_yy7aW.mjs";
-import { n as requireSingleHeaderValue } from "./headers-CveNO9gR.mjs";
-import { t as getUserId$1 } from "./userHelpers-CWF5pbZD.mjs";
+/*! @classytic/arc v2.36.0 | MIT | https://classytic.com */
+import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-DDKni6Tz.mjs";
+import { n as requireSingleHeaderValue } from "./headers-DKslnhey.mjs";
+import { t as getUserId$1 } from "./userHelpers-xQAi5bPF.mjs";
 //#region src/scope/types.ts
 /**
 * Request Scope — The One Standard
@@ -50,36 +50,10 @@ function getOrgId(scope) {
 	if (scope.kind === "elevated") return scope.organizationId;
 }
 /**
-* Resolve the tenant (organization) id from an incoming Fastify request,
-* walking the canonical sources in order: `request.scope` → `x-organization-id`
-* header. Returns `{ organizationId, source }` so callers can log or branch
-* on which path won.
+* Tenant id for a request, from its scope.
 *
-* Use in custom handlers that bypass arc's auto-CRUD path (worker routes,
-* batch importers, cross-engine subscribers) and therefore don't get the
-* tenant injected by `BaseCrudController`. Bridges arc's HTTP shape to
-* the mongokit/kit-side tenant context (e.g. `createTenantContext().run`).
-*
-* Header fallback is intentional: matches `resolveOrgFromHeader` semantics
-* for hosts that select an org via header instead of session/scope. Don't
-* reach for this when `getOrgId(scope)` alone is enough — for standard
-* authenticated routes the scope is already authoritative.
-*
-* @example
-* ```typescript
-* import { getTenantFromRequest } from '@classytic/arc/scope';
-* import { tenantContext } from './lib/mongokit.js';
-*
-* fastify.post('/statements/batch', async (req, reply) => {
-*   const { organizationId } = getTenantFromRequest(req);
-*   if (!organizationId) {
-*     return reply.code(400).send({ error: 'organizationId required' });
-*   }
-*   await tenantContext.run({ tenantId: organizationId }, async () => {
-*     await statementRepository.create(req.body);
-*   });
-* });
-* ```
+* Reads the SCOPE, never `request.user` — the two drift once elevation or a
+* service token is involved, and the scope is the resolved answer.
 */
 function getTenantFromRequest(req, options = {}) {
 	if (req.scope) {
@@ -374,27 +348,10 @@ function getOrgContext(request) {
 	};
 }
 /**
-* Read `request.scope` safely from any object that *might* have one.
-* Falls back to `PUBLIC_SCOPE` when the field is absent or undefined.
-*
-* This is the canonical way for permission checks, presets, and middleware
-* to read scope — never access `request.scope` directly because it can be
-* `undefined` on requests that haven't been touched by an auth adapter yet.
+* Read `request.scope`, falling back to `PUBLIC_SCOPE`.
 *
-* Accepts a structural shape (`{ scope?: RequestScope }`) instead of the
-* full Fastify request type so it can be called from any layer without
-* dragging in the Fastify type. The actual runtime is identical.
-*
-* @example
-* ```typescript
-* import { getRequestScope } from '@classytic/arc/scope';
-*
-* function myCheck(ctx: PermissionContext) {
-*   const scope = getRequestScope(ctx.request);
-*   if (isElevated(scope)) return true;
-*   // ...
-* }
-* ```
+* Never returns undefined: an absent scope means an unauthenticated request,
+* not a missing one, and callers must not have to distinguish those.
 */
 function getRequestScope(request) {
 	return request.scope ?? PUBLIC_SCOPE;

package/dist/{types-BfC83KsP.d.mts → types-BXnTOsXP.d.mts}

@@ -1,5 +1,5 @@
 
-import { V as ResourceDefinition } from "./index-BcR2bFZQ.mjs";
+import { V as ResourceDefinition } from "./index-C01wWGJt.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */

package/dist/{types-BcTumAz_.d.mts → types-DDD5RKTu.d.mts}

@@ -446,52 +446,23 @@ interface ArcModule<TExports = unknown> {
    */
   readonly dependsOn?: readonly string[];
   /**
-   * Infra SETUP function — the module-level analog of the app's `plugins()`
-   * slot. Runs in the plugins phase: AFTER the app's own `plugins()` (so
-   * module infra can build on app foundations like a DB connection) and in
-   * `dependsOn` order, but BEFORE any module `bootstrap` — so engines
-   * initialised in `bootstrap` can rely on what's registered here.
-   *
-   * ## ⚠ This is NOT itself a Fastify plugin
-   *
-   * Despite the name, arc CALLS this function directly — it is never handed
-   * to `fastify.register()`. Two consequences, both of which bite module
-   * authors coming from ordinary Fastify plugins:
-   *
-   *   - **You must register plugins yourself.** `await fastify.register(x)`,
-   *     not `return x`. A returned function is read as a DISPOSER (below),
-   *     so returning a plugin silently registers nothing and then invokes
-   *     your plugin as a teardown callback. Arc detects the `fastify-plugin`
-   *     case and throws; the bare-function case warns.
-   *   - **There is no encapsulation and no prefix here.** Decorators and
-   *     hooks you add land on the instance arc passes you — the same
-   *     instance every other module sees. Fastify's encapsulation applies
-   *     only inside a `register()` call you make yourself. See
-   *     https://fastify.dev/docs/latest/Reference/Plugins/
+   * Infra SETUP — the module analog of the app's `plugins()`. Runs after the
+   * app's own `plugins()`, in `dependsOn` order, before any module `bootstrap`.
    *
-   * ```ts
-   * plugins: async (fastify) => {
-   *   await fastify.register(somePlugin, { prefix: '/x' });  // ✅ register
-   *   fastify.decorate('thing', thing);                      // ✅ root-visible
-   *   // return somePlugin                                   // ❌ never registered
-   * },
-   * ```
+   * ⚠ NOT a Fastify plugin: arc CALLS it, never `register()`s it. So you
+   * register your own (`await fastify.register(x)`, not `return x` — a
+   * returned function is read as a DISPOSER), and there is no encapsulation
+   * or prefix: decorators land on the shared instance. Returning an `fp()`
+   * plugin throws; a bare multi-arg function warns.
    *
-   * The name is kept for the 2.x line; v3 renames the slot to `setup` and
-   * REMOVES `plugins` outright — v3 ships no compatibility aliases (v3.md).
-   *
-   * Separating this from `bootstrap` keeps lifecycle intent explicit for
-   * published ecosystem packages: `plugins` = "register infra"; `bootstrap` =
-   * "initialise engines (and return the public export)". Registering a plugin
-   * inside `bootstrap` still works — this slot just makes the two distinct.
-   *
-   * Receives `{ defer }` to register teardown for anything it acquires, and
-   * may RETURN a single disposer as shorthand for the one-resource case:
+   * Receives `{ defer }` for teardown, or return one disposer as shorthand.
+   * v3 renames this slot to `setup` with no alias (v3.md).
    *
    * ```ts
    * plugins: async (fastify) => {
+   *   await fastify.register(somePlugin, { prefix: '/x' });
    *   const conn = await connect();
-   *   return () => conn.close();          // equivalent to defer(...)
+   *   return () => conn.close();
    * },
    * ```
    */
@@ -550,53 +521,25 @@ interface ArcModule<TExports = unknown> {
    */
   bootstrap?: (fastify: FastifyInstance, context: ModuleSetupContext) => TExports | Promise<TExports>;
   /**
-   * App-level resource NAMES this module authoritatively SUPERSEDES. When the
-   * host also lists (or `resourceDir`-discovers) a resource of the same name,
-   * arc DROPS the app copy and registers THIS module's version instead — so the
-   * host keeps NO hand-maintained "which resources did modules take over" filter
-   * set. Ownership lives on the atom that provides it (colocated, drift-proof):
-   *
-   * ```ts
-   * defineModule({ name: "order", owns: ["order", "quotation", "rfq"], resources: () => [...] })
-   * ```
-   *
-   * Semantics:
-   *   - Purely a supersede-the-app-fork switch — it filters the *app* resource
-   *     list, never the module's own `resources` (those always register).
-   *   - 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.
-   *
-   * **Prefer `owns: "provided"`** (2.32) — arc derives the list from the
-   * resources this module actually returned, so the claim and the reality
-   * cannot disagree:
-   *
-   * ```ts
-   * defineModule({ name: "order", owns: "provided", resources: () => [...] })
-   * ```
-   *
-   * That is the whole arm for most modules. Resources are resolved exactly
-   * once, names are validated (duplicates within a module are rejected), the
-   * effective `owns` is derived, and supersession runs afterward — one atomic
-   * phase arc owns, rather than a rule each module re-states.
-   *
-   * **The explicit-array form is ENFORCED at boot: if you `owns` a name,
-   * PROVIDE it** — in THIS module's own `resources`. Arc 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 the list booted "successfully" with the app's route
-   * silently removed and nothing serving it. Two real cases, both silent 404s:
-   * a POS module claiming a checkout resource it mounted only when the host
-   * supplied a pipeline, and a device gateway claiming a name it never
-   * provided at all.
-   *
-   * Keep the explicit array only when the list is genuinely NOT the module's
-   * own resource set — e.g. pre-declaring a name before the fork exists.
-   *
-   * 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.
+   * App-level resource NAMES this module SUPERSEDES. When the host lists (or
+   * discovers) a resource of the same name, arc drops the app copy and
+   * registers this module's — so the host maintains no "which resources did
+   * modules take over" filter set.
+   *
+   * PREFER `owns: "provided"`: arc derives the list from the resources the
+   * module actually returned, so the claim cannot disagree with reality.
+   * Resources resolve once, names are validated, `owns` is derived, and
+   * supersession runs after — one phase arc owns.
+   *
+   * The explicit array is ENFORCED at boot: a claimed name must appear in THIS
+   * module's own `resources`, or boot fails naming the unmet names. Without
+   * that, a typo or a deleted resource booted "successfully" with the app's
+   * route removed and nothing serving it. A sibling module providing the name
+   * does NOT satisfy the claim — ownership is local to its declarer.
+   *
+   * It only filters the APP list, never the module's own resources; an entry
+   * matching no app resource is a silent no-op (a module may pre-declare a
+   * name before any fork exists). Collected across modules as a union.
    */
   readonly owns?: readonly string[] | "provided";
   /**

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

@@ -36,48 +36,17 @@ declare function requireSingleHeaderValue(headers: ArcHeaders | Record<string, s
 //#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.
+ * A capability mandate — time-boxed, optionally cap-bounded authorization for
+ * ONE high-value action by an agent or service.
  *
- * Models the **2025 agent-payments / agent-authorization conventions**:
- * - Google + Anthropic + Stripe **AP2** (Agent Payments Protocol)
- * - Stripe **x402 / Agentic Commerce**
- * - **MCP authorization** (RFC 9728 + RFC 9700 + RFC 9449)
+ * Where OAuth scopes answer "what may this client EVER do?", a mandate answers
+ * "what is THIS request authorized to do right now?" — narrower in capability,
+ * time, and value. Shape follows the 2025 agent-authorization conventions
+ * (AP2, x402, MCP authorization: RFC 9728/9700/9449).
  *
- * Where OAuth `scopes` answer "what can this client EVER do?", a mandate
- * answers "what is THIS REQUEST authorized to do RIGHT NOW?" — narrower in
- * capability, time, and value.
- *
- * Arc does **not** parse mandate JWTs / Verifiable Credentials — your
- * authenticate callback does (one `jose.jwtVerify()` or `did-jwt-vc.verify()`
- * call) and populates this object. Arc's `requireMandate(capability, opts)`
- * permission helper reads it and validates the action against the mandate's
- * declared bounds.
- *
- * @example
- * ```typescript
- * // Inbound: Authorization: Mandate eyJhbGc...
- * authenticate: async (request) => {
- *   const proof = request.headers['authorization']?.replace(/^Mandate /, '');
- *   const claims = await verifyMandate(proof);            // host's verifier
- *   request.scope = {
- *     kind: 'service',
- *     clientId: claims.iss,
- *     organizationId: claims.org,
- *     scopes: claims.scope?.split(' '),
- *     mandate: {
- *       id: claims.jti,
- *       capability: claims.cap,           // 'payment.charge' / 'inbox.send' / ...
- *       cap: claims.amount,               // numeric ceiling
- *       expiresAt: claims.exp * 1000,
- *       parent: claims.parent,            // delegated mandate chain
- *       audience: claims.aud,             // resource id mandate is bound to
- *     },
- *     dpopJkt: claims.cnf?.jkt,           // RFC 7638 — sender-constrained
- *   };
- *   return { id: claims.iss };
- * };
- * ```
+ * Arc does NOT verify mandate JWTs or VCs. The host's `authenticate` callback
+ * verifies and populates this object; `requireMandate(capability, opts)` then
+ * validates the action against its bounds.
  */
 interface Mandate {
   /** Mandate identifier — typically the JWT `jti` claim. */
@@ -252,36 +221,10 @@ declare function isAuthenticated(scope: RequestScope): boolean;
 /** Get organizationId from scope (member, service, or elevated — undefined otherwise) */
 declare function getOrgId(scope: RequestScope): string | undefined;
 /**
- * Resolve the tenant (organization) id from an incoming Fastify request,
- * walking the canonical sources in order: `request.scope` → `x-organization-id`
- * header. Returns `{ organizationId, source }` so callers can log or branch
- * on which path won.
- *
- * Use in custom handlers that bypass arc's auto-CRUD path (worker routes,
- * batch importers, cross-engine subscribers) and therefore don't get the
- * tenant injected by `BaseCrudController`. Bridges arc's HTTP shape to
- * the mongokit/kit-side tenant context (e.g. `createTenantContext().run`).
+ * Tenant id for a request, from its scope.
  *
- * Header fallback is intentional: matches `resolveOrgFromHeader` semantics
- * for hosts that select an org via header instead of session/scope. Don't
- * reach for this when `getOrgId(scope)` alone is enough — for standard
- * authenticated routes the scope is already authoritative.
- *
- * @example
- * ```typescript
- * import { getTenantFromRequest } from '@classytic/arc/scope';
- * import { tenantContext } from './lib/mongokit.js';
- *
- * fastify.post('/statements/batch', async (req, reply) => {
- *   const { organizationId } = getTenantFromRequest(req);
- *   if (!organizationId) {
- *     return reply.code(400).send({ error: 'organizationId required' });
- *   }
- *   await tenantContext.run({ tenantId: organizationId }, async () => {
- *     await statementRepository.create(req.body);
- *   });
- * });
- * ```
+ * Reads the SCOPE, never `request.user` — the two drift once elevation or a
+ * service token is involved, and the scope is the resolved answer.
  */
 declare function getTenantFromRequest(req: {
   scope?: RequestScope;
@@ -510,27 +453,10 @@ declare function getOrgContext(request: {
   orgRoles: string[];
 };
 /**
- * Read `request.scope` safely from any object that *might* have one.
- * Falls back to `PUBLIC_SCOPE` when the field is absent or undefined.
- *
- * This is the canonical way for permission checks, presets, and middleware
- * to read scope — never access `request.scope` directly because it can be
- * `undefined` on requests that haven't been touched by an auth adapter yet.
- *
- * Accepts a structural shape (`{ scope?: RequestScope }`) instead of the
- * full Fastify request type so it can be called from any layer without
- * dragging in the Fastify type. The actual runtime is identical.
+ * Read `request.scope`, falling back to `PUBLIC_SCOPE`.
  *
- * @example
- * ```typescript
- * import { getRequestScope } from '@classytic/arc/scope';
- *
- * function myCheck(ctx: PermissionContext) {
- *   const scope = getRequestScope(ctx.request);
- *   if (isElevated(scope)) return true;
- *   // ...
- * }
- * ```
+ * Never returns undefined: an absent scope means an unauthenticated request,
+ * not a missing one, and callers must not have to distinguish those.
  */
 declare function getRequestScope(request: {
   scope?: RequestScope;
@@ -576,38 +502,9 @@ interface ScopeFirstCtxRequest {
   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 });
- * ```
+ * Build a scope-first context for permission checks outside a Fastify request
+ * (jobs, MCP tools, workers). `scope` is the identity channel; `user` is
+ * derived for legacy checks that still read it.
  */
 declare function scopeFirstCtx(req: ScopeFirstCtxRequest, options: ScopeFirstCtxOptions & {
   fallbackActorId: string;

package/dist/usage/index.d.mts

@@ -1,6 +1,6 @@
 
-import { i as RequestScope } from "../types-ChuShpCP.mjs";
-import { l as PermissionCheck, u as PermissionContext } from "../base-Csjc2oF-.mjs";
+import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
+import { l as PermissionCheck, u as PermissionContext } from "../base-C-NL2fTi.mjs";
 import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts