@classytic/arc 2.41.0 → 2.43.0

package/skills/arc/SKILL.md

@@ -77,7 +77,7 @@ createApp({ role: process.env.ARC_ROLE as 'api' | 'worker' | 'relay' | 'schedule
 
 `api` and `worker` mount NO module schedule arms; `relay` mounts only `kind: 'relay'` arms (the outbox relay, durable webhook delivery); `scheduler` mounts all of them. Declaring `relay`/`scheduler` together with `resources`/`resourceDir` is BOOT-FATAL — a relay process must not serve routes. Default `all` is the pre-2.33 behaviour, unchanged. `createWorker()` forwards `role`; without one it still runs everything non-HTTP.
 
-`beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks.
+`beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks. Return a disposer (`() => mongoose.disconnect()`) and arc runs it on close and on a failed boot. A bridge declared as `{ kind: 'bridge', name, dependsOn, load }` is never imported when inactive.
 
 For async-booted engines, pass `resources` as a factory so it runs after `bootstrap[]`:
 
@@ -210,7 +210,14 @@ presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
 
 ## Permissions
 
-A `PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`. `filters` propagate into the repo query (row-level ABAC). `scope` stamps attributes downstream.
+A `PermissionCheck` returns `boolean | AuthorizationDecision` — build one with `allow({ policy?, scope? })` / `deny(reason?)`. `policy` is ANDed into the repo query (row-level ABAC); `scope` stamps attributes downstream. The pre-2.30 `{ granted, filters }` shape THROWS — never emit it.
+
+**Public but row-filtered** — use `allowPublic({ policy })`, not a hand-written `allow({ policy })`: a hand-written check lacks the `_isPublic` flag, so anonymous callers get 401.
+
+```typescript
+list: allowPublic({ policy: { status: 'published' } }),              // strangers: published only
+list: allowPublic({ policy: (ctx) => isElevated(scopeOf(ctx)) ? {} : { status: 'published' } }),  // {} = unrestricted
+```
 
 ```typescript
 import {
@@ -233,9 +240,11 @@ permissions: {
 **Custom check:**
 
 ```typescript
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
+
 const requirePro = (): PermissionCheck => async (ctx) => {
-  if (!ctx.user) return { granted: false, reason: 'Auth required' };
-  return { granted: ctx.user.plan === 'pro' };
+  if (!ctx.user) return deny('Auth required');
+  return ctx.user.plan === 'pro' ? allow() : deny('Pro plan required');
 };
 ```
 

package/skills/arc/references/auth.md

@@ -497,6 +497,7 @@ import {
 | Function | Description |
 |----------|-------------|
 | `allowPublic()` | No authentication |
+| `allowPublic({ policy })` | No authentication, rows narrowed by a filter (or a per-caller resolver; `{}` = unrestricted) |
 | `requireAuth()` | Any authenticated user |
 | `requireRoles(['admin'])` | At least one role matches |
 | `requireOwnership('userId')` | Resource owner only (elevated bypasses) |
@@ -510,9 +511,11 @@ import {
 **Custom permission:**
 
 ```typescript
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
+
 const requirePro = (): PermissionCheck => async (ctx) => {
-  if (!ctx.user) return { granted: false, reason: 'Auth required' };
-  return { granted: ctx.user.plan === 'pro' };
+  if (!ctx.user) return deny('Auth required');
+  return ctx.user.plan === 'pro' ? allow() : deny('Pro plan required');
 };
 ```
 
@@ -646,12 +649,12 @@ Gate routes on service identity using the scope helpers + a permission builder:
 
 ```typescript
 import { isService, getClientId, getServiceScopes } from '@classytic/arc/scope';
-import type { PermissionCheck } from '@classytic/arc/permissions';
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
 
 const requireScope = (scope: string): PermissionCheck => (ctx) => {
-  if (!isService(ctx.request.scope)) return { granted: false, reason: 'service only' };
+  if (!isService(ctx.request.scope)) return deny('service only');
   const has = getServiceScopes(ctx.request.scope).includes(scope);
-  return has ? { granted: true } : { granted: false, reason: `missing scope: ${scope}` };
+  return has ? allow() : deny(`missing scope: ${scope}`);
 };
 
 defineResource({

package/skills/arc/references/integrations.md

@@ -238,7 +238,7 @@ Single configuration point for both SSE and WebSocket with shared auth, org-scop
 ```typescript
 await fastify.register(eventGatewayPlugin, {
   auth: true,                     // Fail-closed for both SSE and WebSocket
-  orgScoped: true,                // Filter events by org
+  // orgScoped: omitted → SSE's default (true). Set false only for a cross-tenant ops stream.
   roomPolicy: (client, room) => {
     return ['product', 'order', 'invoice'].includes(room);
   },

package/skills/arc/references/mcp.md

@@ -101,18 +101,20 @@ await app.register(mcpPlugin, {
 
 ### Permission Filters (v2.4.2)
 
-Resource permissions with `filters` are automatically enforced in MCP tools — same as REST:
+Resource permissions that return a row `policy` are automatically enforced in MCP tools — same as REST:
 
 ```typescript
+import { allow, deny } from '@classytic/arc/permissions';
+
 defineResource({
   name: 'task',
   permissions: {
-    list: (ctx) => ({
-      granted: !!ctx.user,
-      filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
-    }),
+    list: (ctx) =>
+      ctx.user
+        ? allow({ policy: { orgId: ctx.user.orgId, branchId: ctx.user.branchId } })
+        : deny('Auth required'),
     create: (ctx) => !!ctx.user,                    // boolean works too
-    delete: (ctx) => ({ granted: false, reason: 'Read-only' }),  // deny
+    delete: () => deny('Read-only'),
   },
 });
 

package/skills/arc/references/multi-tenancy.md

@@ -38,15 +38,21 @@ Every request goes through this ladder — if any step is missed, tenant isolati
 
 ## Where `tenantField` is read
 
-Every resource defines `tenantField` (default: `'organizationId'`, or `false` to disable). It is read in **exactly three places** and ALL of them derive the org ID from `metadata._scope` via `getOrgId()`:
+Every resource defines `tenantField` (default: `'organizationId'`, or `false` to disable). **One function decides tenancy — `resolveTenancy()` in `src/core/tenancy.ts`** — and every layer switches on its result:
 
-| File                           | Method                  | Purpose                                        |
-|--------------------------------|-------------------------|------------------------------------------------|
-| `src/core/QueryResolver.ts`    | `resolve()`             | `list` — prepends `{ [tenantField]: orgId }` to the filter |
-| `src/core/AccessControl.ts`    | `buildIdFilter()`       | `get`, `update`, `delete` by ID — compound filter so cross-tenant IDs 404 |
-| `src/core/BaseController.ts`   | `buildBulkFilter()`     | `bulkUpdate`, `bulkDelete` — narrows bulk ops to the caller's org |
+| Result | Meaning |
+|---|---|
+| `{ mode: 'scoped', field, orgId }` | filter by `field = orgId` (a member, a service key, or an elevated admin who SELECTED an org) |
+| `unscoped: 'platform'` | elevated admin with NO org — sees and writes across tenants |
+| `unscoped: 'cross-tenant'` | the route declared `multiTenantPreset({ crossTenant: [...] })` — reads only; the row policy still applies |
+| `unscoped: 'no-org'` | anonymous, or signed in with no org selected — reads get no tenant filter (the preset refuses earlier where one is required); **writes are refused** |
+| `unscoped: 'untenanted-resource'` | `tenantField: false` |
 
-**Everything else** (`BodySanitizer`, `MongoKit QueryParser`, presets) already composes cleanly with these three read points. If `getOrgId(scope)` returns the right value, you have tenant isolation — end of story.
+Consumers: `QueryResolver` (list), `AccessControl.buildIdFilter` (get/update/delete by id) and `checkOrgScope` (post-fetch), `buildTenantRepoOptions` (what the kit is told, `bypassTenant`), the bulk mixin (`bulkCreate` stamping + `buildBulkFilter`), and — via `eventAudienceOf` / `isEventVisible` — the `sse` and `realtime` streams.
+
+**Never re-derive the org from the scope in a new layer.** Each layer used to, with its own condition, and they drifted: `crossTenant` was taught to three of four read layers (`get` silently ignored it for signed-in members), bulk writes skipped the org for ANY elevated admin (an admin acting as org-9 deleted across every tenant), and `realtime` withheld the platform view that reads grant. The union is exhaustive, so a new mode is a compile error in every consumer that has not handled it.
+
+The cache key (`deriveCacheScope`) deliberately does NOT use it: it answers "whose cache partition", which on a cross-tenant read is still the caller's org — dropping it could let one org's cached page answer another's.
 
 ## Filter composition
 
@@ -101,19 +107,18 @@ Return the scope directly from your permission check. This is the cleanest integ
 
 ```ts
 // src/permissions/apiKey.ts
-import type { PermissionCheck } from '@classytic/arc/permissions';
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
 import { ClientModel } from '../models/Client.js';
 
 export function requireApiKey(): PermissionCheck {
   return async ({ request }) => {
     const apiKey = request.headers['x-api-key'] as string | undefined;
-    if (!apiKey) return { granted: false, reason: 'Missing API key' };
+    if (!apiKey) return deny('Missing API key');
 
     const client = await ClientModel.findOne({ apiKey });
-    if (!client) return { granted: false, reason: 'Invalid API key' };
+    if (!client) return deny('Invalid API key');
 
-    return {
-      granted: true,
+    return allow({
       scope: {
         kind: 'service',
         clientId: String(client._id),
@@ -121,8 +126,8 @@ export function requireApiKey(): PermissionCheck {
         scopes: client.allowedScopes,  // optional OAuth-style scope strings
       },
       // Optional additional row-level narrowing
-      filters: client.projectId ? { projectId: client.projectId } : undefined,
-    };
+      ...(client.projectId ? { policy: { projectId: client.projectId } } : {}),
+    });
   };
 }
 ```

package/skills/arc/references/production.md

@@ -76,8 +76,8 @@ Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives.
 
 `drainDelayMs` is the window between "start failing readiness" and "stop accepting":
 
-- `/health/ready` → `503 { status: 'draining' }` immediately on signal
-- `/health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
+- `/_health/ready` → `503 { status: 'draining' }` immediately on signal
+- `/_health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
 - everything already routed here is still served for the whole window
 
 Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
@@ -299,7 +299,7 @@ const app = await createApp({
       path: '/events/stream',       // SSE endpoint (default: '/events/stream')
       requireAuth: true,            // Fail-closed auth (default: true)
       patterns: ['order.*', 'product.*'],  // Event patterns to stream (default: ['*'])
-      orgScoped: false,             // Filter events by org from request.scope (default: false)
+      // orgScoped defaults to TRUE (2.41.1) — a caller only sees its own org's events.
       heartbeat: 30000,             // Heartbeat interval in ms (default: 30000)
     },
   },
@@ -307,7 +307,7 @@ const app = await createApp({
 
 // Manual registration
 import { ssePlugin } from '@classytic/arc/plugins';
-await fastify.register(ssePlugin, { requireAuth: true, orgScoped: true });
+await fastify.register(ssePlugin, { requireAuth: true });
 ```
 
 ### Realtime resource change feed (2.22)
@@ -322,12 +322,9 @@ row-permissioned resources through it); event firehose → sse. Massive fan-out
 (viral feeds, live scores) → publish once to a dedicated edge fan-out layer
 via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
 
-```typescript
-```
-
 **Fail-closed auth:** When `requireAuth: true` (default), throws at registration if `fastify.authenticate` is missing — prevents exposing SSE without auth.
 
-**Org-scoped:** When `orgScoped: true`, events with `organizationId` are only sent to clients whose `request.scope` matches. Prevents cross-tenant leakage.
+**Org-scoped by default (2.41.1):** an event carrying `organizationId` reaches only callers in that org. It defaulted to `false` — with `patterns: ['*']`, one tenant's member received every tenant's events, full documents included. Events with no `organizationId` still reach everyone, so single-tenant apps are unaffected; an elevated admin with no active org sees all tenants (the platform view). `orgScoped: false` is for a deliberately cross-tenant stream only — keep `requireAuth` and add a `filter`.
 
 ## Error Handler Plugin
 
@@ -383,7 +380,7 @@ return reply.header('content-type', 'text/csv').send(readableStream);
 
 ### BigInt Serialization
 
-Opt-in: `createApp({ serializeBigInt: true })` — auto-converts BigInt → Number in all JSON responses.
+Opt-in: `createApp({ serializeBigInt: 'string' })` — BigInt → decimal string in JSON responses (lossless); `'number'` is lossy above 2^53-1.
 
 ## Multipart Body Middleware (v2.7.3)
 
@@ -678,7 +675,27 @@ await outbox.store(event, { session });
 const relayed = await outbox.relay();  // publishes pending → transport
 ```
 
-**OutboxStore interface**: `save(event)`, `getPending(limit)`, `acknowledge(eventId)` (+ optional `claimPending`, `fail`, `getDeadLettered`, `purge`). When you pass `repository`, arc adapts it internally.
+**Prefer the module form** — it owns the relay schedule, shutdown, and a readiness check, so none of that is hand-wired:
+
+```typescript
+import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
+
+const outbox = createOutboxModule({
+  store: repositoryAsOutboxStore(new Repository(OutboxModel)),
+  // Bounds retries AND log volume. `attempts` is the DURABLE count (it survives relay
+  // restarts and is shared across relays), so a poison event really does stop at 5.
+  failurePolicy: ({ attempts }) =>
+    attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
+  health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5_000 },
+});
+// createApp({ modules: [outbox] }); consumers declare dependsOn: ['outbox'].
+```
+
+- `requestDrain()` — nudge a pass after commit (milliseconds, not `relayEveryMs`); runs outside the caller's request scope.
+- `drain()` — await delivery, cascades included. For tests and a shutdown that should empty the queue.
+- `health()` + readiness check `<name>.relay` — **non-critical** (a stalled relay is a cluster problem; pulling one pod would not drain it). Unhealthy on any dead letter or pending lag past the threshold. The probe reuses a reading for `probeCacheMs` so N replicas × probe rate do not become N count queries a second on the outbox table.
+
+**OutboxStore contract** (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending` / `claimPendingFenced` (lease + fencing token, and the durable `attempts`), `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`. When you pass `repository`, arc adapts it internally.
 
 ## Bulk Operations Preset
 

package/dist/actionPermissions-DPwPWPOV.mjs

@@ -1,350 +0,0 @@
-/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
-import { n as getUserRoles } from "./userHelpers-DDMOZ_Pm.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CDy3-zw1.mjs";
-import { a as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-BTyPLHK0.mjs";
-import { t as buildRequestScopeProjection } from "./projection-Uvgp-EEj.mjs";
-import { t as executePipeline } from "./pipe-CBVmUJ-j.mjs";
-import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
-//#region src/core/fastifyAdapter.ts
-/** Type guard for Mongoose-like documents with toObject() */
-function isMongooseDoc(obj) {
-	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
-}
-/**
-* Apply field mask to a single object
-* Filters fields based on include/exclude rules
-*/
-function applyFieldMaskToObject(obj, fieldMask) {
-	if (!obj || typeof obj !== "object") return obj;
-	const plain = isMongooseDoc(obj) ? obj.toObject() : obj;
-	const { include, exclude } = fieldMask;
-	if (include && include.length > 0) {
-		const filtered = {};
-		for (const field of include) if (field in plain) filtered[field] = plain[field];
-		return filtered;
-	}
-	if (exclude && exclude.length > 0) {
-		const filtered = { ...plain };
-		for (const field of exclude) delete filtered[field];
-		return filtered;
-	}
-	return plain;
-}
-/**
-* Apply field mask to response data (handles both objects and arrays)
-*/
-function applyFieldMask(data, fieldMask) {
-	if (!fieldMask) return data;
-	if (Array.isArray(data)) return data.map((item) => applyFieldMaskToObject(item, fieldMask));
-	if (data && typeof data === "object") return applyFieldMaskToObject(data, fieldMask);
-	return data;
-}
-/**
-* Project `FastifyRequest` into the curated `IRequestContext` shape that
-* arc's controllers receive. This is a developer-facing facade, not a
-* portability boundary — arc is Fastify-only. The projection lifts the
-* fields tenant-scoped controllers reach for (`organizationId`,
-* `teamId`, `scope`, `context`, server accessor) onto a flat, typed
-* surface so handler code doesn't have to dig through Fastify's
-* decorator surface or `req.metadata._scope` internals.
-*/
-function createRequestContext(req) {
-	const reqWithExtras = req;
-	const requestContext = reqWithExtras.context ?? {};
-	const srv = req.server;
-	const serverAccessor = {
-		events: srv && "events" in srv ? srv.events : void 0,
-		audit: srv && "audit" in srv ? srv.audit : void 0,
-		queryCache: srv && "queryCache" in srv ? srv.queryCache : void 0,
-		log: req.log
-	};
-	const rawScope = reqWithExtras.scope;
-	const scopeProjection = buildRequestScopeProjection(rawScope);
-	return {
-		query: reqWithExtras.query ?? {},
-		body: reqWithExtras.body ?? {},
-		params: reqWithExtras.params ?? {},
-		headers: reqWithExtras.headers,
-		user: reqWithExtras.user ? (() => {
-			const user = reqWithExtras.user;
-			const rawId = user._id ?? user.id;
-			const normalizedId = rawId ? String(rawId) : void 0;
-			return {
-				...user,
-				id: normalizedId,
-				_id: normalizedId
-			};
-		})() : null,
-		context: requestContext,
-		scope: scopeProjection,
-		metadata: {
-			...reqWithExtras.context,
-			arc: reqWithExtras.arc,
-			_scope: rawScope,
-			_ownershipCheck: reqWithExtras._ownershipCheck,
-			_crossTenantRead: reqWithExtras._crossTenantRead,
-			_policyFilters: reqWithExtras._policyFilters ?? {},
-			log: reqWithExtras.log
-		},
-		server: serverAccessor
-	};
-}
-/**
-* Get typed auth context from an IRequestContext.
-* Use this in controller overrides to access request context.
-*
-* For org scope, use `getControllerScope(req)` instead.
-*/
-function getControllerContext(req) {
-	return req.context ?? req.metadata ?? {};
-}
-/**
-* Get request scope from an IRequestContext.
-* Returns the RequestScope set by auth adapters.
-*/
-function getControllerScope(req) {
-	return req.metadata?._scope ?? PUBLIC_SCOPE;
-}
-/**
-* Compute per-field capability metadata for the current user.
-* Only includes fields that have restrictions — unrestricted fields
-* are omitted (frontend defaults to { readable: true, writable: true }).
-*/
-function computeFieldCapabilities(fieldPerms, effectiveRoles) {
-	const caps = {};
-	for (const [field, perm] of Object.entries(fieldPerms)) {
-		let readable = true;
-		let writable = true;
-		switch (perm._type) {
-			case "hidden":
-				readable = false;
-				writable = false;
-				break;
-			case "visibleTo":
-				readable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
-				break;
-			case "writableBy": writable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
-		}
-		caps[field] = {
-			readable,
-			writable
-		};
-	}
-	return caps;
-}
-/**
-* Send a controller's `IControllerResponse` through Fastify's reply.
-*
-* The `IControllerResponse<T>` envelope is arc's internal pipeline
-* contract — it's how custom `status`, `meta`, `headers`, and field
-* permissions thread from a handler through interceptors to the wire
-* without each step having to touch `reply` directly. Not a portability
-* abstraction (arc is Fastify-only); a pipeline-internal one.
-*
-* **Auto-envelope of bare returns.** Custom route handlers are
-* expected to return the envelope shape so this function can apply
-* field permissions, attach `fieldCaps`, and flatten paginated lists.
-* A handler that returns raw `T` (array, plain object, primitive) used
-* to silently produce a broken response — `response.data` was
-* `undefined`, the body sent was `undefined`, and any declared
-* `fields:` permission map was bypassed (the leak shape mentora
-* flagged). 2.17 detects bare returns and wraps them into
-* `{ data: response, status: 200 }` before the field-permission
-* pipeline runs, so `fields:` applies to ALL custom routes whether the
-* handler envelopes its return value or not. The envelope shape is
-* still the canonical contract — auto-wrapping is a safety net, not
-* an invitation to drop the envelope.
-*/
-function sendControllerResponse(reply, response, request) {
-	if (response === null || typeof response !== "object" || !Object.hasOwn(response, "data")) response = {
-		data: response,
-		status: 200
-	};
-	const reqWithExtras = request;
-	const fieldMaskConfig = reqWithExtras?.fieldMask;
-	const arcMeta = reqWithExtras?.arc;
-	const scope = reqWithExtras?.scope ?? PUBLIC_SCOPE;
-	const fieldPerms = isElevated(scope) ? void 0 : arcMeta?.fields;
-	const effectiveRoles = fieldPerms ? resolveEffectiveRoles(getUserRoles(reqWithExtras?.user), isMember(scope) ? scope.orgRoles : []) : [];
-	const fieldCaps = fieldPerms ? computeFieldCapabilities(fieldPerms, effectiveRoles) : void 0;
-	const hasFieldRestrictions = !!(fieldMaskConfig || fieldPerms);
-	/** Apply both field mask and field-level permissions to a data item */
-	const applyPermissions = (data) => {
-		let result = fieldMaskConfig ? applyFieldMask(data, fieldMaskConfig) : data;
-		if (fieldPerms && result && typeof result === "object") {
-			if (Array.isArray(result)) result = result.map((item) => applyFieldReadPermissions(item, fieldPerms, effectiveRoles));
-			else result = applyFieldReadPermissions(result, fieldPerms, effectiveRoles);
-		}
-		return result;
-	};
-	if (response.headers) for (const [key, value] of Object.entries(response.headers)) reply.header(key, value);
-	if (response.data && typeof response.data === "object" && Array.isArray(response.data.data)) {
-		const payload = response.data;
-		const filteredRows = hasFieldRestrictions ? applyPermissions(payload.data) : payload.data;
-		let canonical;
-		if (isPaginatedResult(payload)) canonical = toCanonicalList({
-			...payload,
-			data: filteredRows
-		});
-		else if (typeof payload.page === "number" && typeof payload.limit === "number" && typeof payload.total === "number") canonical = toCanonicalList({
-			method: "offset",
-			data: filteredRows,
-			page: payload.page,
-			limit: payload.limit,
-			total: payload.total,
-			pages: payload.pages ?? Math.ceil(payload.total / Math.max(1, payload.limit)),
-			hasNext: payload.hasNext ?? false,
-			hasPrev: payload.hasPrev ?? false
-		});
-		else canonical = toCanonicalList(filteredRows);
-		reply.code(response.status ?? 200).send({
-			...canonical,
-			...response.meta ?? {},
-			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
-		});
-		return;
-	}
-	const rawData = hasFieldRestrictions ? applyPermissions(response.data) : response.data;
-	const filteredData = rawData !== null && typeof rawData === "object" && typeof rawData.toJSON === "function" ? rawData.toJSON() : rawData;
-	const status = response.status ?? 200;
-	if (filteredData !== null && typeof filteredData === "object" && !Array.isArray(filteredData) && (response.meta || fieldCaps)) {
-		reply.code(status).send({
-			...filteredData,
-			...response.meta ?? {},
-			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
-		});
-		return;
-	}
-	reply.code(status).send(filteredData);
-}
-/**
-* Bridge an `IController` method (`(ctx: IRequestContext) => Promise<IControllerResponse<T>>`)
-* into a Fastify route handler. Translates between arc's curated request
-* context surface and Fastify's request/reply, and routes the envelope
-* through `sendControllerResponse` so the pipeline applies field
-* permissions, status, and meta uniformly. Internal plumbing, not a
-* portability layer — arc is Fastify-only.
-*
-* @example
-* ```typescript
-* const controller = new BaseController(repository);
-* const listHandler = createFastifyHandler(controller.list.bind(controller));
-* fastify.get('/products', listHandler);
-* ```
-*/
-function createFastifyHandler(controllerMethod) {
-	return async (req, reply) => {
-		sendControllerResponse(reply, await controllerMethod(createRequestContext(req)), req);
-		return reply;
-	};
-}
-/**
-* Create Fastify adapters for all CRUD methods of an IController
-*
-* Returns Fastify-compatible handlers for each CRUD operation
-*
-* @example
-* ```typescript
-* const controller = new BaseController(repository);
-* const handlers = createCrudHandlers(controller);
-*
-* fastify.get('/', handlers.list);
-* fastify.get('/:id', handlers.get);
-* fastify.post('/', handlers.create);
-* fastify.patch('/:id', handlers.update);
-* fastify.delete('/:id', handlers.delete);
-* ```
-*/
-function createCrudHandlers(controller) {
-	return {
-		list: createFastifyHandler(controller.list.bind(controller)),
-		get: createFastifyHandler(controller.get.bind(controller)),
-		create: createFastifyHandler(controller.create.bind(controller)),
-		update: createFastifyHandler(controller.update.bind(controller)),
-		delete: createFastifyHandler(controller.delete.bind(controller))
-	};
-}
-//#endregion
-//#region src/core/middlewares/pipeline.ts
-/**
-* Resolve pipeline steps for a specific operation.
-* Flat-array config applies to every op; map config applies per-op.
-*/
-function resolvePipelineSteps(pipeline, operation) {
-	if (!pipeline) return [];
-	if (Array.isArray(pipeline)) return pipeline;
-	return pipeline[operation] ?? [];
-}
-/**
-* Wrap a controller method (one that takes `IRequestContext` and returns
-* `IControllerResponse<T>`) with pipeline execution. Used by CRUD ops and
-* string-handler custom routes.
-*/
-function buildPipelineHandler(controllerMethod, steps, operation, resourceName) {
-	return async (req, reply) => {
-		const pipeCtx = {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		};
-		sendControllerResponse(reply, await executePipeline(steps, pipeCtx, (ctx) => controllerMethod(ctx), operation), req);
-	};
-}
-/**
-* Wrap an action handler (one that takes `(id, data, req)` and returns a raw
-* result) with pipeline execution. Returns a function that produces a full
-* `IControllerResponse<unknown>` — the action router feeds this directly into
-* `sendControllerResponse`, so field masking, custom status codes, `meta`,
-* `details`, and structured error codes from pipeline interceptors flow
-* through to the client unchanged.
-*
-* CRUD and actions now share the same parity invariant: a pipeline that
-* returns `{ success: false, status: 422, error, details, meta }` reaches the
-* client with all four fields intact. Previously the action path stringified
-* failures into a generic `Error` and dropped everything except `statusCode`.
-*
-* Handler throws still bubble out — the caller's try/catch handles `onError`
-* shaping and the generic `ACTION_FAILED` fallback.
-*/
-function buildActionPipelineHandler(handler, steps, operation, resourceName) {
-	if (steps.length === 0) return async (id, data, req) => ({
-		status: 200,
-		data: await handler(id, data, req)
-	});
-	return async (id, data, req) => {
-		const pipeCtx = {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		};
-		return executePipeline(steps, pipeCtx, async (_ctx) => ({
-			status: 200,
-			data: await handler(id, data, req)
-		}), operation);
-	};
-}
-//#endregion
-//#region src/core/actionPermissions.ts
-/**
-* Return the effective `PermissionCheck` for a single action, or `undefined`
-* when the resource declares no gate at any level.
-*
-* Callers decide what "no gate" means:
-*   - HTTP: boot-time throw in `normalizeActionsToRouterConfig`.
-*   - MCP: tool-generation throw in `resourceToTools` (mirrors HTTP — the
-*     two surfaces fail closed identically so MCP can't expose an
-*     unauthenticated mutating tool when the HTTP plugin lifecycle hasn't
-*     run).
-*   - OpenAPI: docs advertise the endpoint as unauthenticated.
-*/
-function resolveActionPermission(input) {
-	const { action, resourcePermissions, resourceActionPermissions, globalAuth } = input;
-	const explicit = typeof action !== "function" && action.permissions ? action.permissions : void 0;
-	if (explicit) return explicit;
-	if (resourceActionPermissions) return resourceActionPermissions;
-	if (globalAuth) return globalAuth;
-	const updateFallback = resourcePermissions?.update;
-	if (updateFallback) return updateFallback;
-}
-//#endregion
-export { createCrudHandlers as a, getControllerContext as c, resolvePipelineSteps as i, getControllerScope as l, buildActionPipelineHandler as n, createFastifyHandler as o, buildPipelineHandler as r, createRequestContext as s, resolveActionPermission as t, sendControllerResponse as u };