@classytic/arc 2.11.4 → 2.13.1

package/dist/scope/index.d.mts

@@ -1,5 +1,5 @@
-import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types-DDyTPc6y.mjs";
-import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-BQQXZ_VR.mjs";
+import { C as isOrgInScope, D as requireTeamId, E as requireOrgId, O as requireUserId, S as isMember, T as requireClientId, _ as getUserId, a as getAncestorOrgIds, b as isAuthenticated, c as getMandate, d as getOrgRoles, f as getRequestScope, g as getTeamId, h as getServiceScopes, i as RequestScope, l as getOrgContext, m as getScopeContextMap, n as Mandate, o as getClientId, p as getScopeContext, r as PUBLIC_SCOPE, s as getDPoPJkt, t as AUTHENTICATED_SCOPE, u as getOrgId, v as getUserRoles, w as isService, x as isElevated, y as hasOrgAccess } from "../types-CTYvcwHe.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-BXOWoGCF.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/scope/rateLimitKey.d.ts
@@ -30,4 +30,4 @@ interface ResolveOrgFromHeaderOptions {
  */
 declare function resolveOrgFromHeader(options: ResolveOrgFromHeaderOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
-export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, PUBLIC_SCOPE, type RateLimitKeyContext, type RequestScope, type ResolveOrgFromHeaderOptions, type TenantKeyGeneratorOptions, createTenantKeyGenerator, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, type Mandate, PUBLIC_SCOPE, type RateLimitKeyContext, type RequestScope, type ResolveOrgFromHeaderOptions, type TenantKeyGeneratorOptions, createTenantKeyGenerator, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };

package/dist/scope/index.mjs

@@ -1,6 +1,6 @@
-import { _ as isElevated, a as getOrgContext, b as isService, c as getRequestScope, d as getServiceScopes, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, i as getClientId, l as getScopeContext, m as getUserRoles, n as PUBLIC_SCOPE, o as getOrgId, p as getUserId, r as getAncestorOrgIds, s as getOrgRoles, t as AUTHENTICATED_SCOPE, u as getScopeContextMap, v as isMember, y as isOrgInScope } from "../types-AOD8fxIw.mjs";
-import { n as normalizeRoles } from "../types-DV9WDfeg.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-DOFoxoDs.mjs";
+import { C as requireClientId, E as requireUserId, S as isService, T as requireTeamId, _ as hasOrgAccess, a as getDPoPJkt, b as isMember, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserRoles, h as getUserId, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as isAuthenticated, w as requireOrgId, x as isOrgInScope, y as isElevated } from "../types-C_s5moIu.mjs";
+import { n as normalizeRoles } from "../types-D57iXYb8.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-DgoeTyfX.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;
@@ -76,4 +76,4 @@ function resolveOrgFromHeader(options) {
 	};
 }
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };

package/dist/{sse-V7aXc3bW.mjs → sse-Bz-5ZeTt.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE, o as getOrgId } from "./types-AOD8fxIw.mjs";
+import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-C_s5moIu.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/{store-helpers-Cp4uKC1U.mjs → store-helpers-BkIN9-vu.mjs}

