@classytic/arc 2.15.4 → 2.16.1

package/dist/registry-BrlHkrRS.mjs

@@ -0,0 +1,582 @@
+import { t as CRUD_OPERATIONS } from "./constants-TrJVIJl0.mjs";
+import fp from "fastify-plugin";
+//#region src/registry/assertNoTenantData.ts
+/**
+* Walk every cascading resource, run a tenant-scoped count, compare
+* against the strategy's expected outcome.
+*
+* Designed for use inside compliance tests:
+*
+* ```ts
+* import { assertNoTenantData } from '@classytic/arc/registry';
+*
+* it('after org delete, no tenant data leaks', async () => {
+*   await cascadeDeleteForOrganization(arc.registry, { organizationId: 'test-org' });
+*   const report = await assertNoTenantData(arc.registry, { organizationId: 'test-org' });
+*   expect(report.ok).toBe(true);
+*   expect(report.leaks).toHaveLength(0);
+* });
+* ```
+*/
+async function assertNoTenantData(registry, options) {
+	const { organizationId, only, skipAnonymize = true } = options;
+	if (!organizationId) throw new Error("assertNoTenantData: `organizationId` is required");
+	const onlySet = only ? new Set(only) : void 0;
+	const leaks = [];
+	const skipped = [];
+	let checked = 0;
+	for (const r of registry.getAll()) {
+		const resolved = r.resolvedTenantPurge;
+		if (!resolved || resolved.source === "disabled") continue;
+		if (onlySet && !onlySet.has(r.name)) continue;
+		const tenantField = typeof r.tenantField === "string" && r.tenantField || "organizationId";
+		const strategy = resolved.strategy;
+		if (strategy.type === "skip") {
+			skipped.push({
+				resource: r.name,
+				reason: strategy.reason
+			});
+			continue;
+		}
+		if (strategy.type === "anonymize" && skipAnonymize) {
+			skipped.push({
+				resource: r.name,
+				reason: "anonymize (rows legitimately retained)"
+			});
+			continue;
+		}
+		const repo = registry.getAdapter(r.name)?.repository;
+		if (!repo?.count) {
+			skipped.push({
+				resource: r.name,
+				reason: "adapter repository has no `count` method — cannot verify"
+			});
+			continue;
+		}
+		const actual = await repo.count({ [tenantField]: organizationId });
+		checked++;
+		const expected = 0;
+		if (actual !== expected) leaks.push({
+			resource: r.name,
+			tenantField,
+			strategy,
+			expected,
+			actual
+		});
+	}
+	return {
+		ok: leaks.length === 0,
+		organizationId,
+		checked,
+		skipped,
+		leaks
+	};
+}
+//#endregion
+//#region src/registry/purgeResource.ts
+/**
+* Run the resolved strategy against one resource's repository.
+*
+* - `skip` strategy: returns `path: 'skipped'` without touching the repo.
+* - `purgeByField` present: routes through it (chunked, progress, abort).
+* - `purgeByField` absent + hard strategy: legacy `deleteMany` fallback.
+* - `purgeByField` absent + non-hard strategy: returns `path: 'unsupported'`
+*   with a clear error — soft/anonymize require the new primitive.
+*/
+async function purgeResource(resourceName, tenantField, organizationId, resolved, repo, options = {}) {
+	const { strategy } = resolved;
+	if (strategy.type === "skip") return {
+		resource: resourceName,
+		tenantField,
+		strategy,
+		processed: 0,
+		ok: true,
+		path: "skipped",
+		skipReason: strategy.reason
+	};
+	if (typeof repo.purgeByField === "function") {
+		const result = await repo.purgeByField(tenantField, organizationId, strategy, {
+			batchSize: options.batchSize ?? resolved.batchSize,
+			onProgress: options.onProgress,
+			signal: options.signal
+		});
+		return {
+			resource: resourceName,
+			tenantField,
+			strategy,
+			processed: result.processed,
+			ok: result.ok,
+			path: "purgeByField",
+			durationMs: result.durationMs,
+			...result.error ? { error: result.error } : {}
+		};
+	}
+	if (strategy.type !== "hard") return {
+		resource: resourceName,
+		tenantField,
+		strategy,
+		processed: 0,
+		ok: false,
+		path: "unsupported",
+		error: {
+			code: "arc.purge.unsupported_strategy",
+			message: `Resource '${resourceName}' uses strategy '${strategy.type}' but its adapter repository does not implement \`purgeByField\`. Upgrade the adapter (@classytic/mongokit ≥ 3.13.4 / @classytic/sqlitekit ≥ 0.3.4) or change the strategy to 'hard'.`
+		}
+	};
+	const op = repo.deleteMany ?? repo.deleteByFilter ?? repo.removeMany;
+	if (!op) return {
+		resource: resourceName,
+		tenantField,
+		strategy,
+		processed: 0,
+		ok: false,
+		path: "unsupported",
+		error: {
+			code: "arc.purge.no_bulk_op",
+			message: `Resource '${resourceName}' adapter exposes neither \`purgeByField\` nor \`deleteMany\` / \`deleteByFilter\` / \`removeMany\` — bulk cleanup is not supported.`
+		}
+	};
+	try {
+		const start = Date.now();
+		const result = await op.call(repo, { [tenantField]: organizationId });
+		return {
+			resource: resourceName,
+			tenantField,
+			strategy,
+			processed: typeof result === "number" ? result : typeof result?.deletedCount === "number" ? result.deletedCount : typeof result?.count === "number" ? result.count : -1,
+			ok: true,
+			path: "legacy-deleteMany",
+			durationMs: Date.now() - start
+		};
+	} catch (err) {
+		return {
+			resource: resourceName,
+			tenantField,
+			strategy,
+			processed: 0,
+			ok: false,
+			path: "legacy-deleteMany",
+			error: {
+				code: err?.code,
+				message: err instanceof Error ? err.message : String(err)
+			}
+		};
+	}
+}
+//#endregion
+//#region src/registry/cascadeOrgDelete.ts
+/**
+* Names of resources flagged for cascade — used by audit scripts.
+* A resource is cascading when its resolved strategy isn't `disabled`
+* (i.e. the host declared `onTenantDelete`).
+*/
+function getCascadingResources(registry) {
+	return registry.getAll().filter((r) => isResourceCascading(r)).map((r) => r.name);
+}
+/**
+* Rich introspection — returns the resolved strategy + source per
+* cascading resource. Use for audit dashboards that answer "what
+* happens to this resource on org-delete?" without grepping the
+* source.
+*
+* **Returns the full `TenantPurgeStrategy` discriminated union**, not
+* just its `type` tag. The `skip` variant carries a required `reason`
+* field — auditors need it to sign off on every "we deliberately don't
+* purge this" entry. Anonymize carries the field map. Custom carries
+* the handler reference. Narrow on `.strategy.type` for typed access.
+*/
+function getCascadingResourcesWithMetadata(registry) {
+	return registry.getAll().filter((r) => isResourceCascading(r)).map((r) => {
+		const resolved = r.resolvedTenantPurge;
+		const tenantField = typeof r.tenantField === "string" && r.tenantField || "organizationId";
+		const r0 = resolved ?? {
+			strategy: { type: "hard" },
+			priority: 100,
+			source: "declared"
+		};
+		return {
+			name: r.name,
+			tenantField,
+			strategy: r0.strategy,
+			source: r0.source,
+			priority: r0.priority
+		};
+	});
+}
+/** A resource cascades iff its resolved strategy isn't `disabled`. */
+function isResourceCascading(r) {
+	return r.resolvedTenantPurge ? r.resolvedTenantPurge.source !== "disabled" : false;
+}
+/**
+* Cascade-cleanup every tenant-scoped resource for the given organization.
+* Walks the registry in **ascending priority order** (`onTenantDelete.priority`
+* — leaf data first, references last), runs each resource's resolved
+* strategy via `purgeByField` when available (chunked, progress, abort),
+* and returns a structured report.
+*
+* **Strategy resolution** lives in `resolveTenantPurge.ts` — this runner
+* just reads `resource.resolvedTenantPurge` (computed once at boot).
+*
+* **Per-resource execution** lives in `purgeResource.ts` — preferred
+* path is the kit's `purgeByField` (chunked + plugin-composed); falls
+* back to legacy `deleteMany` only for `hard` strategy on adapters that
+* haven't been upgraded.
+*
+* **Failure semantics**: continues on per-resource error, returns the
+* full report. Hosts decide whether a partial cascade is a hard
+* failure (re-throw) or degraded mode (log + alert).
+*
+* @param registry  The arc resource registry (`fastify.arc.registry`).
+* @param options   Org id + filters + logger + progress + signal.
+*/
+async function cascadeDeleteForOrganization(registry, options) {
+	const { organizationId, skip, only, logger, onProgress, signal, batchSize, concurrency = 1, checkpoint } = options;
+	if (!organizationId) throw new Error("cascadeDeleteForOrganization: `organizationId` is required");
+	if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error("cascadeDeleteForOrganization: `concurrency` must be a positive integer");
+	const skipSet = skip ? new Set(skip) : void 0;
+	const onlySet = only ? new Set(only) : void 0;
+	const start = Date.now();
+	const resumeState = await checkpoint?.read();
+	const completedSet = resumeState ? new Set(resumeState.completedResources) : void 0;
+	const flagged = registry.getAll().filter((r) => {
+		if (!r.resolvedTenantPurge || r.resolvedTenantPurge.source === "disabled") return false;
+		if (skipSet?.has(r.name)) return false;
+		if (onlySet && !onlySet.has(r.name)) return false;
+		if (completedSet?.has(r.name)) return false;
+		return true;
+	}).sort((a, b) => {
+		return (a.resolvedTenantPurge?.priority ?? 100) - (b.resolvedTenantPurge?.priority ?? 100);
+	});
+	const results = [];
+	const completed = resumeState ? [...resumeState.completedResources] : [];
+	const groups = groupByPriority(flagged);
+	for (const group of groups) {
+		if (signal?.aborted) break;
+		const groupResults = await runWithConcurrency(group, concurrency, async (r) => {
+			if (signal?.aborted) return;
+			return runOneResource(r, registry, organizationId, {
+				onProgress,
+				signal,
+				batchSize,
+				logger
+			});
+		});
+		for (const report of groupResults) {
+			if (!report) continue;
+			results.push(report);
+			if (!report.error) {
+				completed.push(report.resource);
+				if (checkpoint) await checkpoint.write({ completedResources: [...completed] });
+			}
+		}
+	}
+	const successes = results.filter((row) => !row.error);
+	return {
+		organizationId,
+		resources: results,
+		successes,
+		failures: results.filter((row) => row.error),
+		totalDeleted: successes.reduce((sum, r) => sum + (r.deletedCount > 0 ? r.deletedCount : 0), 0),
+		durationMs: Date.now() - start
+	};
+}
+/** Process a single registry entry under its resolved strategy. */
+async function runOneResource(r, registry, organizationId, ctx) {
+	const tenantField = typeof r.tenantField === "string" && r.tenantField || "organizationId";
+	const repo = registry.getAdapter(r.name)?.repository;
+	if (!repo) {
+		const report = {
+			resource: r.name,
+			tenantField,
+			deletedCount: 0,
+			path: "unsupported",
+			error: {
+				code: "arc.no_adapter",
+				message: `Resource '${r.name}' has no adapter repository — cascade skipped`
+			}
+		};
+		ctx.logger?.warn?.(report, "[Arc/Cascade] resource skipped (no adapter)");
+		return report;
+	}
+	const resourceProgress = ctx.onProgress ? (event) => ctx.onProgress?.({
+		...event,
+		resource: r.name
+	}) : void 0;
+	const outcome = await purgeResource(r.name, tenantField, organizationId, r.resolvedTenantPurge ?? {
+		strategy: { type: "hard" },
+		priority: 100,
+		source: "declared"
+	}, repo, {
+		onProgress: resourceProgress,
+		signal: ctx.signal,
+		batchSize: ctx.batchSize
+	});
+	const report = {
+		resource: outcome.resource,
+		tenantField: outcome.tenantField,
+		deletedCount: outcome.processed,
+		strategy: outcome.strategy,
+		strategySource: r.resolvedTenantPurge?.source,
+		path: outcome.path,
+		...outcome.skipReason ? { skipReason: outcome.skipReason } : {},
+		...outcome.error ? { error: outcome.error } : {}
+	};
+	if (outcome.ok) ctx.logger?.info?.(report, "[Arc/Cascade] resource processed");
+	else ctx.logger?.error?.({ report }, "[Arc/Cascade] resource cascade failed");
+	return report;
+}
+/**
+* Group a priority-sorted list of resources into priority barriers.
+* Each returned sub-array contains resources of identical priority;
+* the outer array preserves ascending order. The cascade runner uses
+* this so all priority-N resources finish before any priority-(N+M)
+* starts — leaf-before-references invariant survives concurrency.
+*/
+function groupByPriority(sorted) {
+	if (sorted.length === 0) return [];
+	const first = sorted[0];
+	if (!first) return [];
+	const groups = [];
+	let current = [first];
+	let currentPriority = first.resolvedTenantPurge?.priority ?? 100;
+	for (let i = 1; i < sorted.length; i++) {
+		const item = sorted[i];
+		if (!item) continue;
+		const p = item.resolvedTenantPurge?.priority ?? 100;
+		if (p === currentPriority) current.push(item);
+		else {
+			groups.push(current);
+			current = [item];
+			currentPriority = p;
+		}
+	}
+	groups.push(current);
+	return groups;
+}
+/**
+* Run `fn` over `items` with bounded concurrency. Order of results
+* matches input order. Simpler shape than a worker-pool because the
+* group sizes are small (typically <=12 resources per priority band).
+*/
+async function runWithConcurrency(items, concurrency, fn) {
+	if (concurrency === 1 || items.length <= 1) {
+		const results = [];
+		for (const item of items) results.push(await fn(item));
+		return results;
+	}
+	const results = new Array(items.length);
+	let cursor = 0;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (true) {
+			const i = cursor++;
+			if (i >= items.length) break;
+			const item = items[i];
+			if (item === void 0) continue;
+			results[i] = await fn(item);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+//#endregion
+//#region src/registry/introspectionPlugin.ts
+const introspectionPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_resources", authRoles = ["superadmin"], enabled = true } = opts;
+	if (!enabled) {
+		fastify.log?.debug?.("Introspection plugin disabled");
+		return;
+	}
+	const typedFastify = fastify;
+	const authMiddleware = authRoles.length > 0 && typedFastify.authenticate ? [typedFastify.authenticate, typedFastify.authorize?.(...authRoles)].filter(Boolean) : [];
+	const getRegistry = () => fastify.arc?.registry;
+	await fastify.register(async (instance) => {
+		instance.get("/", { preHandler: authMiddleware }, async (_req, _reply) => {
+			return getRegistry()?.getIntrospection() ?? {
+				resources: [],
+				stats: {},
+				generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		});
+		instance.get("/stats", { preHandler: authMiddleware }, async (_req, _reply) => {
+			return getRegistry()?.getStats() ?? {
+				totalResources: 0,
+				byModule: {},
+				presetUsage: {},
+				totalRoutes: 0,
+				totalEvents: 0
+			};
+		});
+		instance.get("/:name", {
+			schema: { params: {
+				type: "object",
+				properties: { name: { type: "string" } },
+				required: ["name"]
+			} },
+			preHandler: authMiddleware
+		}, async (req, reply) => {
+			const resource = getRegistry()?.get(req.params.name);
+			if (!resource) return reply.code(404).send({ error: `Resource '${req.params.name}' not found` });
+			return resource;
+		});
+	}, { prefix });
+	fastify.log?.debug?.(`Introspection API at ${prefix}`);
+};
+var introspectionPlugin_default = fp(introspectionPlugin, { name: "arc-introspection" });
+//#endregion
+//#region src/registry/manifest.ts
+/**
+* Resource manifest for frontend code generators (v2.15.5).
+*
+* Every host that hand-rolls a `createCrudApi('foo')` helper on the frontend
+* ends up rewriting the same shim for declarative actions: `postAction(id,
+* name, body)` — and forgets to add a method for every NEW action declared
+* on the resource. The OpenAI-team report flagged this in fajr's
+* `invoices.js`, and now matches needs the same.
+*
+* Arc owns the resource definition, so arc can ship the metadata FE codegen
+* needs in one canonical shape:
+*
+*   {
+*     name: 'invoice',
+*     prefix: '/invoices',
+*     idField: '_id',
+*     crudOps: ['list', 'get', 'create', 'update', 'delete'],
+*     actions: [
+*       { name: 'recordPayment', mount: '/:id/action', requiresId: true,  description: '...' },
+*       { name: 'propose',       mount: '/action',     requiresId: false, description: '...' },
+*     ],
+*   }
+*
+* Hosts feed this into their FE generator (or a runtime `createActionsApi`
+* shim) and every action is wired automatically. New actions land on the FE
+* the same moment they're declared on the resource — no parallel list to
+* keep in sync.
+*
+* The helper is BE-side only (lives under `@classytic/arc/registry`) — arc
+* stays a backend framework and doesn't ship FE runtime code. The host
+* decides whether the manifest powers a fetch-based helper, a TanStack
+* Query factory, an RPC client, or static `.d.ts` generation.
+*
+* @example BE → emit JSON at build time / on a route
+* ```ts
+* // Build-time codegen
+* import { buildResourceManifest } from '@classytic/arc/registry';
+* import { invoiceResource } from './invoice.resource.js';
+* writeFileSync('./fe-gen/invoice.manifest.json',
+*   JSON.stringify(buildResourceManifest(invoiceResource)));
+*
+* // Runtime introspection endpoint
+* fastify.get('/manifest/:name', async (req) => {
+*   const r = arc.registry.get(req.params.name);
+*   return r ? buildResourceManifestFromRegistry(r) : reply.code(404);
+* });
+* ```
+*
+* @example FE → generate fetch methods from the manifest
+* ```ts
+* import manifest from './fe-gen/invoice.manifest.json';
+* import { createActionsApi } from './my-fe-shim.js';  // host-owned
+*
+* export const invoicesApi = {
+*   ...createCrudApi(manifest.prefix),
+*   ...createActionsApi(manifest.prefix, manifest.actions),
+*   // → invoicesApi.recordPayment(id, body)
+*   // → invoicesApi.propose(body)        // id-less
+* };
+* ```
+*/
+/**
+* Build a manifest from a `ResourceDefinition` (the value returned by
+* `defineResource(...)`). Use at build time when you have direct access
+* to the resource module — typically the simplest codegen path.
+*/
+function buildResourceManifest(resource) {
+	const disabled = new Set(resource.disabledRoutes ?? []);
+	const crudOps = resource.disableDefaultRoutes ? [] : CRUD_OPERATIONS.filter((op) => !disabled.has(op));
+	const actions = [];
+	for (const [name, entry] of Object.entries(resource.actions ?? {})) {
+		const requiresId = typeof entry === "function" ? true : entry.id !== false;
+		actions.push({
+			name,
+			mount: requiresId ? "/:id/action" : "/action",
+			requiresId,
+			...typeof entry !== "function" && entry.description ? { description: entry.description } : {}
+		});
+	}
+	const aggregations = [];
+	for (const [name, agg] of Object.entries(resource.aggregations ?? {})) aggregations.push({
+		name,
+		path: `${resource.prefix}/aggregations/${name}`,
+		...agg.summary ? { summary: agg.summary } : {},
+		...agg.description ? { description: agg.description } : {}
+	});
+	const customRoutes = [];
+	for (const route of resource.routes ?? []) customRoutes.push({
+		method: route.method,
+		path: `${resource.prefix}${route.path}`,
+		...route.operation ? { operation: route.operation } : {},
+		...route.summary ? { summary: route.summary } : {}
+	});
+	return {
+		name: resource.name,
+		displayName: resource.displayName,
+		prefix: resource.prefix,
+		idField: resource.idField ?? "_id",
+		updateMethod: resource.updateMethod ?? "PATCH",
+		crudOps,
+		actions,
+		aggregations,
+		customRoutes,
+		...resource.tenantField !== void 0 ? { tenantField: resource.tenantField } : {}
+	};
+}
+/**
+* Build a manifest from a `RegistryEntry` — use when the resource is
+* already registered (introspection endpoint, runtime audit script).
+*
+* Equivalent to {@link buildResourceManifest} but reads from the projected
+* registry shape, so a host that doesn't have the original `defineResource`
+* value in scope (e.g. an FE-gen sidecar that scrapes a running server's
+* `/_resources` endpoint) gets the same output without dragging the resource
+* module into the codegen path.
+*/
+function buildResourceManifestFromRegistry(entry) {
+	const disabled = new Set(entry.disabledRoutes ?? []);
+	const crudOps = entry.disableDefaultRoutes ? [] : CRUD_OPERATIONS.filter((op) => !disabled.has(op));
+	const actions = (entry.actions ?? []).map((a) => {
+		const requiresId = a.id !== false;
+		return {
+			name: a.name,
+			mount: requiresId ? "/:id/action" : "/action",
+			requiresId,
+			...a.description ? { description: a.description } : {}
+		};
+	});
+	const aggregations = (entry.aggregations ?? []).map((agg) => ({
+		name: agg.name,
+		path: `${entry.prefix}/aggregations/${agg.name}`,
+		...agg.summary ? { summary: agg.summary } : {},
+		...agg.description ? { description: agg.description } : {}
+	}));
+	const customRoutes = (entry.customRoutes ?? []).map((r) => ({
+		method: r.method,
+		path: `${entry.prefix}${r.path}`,
+		...r.operation ? { operation: r.operation } : {},
+		...r.summary ? { summary: r.summary } : {}
+	}));
+	const updateMethod = entry.updateMethod ?? "PATCH";
+	return {
+		name: entry.name,
+		displayName: entry.displayName ?? entry.name,
+		prefix: entry.prefix,
+		idField: "_id",
+		updateMethod,
+		crudOps,
+		actions,
+		aggregations,
+		customRoutes,
+		...entry.tenantField !== void 0 ? { tenantField: entry.tenantField } : {}
+	};
+}
+//#endregion
+export { cascadeDeleteForOrganization as a, assertNoTenantData as c, introspectionPlugin_default as i, buildResourceManifestFromRegistry as n, getCascadingResources as o, introspectionPlugin as r, getCascadingResourcesWithMetadata as s, buildResourceManifest as t };

package/dist/{routerShared-DrOa-26E.mjs → routerShared-ClV4cCaa.mjs}

@@ -1,9 +1,9 @@
 import { f as createError } from "./errors-j4aJm1Wg.mjs";
-import { b as isMember, c as getOrgId, h as getUserId, n as PUBLIC_SCOPE, y as isElevated } from "./types-C_s5moIu.mjs";
+import { b as isElevated, c as getOrgId, g as getUserId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
 import { t as requestContext } from "./requestContext-SSaaTgW8.mjs";
-import { I as evaluateAndApplyPermission, p as resolveEffectiveRoles, u as applyFieldReadPermissions } from "./permissions-ohQyv50e.mjs";
+import { I as evaluateAndApplyPermission, p as resolveEffectiveRoles, u as applyFieldReadPermissions } from "./permissions-CTxMrreC.mjs";
 import { t as getUserRoles } from "./types-D57iXYb8.mjs";
-import { t as executePipeline } from "./pipe-Zr0KXjQe.mjs";
+import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";
 import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
 //#region src/scope/projection.ts
 /**
@@ -55,9 +55,13 @@ function applyFieldMask(data, fieldMask) {
 	return data;
 }
 /**
-* Create IRequestContext from Fastify request
-*
-* Extracts framework-agnostic context from Fastify-specific request object
+* 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;
@@ -145,12 +149,33 @@ function computeFieldCapabilities(fieldPerms, effectiveRoles) {
 	return caps;
 }
 /**
-* Send IControllerResponse via Fastify reply
+* 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.
 *
-* Converts framework-agnostic response to Fastify response
-* Applies field masking if specified in request
+* **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;
@@ -207,18 +232,17 @@ function sendControllerResponse(reply, response, request) {
 	reply.code(status).send(filteredData);
 }
 /**
-* Create Fastify route handler from IController method
-*
-* Wraps framework-agnostic controller method in Fastify-specific handler
+* 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);
-*
-* // Create Fastify handler
 * const listHandler = createFastifyHandler(controller.list.bind(controller));
-*
-* // Register route
 * fastify.get('/products', listHandler);
 * ```
 */

package/dist/scope/index.d.mts

@@ -1,5 +1,5 @@
-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 { C as isMember, D as requireOrgId, E as requireClientId, O as requireTeamId, S as isElevated, T as isService, _ as getTenantFromRequest, a as getAncestorOrgIds, b as hasOrgAccess, c as getMandate, d as getOrgRoles, f as getRequestScope, g as getTeamId, h as getServiceScopes, i as RequestScope, k as requireUserId, 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 getUserId, w as isOrgInScope, x as isAuthenticated, y as getUserRoles } from "../types-CfapW2t8.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-DvwtjDwu.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, 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 };
+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, getTenantFromRequest, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };