@classytic/arc 2.20.0 → 2.22.0

package/dist/integrations/jobs.d.mts

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/integrations/jobs.d.ts
 /** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
 interface JobRepeatOptions {

package/dist/integrations/mcp/index.d.mts

@@ -1,11 +1,10 @@
-import { V as ResourceDefinition, bt as IControllerResponse, xt as IRequestContext } from "../../index-_--GyzcO.mjs";
-import { i as RequestScope } from "../../types-LNebCoJx.mjs";
-import { c as PermissionCheck } from "../../fields-C7ahdGYf.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-C9b2HR5W.mjs";
+import { Rt as IControllerResponse, V as ResourceDefinition, zt as IRequestContext } from "../../index-DbtgCOCj.mjs";
+import { i as RequestScope } from "../../types-DH0GupI7.mjs";
+import { t as PermissionCheck } from "../../types-Csxga7d3.mjs";
+import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-Bc42CUyk.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
-
 //#region src/integrations/mcp/aiSdkBridge.d.ts
 /** Minimal AI SDK tool shape we need to invoke. */
 interface AiSdkExecutable {
@@ -170,7 +169,7 @@ interface DefinePromptConfig<TArgs extends Record<string, z.ZodTypeAny>> {
   title?: string;
   /** Flat Zod shape for prompt arguments */
   args?: TArgs;
-  handler: (args: { [K in keyof TArgs]: z.infer<TArgs[K]> }) => PromptResult;
+  handler: (args: { [K in keyof TArgs]: z.infer<TArgs[K]>; }) => PromptResult;
 }
 /**
  * Define a type-safe MCP prompt.
@@ -197,7 +196,7 @@ interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>, TSession
   /** Flat Zod shape for structured output */
   output?: Record<string, z.ZodTypeAny>;
   annotations?: ToolAnnotations;
-  handler: (input: { [K in keyof TInput]: z.infer<TInput[K]> }, ctx: ToolContext<TSession>) => Promise<CallToolResult>;
+  handler: (input: { [K in keyof TInput]: z.infer<TInput[K]>; }, ctx: ToolContext<TSession>) => Promise<CallToolResult>;
 }
 /**
  * Define a type-safe MCP tool.

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-CuW6L_uD.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-ByA2tf6D.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.

package/dist/integrations/mcp/testing.d.mts

@@ -1,5 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-C9b2HR5W.mjs";
-
+import { c as McpAuthResult, l as McpPluginOptions } from "../../types-Bc42CUyk.mjs";
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {
   /** MCP plugin options (resources, overrides, etc.) — same as mcpPlugin config */

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-CuW6L_uD.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-ByA2tf6D.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/streamline.d.mts

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
-
 //#region src/integrations/streamline.d.ts
 /**
  * Start options — matches @classytic/streamline v2.3+ `StartOptions`.
@@ -53,7 +52,8 @@ interface WorkflowLike {
     eventBus: {
       on(event: string, listener: (...args: unknown[]) => void): void;
       off(event: string, listener: (...args: unknown[]) => void): void;
-    }; /** Repository — used by the list-runs endpoint to query workflow_runs. */
+    };
+    /** Repository — used by the list-runs endpoint to query workflow_runs. */
     repository?: {
       getAll(params: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
       /**

package/dist/integrations/webhooks.d.mts

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/integrations/webhooks.d.ts
 interface WebhookSubscription {
   /** Unique subscription ID */
@@ -78,8 +77,9 @@ interface VerifySignatureOptions {
  *
  * ⚠ The `body` argument must be the exact bytes the sender signed. Fastify
  * parses JSON bodies by default and the re-serialised object will NOT match
- * the original signature. Register `@fastify/raw-body` or use `preParsing`
- * to capture `req.rawBody`, then pass that here.
+ * the original signature. Register `fastify-raw-body` (arc's createApp does
+ * this automatically with `global: false`) and opt the route in via
+ * `config: { rawBody: true }`, then pass `req.rawBody` here.
  *
  * @param body      - Raw request body (string or Buffer — must be the exact bytes the sender signed)
  * @param secret    - Shared secret between sender and receiver
@@ -91,8 +91,11 @@ interface VerifySignatureOptions {
  * ```typescript
  * import { verifySignature } from '@classytic/arc/integrations/webhooks';
  *
- * // Arc-to-Arc (default headers + format)
- * fastify.post('/webhooks/incoming', async (req, reply) => {
+ * // Arc-to-Arc (default headers + format). `config: { rawBody: true }` is
+ * // REQUIRED — arc registers fastify-raw-body with `global: false`, so
+ * // routes opt in per-route; without it `req.rawBody` is undefined and
+ * // verifySignature throws a TypeError.
+ * fastify.post('/webhooks/incoming', { config: { rawBody: true } }, async (req, reply) => {
  *   const sig = req.headers['x-webhook-signature'] as string;
  *   if (!verifySignature(req.rawBody, secret, sig)) {
  *     return reply.status(401).send({ error: 'Invalid signature' });

package/dist/integrations/webhooks.mjs

@@ -48,8 +48,9 @@ function signPayload(payload, secret) {
 *
 * ⚠ The `body` argument must be the exact bytes the sender signed. Fastify
 * parses JSON bodies by default and the re-serialised object will NOT match
-* the original signature. Register `@fastify/raw-body` or use `preParsing`
-* to capture `req.rawBody`, then pass that here.
+* the original signature. Register `fastify-raw-body` (arc's createApp does
+* this automatically with `global: false`) and opt the route in via
+* `config: { rawBody: true }`, then pass `req.rawBody` here.
 *
 * @param body      - Raw request body (string or Buffer — must be the exact bytes the sender signed)
 * @param secret    - Shared secret between sender and receiver
@@ -61,8 +62,11 @@ function signPayload(payload, secret) {
 * ```typescript
 * import { verifySignature } from '@classytic/arc/integrations/webhooks';
 *
-* // Arc-to-Arc (default headers + format)
-* fastify.post('/webhooks/incoming', async (req, reply) => {
+* // Arc-to-Arc (default headers + format). `config: { rawBody: true }` is
+* // REQUIRED — arc registers fastify-raw-body with `global: false`, so
+* // routes opt in per-route; without it `req.rawBody` is undefined and
+* // verifySignature throws a TypeError.
+* fastify.post('/webhooks/incoming', { config: { rawBody: true } }, async (req, reply) => {
 *   const sig = req.headers['x-webhook-signature'] as string;
 *   if (!verifySignature(req.rawBody, secret, sig)) {
 *     return reply.status(401).send({ error: 'Invalid signature' });
@@ -82,7 +86,7 @@ function signPayload(payload, secret) {
 * ```
 */
 function verifySignature(body, secret, signature, options) {
-	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifySignature: body must be a string or Buffer (the exact bytes the sender signed). Register @fastify/raw-body and pass req.rawBody — not req.body.");
+	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifySignature: body must be a string or Buffer (the exact bytes the sender signed). Add `config: { rawBody: true }` to the route (arc registers fastify-raw-body with global: false) and pass req.rawBody — not req.body.");
 	if (!signature) return false;
 	const prefix = options?.prefix ?? "sha256=";
 	const algorithm = options?.algorithm ?? "sha256";

package/dist/integrations/websocket-pushref-redis.d.mts

@@ -1,5 +1,4 @@
-import { c as SerializedEntry, i as Principal, n as FencedWriteOutcome, s as PushRefStore, t as EnvelopeSnapshot } from "../pushref-registry-DnCqL3aa.mjs";
-
+import { c as SerializedEntry, i as Principal, n as FencedWriteOutcome, s as PushRefStore, t as EnvelopeSnapshot } from "../pushref-registry-BbcnpNTm.mjs";
 //#region src/integrations/websocket-pushref-redis.d.ts
 /**
  * Minimal `ioredis` shape — typed structurally so this file doesn't

package/dist/integrations/websocket-redis.d.mts

@@ -1,5 +1,4 @@
-import { f as WebSocketAdapter } from "../websocket-MlYlrYq0.mjs";
-
+import { f as WebSocketAdapter } from "../websocket-uuWqM6UY.mjs";
 //#region src/integrations/websocket-redis.d.ts
 interface RedisLike {
   publish(channel: string, message: string): Promise<number>;

package/dist/integrations/websocket.d.mts

@@ -1,3 +1,3 @@
-import { a as GeoRoomOptions, c as WebSocketClient, d as LocalWebSocketAdapter, f as WebSocketAdapter, i as GeoRoom, l as WebSocketMessage, n as GeoPoint, o as RoomManager, r as GeoPublishOpts, s as AuthResult, t as websocketPlugin, u as WebSocketPluginOptions } from "../websocket-MlYlrYq0.mjs";
-import { a as PushRefRegistry, c as SerializedEntry, i as Principal, o as PushRefRegistryOptions, r as MemoryPushRefStore, s as PushRefStore } from "../pushref-registry-DnCqL3aa.mjs";
+import { a as GeoRoomOptions, c as WebSocketClient, d as LocalWebSocketAdapter, f as WebSocketAdapter, i as GeoRoom, l as WebSocketMessage, n as GeoPoint, o as RoomManager, r as GeoPublishOpts, s as AuthResult, t as websocketPlugin, u as WebSocketPluginOptions } from "../websocket-uuWqM6UY.mjs";
+import { a as PushRefRegistry, c as SerializedEntry, i as Principal, o as PushRefRegistryOptions, r as MemoryPushRefStore, s as PushRefStore } from "../pushref-registry-BbcnpNTm.mjs";
 export { type AuthResult, type GeoPoint, type GeoPublishOpts, GeoRoom, type GeoRoomOptions, LocalWebSocketAdapter, MemoryPushRefStore, type Principal, PushRefRegistry, type PushRefRegistryOptions, type PushRefStore, RoomManager, type SerializedEntry, type WebSocketAdapter, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, websocketPlugin };

package/dist/jsonBody-BlzAoGCe.mjs

@@ -0,0 +1,43 @@
+import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
+import sjson from "secure-json-parse";
+//#region src/utils/jsonBody.ts
+/**
+* Shared JSON request-body parsing for every arc content-type parser
+* (`application/json`, `application/scim+json`, decrypted `application/jose`).
+*
+* One primitive, one contract:
+*   - empty body → `undefined` (DELETE/GET with `Content-Type: application/json`
+*     must not crash — the original reason arc replaces Fastify's parser)
+*   - prototype-poisoning payloads (`__proto__`, `constructor.prototype`)
+*     rejected via `secure-json-parse`, same protection Fastify's stock
+*     parser has
+*   - ANY parse failure → `ArcError` with `statusCode: 400` /
+*     `code: 'arc.bad_request'`. Client-sent bytes can never produce a 500:
+*     Fastify forwards parser errors to the error handler as-is, so an
+*     undecorated `SyntaxError` would fall through to the
+*     `arc.internal_error` fallback. The raw parser message stays on
+*     `cause` (logged, never on the wire).
+*/
+/**
+* Parse a JSON request body with prototype-poisoning protection and the
+* arc 400 error contract.
+*
+* @param raw     - Body text (string or Buffer). Empty/absent → `undefined`.
+* @param message - Wire-safe error message for parse failures
+*                  (default: `"Invalid JSON payload"`).
+*/
+function parseJsonBody(raw, message = "Invalid JSON payload") {
+	const text = typeof raw === "string" ? raw : raw ? raw.toString("utf8") : "";
+	if (text.length === 0) return void 0;
+	try {
+		return sjson.parse(text);
+	} catch (cause) {
+		throw new ArcError(message, {
+			code: "arc.bad_request",
+			statusCode: 400,
+			cause
+		});
+	}
+}
+//#endregion
+export { parseJsonBody as t };

package/dist/{loadResources-B8UmpITt.mjs → loadResources-DpU8pfjV.mjs}

@@ -59,10 +59,11 @@ var loadResources_exports = /* @__PURE__ */ __exportAll({ loadResources: () => l
 * ```
 */
 async function loadResources(dir, options = {}) {
-	const { suffix = ".resource", recursive = true, exclude, include } = options;
+	const { suffix = ".resource", recursive = true, exclude, include, filter } = options;
 	const absDir = resolve(dir.startsWith("file://") ? dirname(fileURLToPath(dir)) : dir);
-	const files = await collectFiles(absDir, new RegExp(`${escapeRegex(suffix)}\\.(ts|js|mts|mjs)$`), recursive);
-	files.sort();
+	const discovered = await collectFiles(absDir, new RegExp(`${escapeRegex(suffix)}\\.(ts|js|mts|mjs)$`), recursive);
+	discovered.sort();
+	const files = filter ? discovered.filter((f) => filter(f)) : discovered;
 	const includeSet = include ? new Set(include) : null;
 	const excludeSet = exclude ? new Set(exclude) : null;
 	const skipped = [];

package/dist/logger/index.d.mts

@@ -77,5 +77,30 @@ declare function configureArcLogger(options: ArcLoggerOptions): void;
  * ```
  */
 declare function arcLog(module: string): ArcLogger;
+/**
+ * Minimal structural slice of a pino-style logger (`fastify.log`). Each
+ * level accepts `(msg)` or `(mergeObject, msg)` — the pino calling
+ * convention, which differs from console's variadic `(...args)`.
+ */
+interface PinoLike {
+  debug: (obj: unknown, msg?: string) => void;
+  info: (obj: unknown, msg?: string) => void;
+  warn: (obj: unknown, msg?: string) => void;
+  error: (obj: unknown, msg?: string) => void;
+}
+/**
+ * Bridge an `ArcLogWriter` onto a pino-style logger (`fastify.log`).
+ *
+ * arcLog call sites use the console convention — positional args like
+ * `log.warn("message", { userId })` — which pino would silently drop
+ * (extra args are printf interpolation values there). The bridge folds
+ * string args into the message, merges object args into the pino merge
+ * object, and maps `Error` instances to `{ err }` so pino's error
+ * serializer applies.
+ *
+ * `createApp` installs this automatically so arc-internal warnings flow
+ * through the host's transports, level, and redaction config.
+ */
+declare function createPinoWriter(logger: PinoLike): ArcLogWriter;
 //#endregion
-export { ArcLogWriter, ArcLogger, ArcLoggerOptions, arcLog, configureArcLogger };
+export { ArcLogWriter, ArcLogger, ArcLoggerOptions, PinoLike, arcLog, configureArcLogger, createPinoWriter };

package/dist/logger/index.mjs

@@ -44,6 +44,44 @@ function arcLog(module) {
 		}
 	};
 }
+/**
+* Bridge an `ArcLogWriter` onto a pino-style logger (`fastify.log`).
+*
+* arcLog call sites use the console convention — positional args like
+* `log.warn("message", { userId })` — which pino would silently drop
+* (extra args are printf interpolation values there). The bridge folds
+* string args into the message, merges object args into the pino merge
+* object, and maps `Error` instances to `{ err }` so pino's error
+* serializer applies.
+*
+* `createApp` installs this automatically so arc-internal warnings flow
+* through the host's transports, level, and redaction config.
+*/
+function createPinoWriter(logger) {
+	const emit = (level) => (...args) => {
+		const parts = [];
+		let merge;
+		for (const arg of args) if (typeof arg === "string") parts.push(arg);
+		else if (arg instanceof Error) merge = {
+			...merge ?? {},
+			err: arg
+		};
+		else if (arg !== null && typeof arg === "object") merge = {
+			...merge ?? {},
+			...arg
+		};
+		else parts.push(String(arg));
+		const msg = parts.join(" ");
+		if (merge) logger[level](merge, msg);
+		else logger[level](msg);
+	};
+	return {
+		debug: emit("debug"),
+		info: emit("info"),
+		warn: emit("warn"),
+		error: emit("error")
+	};
+}
 function getWriter() {
 	return globalOptions.writer ?? console;
 }
@@ -68,4 +106,4 @@ function isSuppressed() {
 	return env === "1" || env === "true";
 }
 //#endregion
-export { arcLog, configureArcLogger };
+export { arcLog, configureArcLogger, createPinoWriter };

package/dist/{mcpPlugin-CuW6L_uD.mjs → mcpPlugin-ByA2tf6D.mjs}

@@ -1,13 +1,13 @@
 import { p as isArcError, t as ArcError } from "./errors-DkO8Nk6-.mjs";
 import { c as getOrgId, g as getUserId } from "./types-bHblZ9YN.mjs";
-import { t as BaseController } from "./BaseController-D-MHZ27_.mjs";
-import { N as normalizePermissionResult } from "./permissions-CgbOLJZG.mjs";
+import { t as BaseController } from "./BaseController-C6FlRWxF.mjs";
+import { P as normalizePermissionResult } from "./permissions-BJMuKMl7.mjs";
 import { t as executePipeline } from "./pipe-BOLmGIxa.mjs";
-import { i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-C9RMiIpc.mjs";
+import { i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
 import { n as validateAggregations } from "./validate-C2mGgSXg.mjs";
 import { n as executeAggregation } from "./buildHandler-D_2ULWxZ.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-ajetw3Fv.mjs";
+import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-B-6SPe7g.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
@@ -630,6 +630,7 @@ function defaultCrudDescription(op, displayName, softDelete, queryMeta) {
 			if (queryMeta?.filterableFields?.length) parts.push(`Filterable fields: ${queryMeta.filterableFields.join(", ")}.`);
 			if (queryMeta?.allowedOperators?.length) parts.push(`Filter operators: ${queryMeta.allowedOperators.join(", ")} (use field[op]=value syntax).`);
 			if (queryMeta?.sortableFields?.length) parts.push(`Sortable fields: ${queryMeta.sortableFields.join(", ")}.`);
+			parts.push("Set _count: true for a count-only result, _exists: true for a boolean existence check, or _distinct: '<field>' for distinct values — all honor the same filters.");
 			return parts.join(" ");
 		}
 		case "get": return `Get a single ${singular} by ID`;
@@ -772,6 +773,9 @@ function buildListShape(fieldRules, options) {
 	const { filterableFields = [], hiddenFields = [], extraHideFields = [], allowedOperators } = options;
 	const allHidden = /* @__PURE__ */ new Set([...hiddenFields, ...extraHideFields]);
 	const shape = { ...PAGINATION_SHAPE };
+	shape._count = z.boolean().optional().describe("Return only { count } of records matching the filters — no documents fetched. Cheapest way to answer 'how many'.");
+	shape._exists = z.boolean().optional().describe("Return only whether ANY record matches the filters (boolean existence check).");
+	shape._distinct = z.string().optional().describe("Return the distinct values of this field across records matching the filters.");
 	if (!fieldRules) return shape;
 	for (const name of filterableFields) {
 		if (allHidden.has(name)) continue;

package/dist/middleware/index.d.mts

@@ -1,6 +1,5 @@
-import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-_--GyzcO.mjs";
+import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-DbtgCOCj.mjs";
 import { RouteHandlerMethod } from "fastify";
-
 //#region src/middleware/middleware.d.ts
 interface NamedMiddleware {
   /** Unique name for debugging/introspection */

package/dist/{module-JYH9V0I8.d.mts → module-B4u10iOJ.d.mts}

@@ -1,5 +1,5 @@
+import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
 import { FastifyInstance } from "fastify";
-
 //#region src/factory/loadResources.d.ts
 /**
  * loadResources — Auto-discover resource files from a directory.
@@ -142,6 +142,31 @@ interface LoadResourcesOptions<TContext = unknown> {
    * ```
    */
   include?: string[];
+  /**
+   * Path-level gate, called for every discovered file BEFORE it is imported.
+   * Return `false` to skip the file entirely — its module never evaluates,
+   * so top-level side effects (engine construction, model registration) of
+   * gated-off features never fire. That's the difference from
+   * `include`/`exclude`, which match resource NAMES after import.
+   *
+   * The feature-flag → resource-dir manifest every tiered SaaS host carries
+   * becomes one callback:
+   *
+   * ```ts
+   * await loadResources(import.meta.url, {
+   *   filter: (path) => {
+   *     if (path.includes(`${sep}loyalty${sep}`)) return isFeatureEnabled('loyalty');
+   *     if (path.includes(`${sep}pos${sep}`)) return isFeatureEnabled('pos');
+   *     return true;
+   *   },
+   * });
+   * ```
+   *
+   * Receives the ABSOLUTE file path. Gating everything is legitimate — the
+   * result is an empty array (interacts with `strictResourceDir` like any
+   * other empty discovery).
+   */
+  filter?: (absolutePath: string) => boolean;
   /**
    * Optional logger override for diagnostics. When omitted, warnings flow
    * through arc's standard logger (`arcLog('loadResources')`) — same path
@@ -243,6 +268,26 @@ interface ArcModule<TExports = unknown> {
    * inside `bootstrap` still works — this slot just makes the two distinct.
    */
   plugins?: (fastify: FastifyInstance) => void | Promise<void>;
+  /**
+   * Domain error mappers this module ships (see `defineErrorMapper`). Merged
+   * into the app's error handler at boot, AFTER any host-declared mappers —
+   * host config keeps priority; module mappers follow in composition order.
+   *
+   * Closes the "composition root must know every domain's error classes"
+   * coupling: before this slot, adding `@classytic/arc-shipping` meant
+   * remembering to also register its `ShippingError` mapper in the host's
+   * `errorHandler.errorMappers` — forget it and the domain error crossed the
+   * wire as an opaque 500. Now the module carries its own mapper:
+   *
+   * ```ts
+   * defineModule({
+   *   name: 'shipping',
+   *   errorMappers: [shippingErrorMapper],
+   *   ...
+   * })
+   * ```
+   */
+  readonly errorMappers?: readonly ErrorMapper[];
   /**
    * Domain init — runs in the `bootstrap` phase (after all `plugins`, before
    * resources). Initialize engines / singletons / event subscriptions here so
@@ -261,6 +306,31 @@ interface ArcModule<TExports = unknown> {
    * ```
    */
   bootstrap?: (fastify: FastifyInstance) => 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).
+   *   - 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.
+   *   - 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.
+   */
+  readonly owns?: readonly string[];
   /**
    * The module's resources. Array or factory — the factory form runs AFTER all
    * bootstraps, so `defineResource(...)` receives fully-booted engines. Flows

package/dist/{openapi-Dq6RbEGK.mjs → openapi-BRpMZD7C.mjs}

@@ -1,8 +1,8 @@
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-U0MnO9vd.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-C9RMiIpc.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-Ds5reSGs.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-HlQso0jO.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-h1cEEaEX.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/permissions/index.d.mts

@@ -1,3 +1,4 @@
-import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, f as getUserRoles, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, p as normalizeRoles, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission, u as PermissionResult } from "../fields-C7ahdGYf.mjs";
-import { A as requireRoles, C as allOf, D as not, E as denyAll, F as RequireAgentScopeOptions, I as RequireMandateOptions, L as requireAgentScope, M as when, N as applyPermissionResult, O as requireAuth, P as normalizePermissionResult, R as requireDPoP, S as createOrgPermissions, T as anyOf, _ as ConnectEventsOptions, a as presets_d_exports, b as PermissionEventBus, c as readOnly, d as requireOrgRole, f as requireScopeContext, g as createRoleHierarchy, h as RoleHierarchy, i as ownerWithAdminBypass, j as roles, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig, z as requireMandate } from "../index-CdFkIMEd.mjs";
-export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };
+import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-D3lhgzhD.mjs";
+import { A as requireOwnership, B as requireMandate, C as createOrgPermissions, D as denyAll, E as anyOf, F as normalizePermissionResult, I as RequireAgentScopeOptions, L as RequireMandateOptions, M as roles, N as when, O as not, P as applyPermissionResult, R as requireAgentScope, S as createDynamicPermissionMatrix, T as allowPublic, _ as createRoleHierarchy, a as permissionMatrix, b as DynamicPermissionMatrixConfig, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as requireRoles, k as requireAuth, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as ConnectEventsOptions, w as allOf, x as PermissionEventBus, y as DynamicPermissionMatrix, z as requireDPoP } from "../index-ogIHvOjo.mjs";
+export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,3 +1,3 @@
-import { A as requireMandate, C as requireAuth, D as when, E as roles, F as applyFieldWritePermissions, I as fields, L as resolveEffectiveRoles, N as normalizePermissionResult, O as requireAgentScope, P as applyFieldReadPermissions, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyPermissionResult, k as requireDPoP, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-CgbOLJZG.mjs";
+import { A as requireDPoP, C as not, D as roles, E as requireRoles, F as applyFieldReadPermissions, I as applyFieldWritePermissions, L as fields, M as applyPermissionResult, O as when, P as normalizePermissionResult, R as resolveEffectiveRoles, S as denyAll, T as requireOwnership, _ as requireServiceScope, a as permissionMatrix, b as allowPublic, c as publicReadAdminWrite, d as createDynamicPermissionMatrix, f as createOrgPermissions, g as requireScopeContext, h as requireOrgRole, i as ownerWithAdminBypass, j as requireMandate, k as requireAgentScope, l as readOnly, m as requireOrgMembership, n as authenticated, o as presets_exports, p as requireOrgInScope, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireTeamMembership, w as requireAuth, x as anyOf, y as allOf } from "../permissions-BJMuKMl7.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
-export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };
+export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/{permissions-CgbOLJZG.mjs → permissions-BJMuKMl7.mjs}

@@ -1382,6 +1382,7 @@ var presets_exports = /* @__PURE__ */ __exportAll({
 	authenticated: () => authenticated,
 	fullPublic: () => fullPublic,
 	ownerWithAdminBypass: () => ownerWithAdminBypass,
+	permissionMatrix: () => permissionMatrix,
 	publicRead: () => publicRead,
 	publicReadAdminWrite: () => publicReadAdminWrite,
 	readOnly: () => readOnly
@@ -1450,6 +1451,37 @@ function adminOnly(roles = ["admin"], overrides) {
 	}, overrides);
 }
 /**
+* Arbitrary-gate CRUD matrix — the generalization every host and arc-*
+* module hand-rolls as `{ list: view, get: view, create: manage, ... }`.
+*
+* Unlike the fixed presets above, the gates are caller-supplied
+* `PermissionCheck`s, so ANY combinator plugs in — org roles, ownership,
+* `anyOf(...)`, service scopes, custom async checks. `delete` defaults to
+* the `write` gate.
+*
+* @example
+* ```typescript
+* // Two-gate (view/manage) — the arc-* module convention:
+* permissionMatrix({ read: requireAuth(), write: requireOrgRole('manager') })
+*
+* // Three-gate with a stricter delete:
+* permissionMatrix({
+*   read: allowPublic(),
+*   write: requireOrgRole('manager'),
+*   delete: requireOrgRole('owner'),
+* })
+* ```
+*/
+function permissionMatrix(gates, overrides) {
+	return withOverrides({
+		list: gates.read,
+		get: gates.read,
+		create: gates.write,
+		update: gates.write,
+		delete: gates.delete ?? gates.write
+	}, overrides);
+}
+/**
 * Owner-scoped with admin bypass.
 * list = auth (scoped to owner), get = auth, create = auth,
 * update + delete = ownership check with admin bypass.
@@ -1498,4 +1530,4 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { requireMandate as A, requireAuth as C, when as D, roles as E, applyFieldWritePermissions as F, fields as I, resolveEffectiveRoles as L, evaluateAndApplyPermission as M, normalizePermissionResult as N, requireAgentScope as O, applyFieldReadPermissions as P, not as S, requireRoles as T, requireTeamMembership as _, presets_exports as a, anyOf as b, readOnly as c, createOrgPermissions as d, requireOrgInScope as f, requireServiceScope as g, requireScopeContext as h, ownerWithAdminBypass as i, applyPermissionResult as j, requireDPoP as k, createRoleHierarchy as l, requireOrgRole as m, authenticated as n, publicRead as o, requireOrgMembership as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, createDynamicPermissionMatrix as u, allOf as v, requireOwnership as w, denyAll as x, allowPublic as y };
+export { requireDPoP as A, not as C, roles as D, requireRoles as E, applyFieldReadPermissions as F, applyFieldWritePermissions as I, fields as L, applyPermissionResult as M, evaluateAndApplyPermission as N, when as O, normalizePermissionResult as P, resolveEffectiveRoles as R, denyAll as S, requireOwnership as T, requireServiceScope as _, permissionMatrix as a, allowPublic as b, publicReadAdminWrite as c, createDynamicPermissionMatrix as d, createOrgPermissions as f, requireScopeContext as g, requireOrgRole as h, ownerWithAdminBypass as i, requireMandate as j, requireAgentScope as k, readOnly as l, requireOrgMembership as m, authenticated as n, presets_exports as o, requireOrgInScope as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, requireTeamMembership as v, requireAuth as w, anyOf as x, allOf as y };

package/dist/pipeline/index.d.mts

@@ -1,5 +1,4 @@
-import { Bt as Transform, Ft as NextFunction, It as OperationFilter, Lt as PipelineConfig, Nt as Guard, Pt as Interceptor, Rt as PipelineContext, bt as IControllerResponse, zt as PipelineStep } from "../index-_--GyzcO.mjs";
-
+import { Ct as PipelineStep, Rt as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-DbtgCOCj.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;