@@ -1,4 +1,4 @@
-//#region src/adapters/store-helpers.ts
+//#region src/utils/store-helpers.ts
 /**
 * Classify an error thrown by `getOne` / `getById` / `update` as a
 * "document not found" miss. Mongokit uses `status: 404`, Prisma uses

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { B as ResourceDefinition, Pt as AnyRecord } from "../index-CXXRbnf8.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-D7KpfiL1.mjs";
+import { V as ResourceDefinition, Wt as AnyRecord } from "../index-BtW7qYwa.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-BvqwCCSx.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
@@ -349,12 +349,6 @@ declare class HttpTestHarness<T = unknown> {
   private resource;
   private optionsOrGetter;
   private enabledRoutes;
-  /**
-   * Update verbs exercised by this harness instance. One entry for single-method
-   * resources (`"PATCH"` or `"PUT"`), two for `updateMethod: "both"` so both
-   * verbs are covered — the framework mounts both, and the harness should
-   * probe both.
-   */
   private updateMethods;
   constructor(resource: ResourceDefinition<unknown>, optionsOrGetter: OptionsOrGetter<T>);
   private getOptions;

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { t as CRUD_OPERATIONS } from "../constants-BhY1OHoH.mjs";
+import { t as CRUD_OPERATIONS } from "../constants-Cxde4rpC.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -49,13 +49,13 @@ function expectArc(response) {
 		},
 		ok(status = 200) {
 			expect(response.statusCode, `expected 2xx (${status}) but got ${response.statusCode}. Body: ${response.body.slice(0, 200)}`).toBe(status);
-			expect(getBody().success).toBe(true);
+			getBody();
 			return assertion;
 		},
 		failed(status) {
 			if (status !== void 0) expect(response.statusCode).toBe(status);
 			else expect(response.statusCode).toBeGreaterThanOrEqual(400);
-			expect(getBody().success).toBe(false);
+			expect(getBody().code, "expected ErrorContract.code on failed response").toBeDefined();
 			return assertion;
 		},
 		unauthorized() {
@@ -74,7 +74,8 @@ function expectArc(response) {
 			return assertion.failed(409);
 		},
 		hasData() {
-			expect(getBody().data, "expected body.data to be defined").toBeDefined();
+			const body = getBody();
+			expect(Object.keys(body).length > 0, "expected response body to be defined").toBe(true);
 			return assertion;
 		},
 		hasStatus(status) {
@@ -82,22 +83,17 @@ function expectArc(response) {
 			return assertion;
 		},
 		hidesField(field) {
-			const data = getBody().data;
-			expect(data, "expected body.data to be defined before field check").toBeDefined();
-			expect(data, `expected field '${field}' to be hidden from response.data`).not.toHaveProperty(field);
+			expect(getBody(), `expected field '${field}' to be hidden from response`).not.toHaveProperty(field);
 			return assertion;
 		},
 		showsField(field) {
-			const data = getBody().data;
-			expect(data, "expected body.data to be defined before field check").toBeDefined();
-			expect(data, `expected field '${field}' on response.data`).toHaveProperty(field);
+			expect(getBody(), `expected field '${field}' on response`).toHaveProperty(field);
 			return assertion;
 		},
 		paginated(expected) {
 			const body = getBody();
-			expect(body.success).toBe(true);
-			const docs = body.docs ?? (Array.isArray(body.data) ? body.data : void 0);
-			expect(Array.isArray(docs), "expected `docs[]` (or `data[]`) on paginated response").toBe(true);
+			const data = body.data;
+			expect(Array.isArray(data), "expected `data[]` array on paginated response").toBe(true);
 			if (expected?.page !== void 0) expect(body.page).toBe(expected.page);
 			if (expected?.limit !== void 0) expect(body.limit).toBe(expected.limit);
 			if (expected?.total !== void 0) expect(body.total).toBe(expected.total);
@@ -107,8 +103,8 @@ function expectArc(response) {
 		},
 		hasError(matcher) {
 			const body = getBody();
-			const errorField = body.error ?? body.message;
-			expect(errorField, "expected body.error or body.message to be set").toBeDefined();
+			const errorField = body.message ?? body.error;
+			expect(errorField, "expected body.message (or body.error) to be set").toBeDefined();
 			if (typeof matcher === "string") expect(errorField).toBe(matcher);
 			else expect(errorField).toMatch(matcher);
 			return assertion;
@@ -520,12 +516,6 @@ var HttpTestHarness = class {
 	resource;
 	optionsOrGetter;
 	enabledRoutes;
-	/**
-	* Update verbs exercised by this harness instance. One entry for single-method
-	* resources (`"PATCH"` or `"PUT"`), two for `updateMethod: "both"` so both
-	* verbs are covered — the framework mounts both, and the harness should
-	* probe both.
-	*/
 	updateMethods;
 	constructor(resource, optionsOrGetter) {
 		this.resource = resource;
@@ -588,7 +578,7 @@ var HttpTestHarness = class {
 				expect(res.statusCode).toBe(200);
 				const body = JSON.parse(res.body);
 				expect(body.success).toBe(true);
-				const list = body.data ?? body.docs;
+				const list = body.data ?? body.data;
 				expect(Array.isArray(list)).toBe(true);
 			});
 			if (enabledRoutes.has("get")) {
@@ -792,7 +782,7 @@ function createMockRepository(overrides = {}) {
 	return {
 		getAll: vi.fn().mockResolvedValue({
 			method: "offset",
-			docs: [],
+			data: [],
 			total: 0,
 			page: 1,
 			limit: 20,
@@ -822,6 +812,8 @@ function createMockRepository(overrides = {}) {
 			acknowledged: true,
 			deletedCount: 0
 		}),
+		claim: vi.fn().mockResolvedValue(null),
+		claimVersion: vi.fn().mockResolvedValue(null),
 		getBySlug: vi.fn().mockResolvedValue(null),
 		getDeleted: vi.fn().mockResolvedValue([]),
 		restore: vi.fn().mockResolvedValue(null),
@@ -1081,7 +1073,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-C9bRrqlX.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-XX2-N0Yd.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OpenApiSchemas, A as RequestIdOptions, At as Authenticator, Bt as UserOrganization, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Ft as ApiResponse, G as ActionsMap, H as ActionDefinition, I as MiddlewareHandler, It as ArcRequest, J as CrudRouteKey, K as ArcFieldRule, L as RequestWithExtras, Lt as JWTPayload, M as EventsDecorator, Mt as JwtContext, N as FastifyRequestExtras, Nt as TokenPair, O as HealthOptions, Ot as AuthHelpers, P as FastifyWithAuth, Pt as AnyRecord, Q as MiddlewareConfig, Rt as ObjectId, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, W as ActionHandlerFn, X as EventDefinition, Y as CrudSchemas, Z as FieldRule, _ as ControllerQueryOptions, _t as IControllerResponse, a as InferAdapterDoc, at as ResourceConfig, b as ParsedQuery, c as TypedController, ct as ResourcePermissions, d as PaginationResult, dt as RouteMethod, et as PresetFunction, f as IntrospectionData, ft as RouteSchemaOptions, g as ArcInternalMetadata, gt as IController, h as ResourceMetadata, ht as FastifyHandler, i as ValidationResult, it as ResourceCacheConfig, j as ArcDecorator, jt as AuthenticatorContext, k as IntrospectionPluginOptions, kt as AuthPluginOptions, l as TypedRepository, lt as RouteDefinition, m as RegistryStats, mt as ControllerLike, n as ConfigError, nt as PresetResult, o as InferDocType, ot as ResourceHookContext, p as RegistryEntry, pt as ControllerHandler, q as CrudController, r as ValidateOptions, rt as RateLimitConfig, s as InferResourceDoc, st as ResourceHooks, t as RouteHandlerMethod, tn as BaseControllerOptions, tt as PresetHook, u as TypedResourceConfig, ut as RouteMcpConfig, v as LookupOption, vt as IRequestContext, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, yt as RouteHandler, zt as UserLike } from "../index-CXXRbnf8.mjs";
-import { r as RequestScope } from "../types-DDyTPc6y.mjs";
-import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-BRjxOAFp.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BQQXZ_VR.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, Bt as Authenticator, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as ApiResponse, H as ActionDefinition, Ht as JwtContext, I as MiddlewareHandler, J as CrudRouteKey, Jt as ObjectId, K as ArcFieldRule, Kt as ArcRequest, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Rt as AuthHelpers, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as TokenPair, Vt as AuthenticatorContext, W as ActionHandlerFn, Wt as AnyRecord, X as EventDefinition, Xt as UserOrganization, Y as CrudSchemas, Yt as UserLike, Z as FieldRule, _ as ControllerQueryOptions, _t as IControllerResponse, a as InferAdapterDoc, at as ResourceConfig, b as ParsedQuery, c as TypedController, ct as ResourcePermissions, d as PaginationResult, dt as RouteMethod, et as PresetFunction, f as IntrospectionData, ft as RouteSchemaOptions, g as ArcInternalMetadata, gt as IController, h as ResourceMetadata, ht as FastifyHandler, i as ValidationResult, it as ResourceCacheConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as RouteDefinition, m as RegistryStats, mt as ControllerLike, n as ConfigError, nt as PresetResult, o as InferDocType, on as BaseControllerOptions, ot as ResourceHookContext, p as RegistryEntry, pt as ControllerHandler, q as CrudController, qt as JWTPayload, r as ValidateOptions, rt as RateLimitConfig, s as InferResourceDoc, st as ResourceHooks, t as RouteHandlerMethod, tt as PresetHook, u as TypedResourceConfig, ut as RouteMcpConfig, v as LookupOption, vt as IRequestContext, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, yt as RouteHandler, zt as AuthPluginOptions } from "../index-BtW7qYwa.mjs";
+import { i as RequestScope } from "../types-CTYvcwHe.mjs";
+import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-COhcH3fk.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BXOWoGCF.mjs";
 export { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/{types-D7KpfiL1.d.mts → types-BvqwCCSx.d.mts}

@@ -1,12 +1,12 @@
-import { At as Authenticator } from "./index-CXXRbnf8.mjs";
 import { r as CacheStore } from "./interface-beEtJyWM.mjs";
-import { n as ElevationOptions } from "./elevation-BQQXZ_VR.mjs";
-import { o as EventTransport } from "./EventTransport-CYNUXdCJ.mjs";
+import { Bt as Authenticator } from "./index-BtW7qYwa.mjs";
+import { n as ElevationOptions } from "./elevation-BXOWoGCF.mjs";
+import { a as EventTransport } from "./EventTransport-CT_52aWU.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BD5nw6St.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-CqMdLI2-.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DDJoNEPL.mjs";
-import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DsglKfM_.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-DEWmGWPz.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-qXpqTebY.mjs";
+import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DTTvc80y.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-DFr45ZG4.mjs";
 import { r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
@@ -682,7 +682,20 @@ interface CreateAppOptions {
     keywords?: string[];
   };
   /**
-   * Enable `reply.ok()`, `reply.fail()`, `reply.paginated()` response helpers.
+   * Enable `reply.sendList()` + `reply.stream()` response decorators.
+   *
+   * Arc emits raw data on success — HTTP status discriminates, no
+   * `{ success, data }` envelope — so single-doc handlers just
+   * `return doc` or `reply.send(doc)` and errors throw `ArcError`
+   * (the global handler serializes to `ErrorContract`). The two
+   * decorators below cover the cases that DO need framework support:
+   *
+   *   - `sendList(input)` normalises any kit-shaped paginated/array
+   *     result to the canonical wire shape via repo-core's
+   *     `toCanonicalList` so the server and `@classytic/arc-next`
+   *     typed client share one declaration.
+   *   - `stream(source, options)` sets `Content-Type` /
+   *     `Content-Disposition` headers for file downloads in one call.
    *
    * Default: `false` (opt-in).
    *
@@ -690,32 +703,64 @@ interface CreateAppOptions {
    * ```typescript
    * const app = await createApp({ replyHelpers: true });
    *
-   * // Then in any handler:
-   * return reply.ok({ name: 'MacBook' });          // → 200 { success: true, data: { ... } }
-   * return reply.ok(product, 201);                  // → 201 { success: true, data: { ... } }
-   * return reply.fail('Not found', 404);            // → 404 { success: false, error: '...' }
-   * return reply.fail(['err1', 'err2'], 422);       // → 422 { success: false, errors: [...] }
-   * return reply.paginated({ docs, total, page, limit });
+   * // List endpoint — kit-shaped pagination → canonical wire shape
+   * app.get('/orders', async (req, reply) => {
+   *   const result = await orderRepo.getAll(req.query);
+   *   return reply.sendList(result);
+   * });
+   *
+   * // File download
+   * app.get('/orders/export.csv', async (req, reply) => {
+   *   return reply.stream(csvReadable, {
+   *     contentType: 'text/csv',
+   *     filename: 'orders.csv',
+   *   });
+   * });
    * ```
    */
   replyHelpers?: boolean;
   /**
-   * Auto-convert BigInt values to Number in all JSON responses.
-   *
-   * When `true`, Arc adds a `preSerialization` hook that converts BigInt values
-   * to Number before JSON serialization. Without this, `JSON.stringify` throws
-   * on BigInt values (e.g., from financial libraries like fin-io).
-   *
-   * Default: `false` (opt-in — most apps don't use BigInt).
+   * Serialize `bigint` values in JSON responses.
+   *
+   * `JSON.stringify` throws on `bigint` by default. This option installs a
+   * `preSerialization` hook that converts them on the way out:
+   *
+   * - `false` (default) — no conversion. JSON serialization throws if a
+   *   `bigint` reaches the wire. Safest when no codepath produces bigints.
+   * - `'string'` — **recommended for IDs / money / counters / ledgers.**
+   *   Converts every `bigint` to a decimal string. Lossless: every digit
+   *   survives the wire. Clients parse with `BigInt(value)` to reconstitute.
+   * - `'number'` — converts every `bigint` to `Number(value)`.
+   *   **Lossy above 2^53 - 1 (`Number.MAX_SAFE_INTEGER` = 9007199254740991).**
+   *   Use ONLY when you've audited the value range — e.g. small enums,
+   *   bounded counters that physically can't exceed the safe range. For
+   *   anything that could be an ID, monetary amount, or unbounded counter,
+   *   `Number()` corruption silently rounds digits and there is no
+   *   recovery. arc emits a one-shot startup warning when you opt into
+   *   this mode.
+   * - `true` — back-compat alias for `'number'`. Will be removed in a
+   *   future major. Migrate to `'string'` (lossless) or explicit
+   *   `'number'` (acknowledges the precision risk).
+   *
+   * Default: `false` (opt-in — most apps don't use bigint).
    *
    * @example
    * ```typescript
+   * // Lossless — recommended path
+   * const app = await createApp({
+   *   serializeBigInt: 'string',
+   * });
+   * // { totalSatoshis: "9007199254740999" }
+   *
+   * // Lossy — only when value range is bounded
    * const app = await createApp({
-   *   serializeBigInt: true,
+   *   serializeBigInt: 'number',
+   * });
+   * // { totalSatoshis: 9007199254740999 }  // precision lost above MAX_SAFE_INTEGER
    * });
    * ```
    */
-  serializeBigInt?: boolean;
+  serializeBigInt?: boolean | "number" | "string";
   /**
    * Resources to register automatically. Accepts two shapes:
    *
@@ -733,7 +778,7 @@ interface CreateAppOptions {
    * Arc's lifecycle contract:
    * ```
    * 1. Arc core (security, auth, events)
-   * 2. plugins()            ← infra (DB, SSE, docs)
+   * 2. plugins()            ← infra (DB, SSE, data)
    * 3. bootstrap[]          ← domain init (engines, singletons)
    * 4. resources resolution ← (factory form: call it here)
    * 5. resources registered ← plugins mounted on Fastify
@@ -757,6 +802,9 @@ interface CreateAppOptions {
    *
    * @example Factory with async-booted engine
    * ```ts
+   * import { createApp, defineResource } from '@classytic/arc';
+   * import { createMongooseAdapter } from '@classytic/mongokit/adapter';
+   *
    * const app = await createApp({
    *   bootstrap: [async () => { await ensureCatalogEngine(); }],
    *   resources: async () => {
@@ -867,7 +915,7 @@ interface CreateAppOptions {
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.
    *
-   * Use this for infrastructure setup: database connections, OpenAPI docs,
+   * Use this for infrastructure setup: database connections, OpenAPI data,
    * webhook plugins, SSE wiring, etc.
    */
   plugins?: (fastify: FastifyInstance) => Promise<void>;
@@ -882,7 +930,7 @@ interface CreateAppOptions {
    * Boot order:
    * ```
    * 1. Arc core (security, auth, events)
-   * 2. plugins()      ← infra (DB, SSE, docs)
+   * 2. plugins()      ← infra (DB, SSE, data)
    * 3. bootstrap[]    ← domain init (singletons, event handlers)
    * 4. resources[]    ← auto-discovered routes
    * ```

package/dist/{types-DDyTPc6y.d.mts → types-CTYvcwHe.d.mts}

@@ -19,6 +19,93 @@
  * const globalRoles = getUserRoles(scope);
  * ```
  */
+/**
+ * A capability mandate — declarative, time-boxed, optionally cap-bounded
+ * authorization for a single high-value action by an AI 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 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 };
+ * };
+ * ```
+ */
+interface Mandate {
+  /** Mandate identifier — typically the JWT `jti` claim. */
+  id: string;
+  /**
+   * Capability string the mandate authorizes. Hierarchical-dotted convention:
+   * `payment.charge`, `payment.refund`, `inbox.send`, `data.export`, etc.
+   * Match in `requireMandate(capability)`; treated as opaque otherwise.
+   */
+  capability: string;
+  /**
+   * Optional numeric ceiling for the action — interpretation is per-capability:
+   * for `payment.*` the upper bound on amount (in the mandate's currency),
+   * for `data.export` the row count, for `inbox.send` the message count.
+   * Validated by the host via `validateAmount` in `requireMandate`'s opts.
+   */
+  cap?: number;
+  /**
+   * Currency code (ISO 4217) when `cap` represents a monetary amount.
+   * Required for AP2 / x402 payment mandates; ignored for non-monetary caps.
+   */
+  currency?: string;
+  /** Expiry as epoch ms. `requireMandate` enforces with optional grace window. */
+  expiresAt?: number;
+  /**
+   * Parent mandate id when this mandate was delegated from another. Lets the
+   * audit chain reconstruct the full delegation graph (root user authorization
+   * → agent platform mandate → per-action sub-mandate).
+   */
+  parent?: string;
+  /**
+   * Resource the mandate is bound to (e.g., `invoice:INV-7`, `order:ORD-42`).
+   * When set, `requireMandate` can verify the inbound request targets the
+   * same resource — prevents a payment-mandate for one invoice being replayed
+   * against another.
+   */
+  audience?: string;
+  /**
+   * Free-form claims the host's mandate verifier extracted (intent text,
+   * user-presented confirmation, risk score, etc.). Surfaced in audit rows;
+   * arc takes no position on the shape.
+   */
+  meta?: Readonly<Record<string, unknown>>;
+}
 /**
  * Request scope — 5 kinds, no ambiguity.
  *
@@ -84,6 +171,38 @@ type RequestScope = {
   scopes?: readonly string[]; /** App-defined scope dimensions — see `member.context` for details. */
   context?: Readonly<Record<string, string>>; /** Parent organizations — see `member.ancestorOrgIds` for details. */
   ancestorOrgIds?: readonly string[];
+  /**
+   * Capability mandate — narrows what the caller may do beyond OAuth `scopes`.
+   *
+   * Where `scopes` says "this client can write orders", a mandate says
+   * "this specific request can charge up to $50 on behalf of user U for
+   * invoice INV-7, expires at T". Models the AP2 / Stripe x402 / Google
+   * Agent Payments Protocol pattern for AI-agent-led actions on protected
+   * resources.
+   *
+   * Arc does **not** parse or verify mandate JWTs / VCs — your authenticate
+   * function does (using `jose` / `did-jwt-vc` / your provider's SDK) and
+   * populates this field. Arc's `requireMandate(capability, opts)`
+   * permission helper reads it.
+   *
+   * Optional — omit when the request isn't mandate-bound (most M2M auth
+   * still works fine via OAuth `scopes`).
+   */
+  mandate?: Readonly<Mandate>;
+  /**
+   * DPoP key thumbprint (RFC 7638 JWK SHA-256 thumbprint) bound to this
+   * service identity. When present, the inbound token is sender-constrained
+   * — replaying it from a different client (different key) MUST fail.
+   *
+   * Arc does **not** verify the DPoP proof header — your authenticate
+   * function does (one `jose.dpop.verify()` call) and populates this
+   * field on success. Arc's `requireDPoP()` permission helper checks
+   * presence + binding.
+   *
+   * Pairs with RFC 9449 (OAuth DPoP) and is mandatory for high-value
+   * agent flows in MCP authorization (RFC 9728 + RFC 9700) and AP2.
+   */
+  dpopJkt?: string;
 } | {
   kind: "elevated";
   userId?: string;
@@ -131,6 +250,37 @@ declare function getClientId(scope: RequestScope): string | undefined;
  * Returns an empty array for any non-service kind.
  */
 declare function getServiceScopes(scope: RequestScope): readonly string[];
+/**
+ * Get the capability mandate from a service scope (when present).
+ *
+ * Returns the `Mandate` populated by your authenticate function on
+ * mandate-bound requests (AP2 / x402 / MCP authorization), or `undefined`
+ * for any non-service scope or non-mandate-bound service request.
+ *
+ * Use directly when you need the full mandate for custom logic; use
+ * `requireMandate(capability)` for the canonical permission-check path.
+ *
+ * @example
+ * ```typescript
+ * import { getMandate } from '@classytic/arc/scope';
+ *
+ * const mandate = getMandate(request.scope);
+ * if (mandate?.audience !== `invoice:${request.params.id}`) {
+ *   throw new ForbiddenError('Mandate is bound to a different resource');
+ * }
+ * ```
+ */
+declare function getMandate(scope: RequestScope): Readonly<Mandate> | undefined;
+/**
+ * Get the DPoP key thumbprint (RFC 7638) from a service scope.
+ *
+ * When non-empty, the inbound credential is sender-constrained — replaying
+ * it from a different keypair must fail. Set by your authenticate function
+ * after a successful `jose.dpop.verify()` (or equivalent) call. Read via
+ * `requireDPoP()` permission helper or directly when implementing custom
+ * binding checks.
+ */
+declare function getDPoPJkt(scope: RequestScope): string | undefined;
 /** Get org roles from scope (empty array if not a member) */
 declare function getOrgRoles(scope: RequestScope): string[];
 /** Get team ID from scope (only available on member kind) */
@@ -214,6 +364,50 @@ declare function isOrgInScope(scope: RequestScope, targetOrgId: string): boolean
  * ```
  */
 declare function getUserId(scope: RequestScope): string | undefined;
+/**
+ * Throwing variant of `getOrgId`. Returns the organization id when the
+ * scope carries one (`member` / `service` / `elevated`); throws
+ * `OrgRequiredError` (HTTP 403, code `ORG_SELECTION_REQUIRED`) otherwise.
+ *
+ * Use whenever a handler/service path REQUIRES an org id — `requireOrgId`
+ * eliminates the `if (!orgId) throw …` boilerplate that drifts across
+ * handlers, and ensures every "missing org" produces the same error shape.
+ *
+ * @param hint Optional context for the error message (e.g. route name) —
+ *   surfaces in the response body and in logs, so the failing path is
+ *   visible without grepping for the throw site.
+ * @example
+ * ```typescript
+ * import { requireOrgId } from '@classytic/arc/scope';
+ *
+ * const orgId = requireOrgId(req.scope, 'POST /orders');
+ * await orderRepo.create({ ...req.body, organizationId: orgId });
+ * ```
+ */
+declare function requireOrgId(scope: RequestScope, hint?: string): string;
+/**
+ * Throwing variant of `getUserId`. Returns the user id when the scope is
+ * `authenticated` / `member` / `elevated` and carries one; throws
+ * `UnauthorizedError` (HTTP 401) otherwise.
+ *
+ * @param hint Optional route/context tag for the error message.
+ */
+declare function requireUserId(scope: RequestScope, hint?: string): string;
+/**
+ * Throwing variant of `getClientId`. Returns the service-account `clientId`
+ * when the scope kind is `service`; throws `UnauthorizedError` (HTTP 401)
+ * otherwise. Use for routes that are service-account-only.
+ */
+declare function requireClientId(scope: RequestScope, hint?: string): string;
+/**
+ * Throwing variant of `getTeamId`. Returns the team id when the scope is
+ * `member` and carries one; throws `OrgRequiredError` (HTTP 403) otherwise.
+ *
+ * Uses the org-context error class (not a separate `TeamRequiredError`)
+ * because the failure mode is the same shape as missing-org: the request
+ * lacks a tenancy dimension the route requires.
+ */
+declare function requireTeamId(scope: RequestScope, hint?: string): string;
 /**
  * Get global user roles from scope (available on authenticated and member).
  * These are user-level roles (e.g. superadmin, finance-admin) distinct from
@@ -283,4 +477,4 @@ declare const PUBLIC_SCOPE: Readonly<RequestScope>;
 /** Default authenticated scope — used when user is logged in but no org */
 declare const AUTHENTICATED_SCOPE: Readonly<RequestScope>;
 //#endregion
-export { isAuthenticated as _, getClientId as a, isOrgInScope as b, getOrgRoles as c, getScopeContextMap as d, getServiceScopes as f, hasOrgAccess as g, getUserRoles as h, getAncestorOrgIds as i, getRequestScope as l, getUserId as m, PUBLIC_SCOPE as n, getOrgContext as o, getTeamId as p, RequestScope as r, getOrgId as s, AUTHENTICATED_SCOPE as t, getScopeContext as u, isElevated as v, isService as x, isMember as y };
+export { isOrgInScope as C, requireTeamId as D, requireOrgId as E, requireUserId as O, isMember as S, requireClientId as T, getUserId as _, getAncestorOrgIds as a, isAuthenticated as b, getMandate as c, getOrgRoles as d, getRequestScope as f, getTeamId as g, getServiceScopes as h, RequestScope as i, getOrgContext as l, getScopeContextMap as m, Mandate as n, getClientId as o, getScopeContext as p, PUBLIC_SCOPE as r, getDPoPJkt as s, AUTHENTICATED_SCOPE as t, getOrgId as u, getUserRoles as v, isService as w, isElevated as x, hasOrgAccess as y };