@classytic/arc 2.11.4 → 2.14.0

package/dist/{resourceToTools-CxNmI6xF.mjs → resourceToTools-DLL32us3.mjs}

@@ -1,10 +1,13 @@
-import { t as BaseController } from "./BaseController-swXruJ2_.mjs";
-import { A as normalizePermissionResult } from "./permissions-gd_aUWrR.mjs";
-import { u as resolvePipelineSteps } from "./routerShared-BqLRb5l7.mjs";
-import { t as executePipeline } from "./pipe-DVoIheVC.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-sUUKDhtP.mjs";
-import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-Dy2p4MxS.mjs";
-import { t as pluralize } from "./pluralize-CWP6MB39.mjs";
+import { p as isArcError } from "./errors-j4aJm1Wg.mjs";
+import { t as BaseController } from "./BaseController-DX_T-bDB.mjs";
+import { L as normalizePermissionResult } from "./permissions-ohQyv50e.mjs";
+import { t as executePipeline } from "./pipe-Zr0KXjQe.mjs";
+import { u as resolvePipelineSteps } from "./routerShared-DrOa-26E.mjs";
+import { n as executeAggregation, r as validateAggregations } from "./buildHandler-olo-gt94.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CyUkQu6O.mjs";
+import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-lYhC2gE5.mjs";
+import { t as pluralize } from "./pluralize-DQgqgifU.mjs";
+import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
@@ -416,15 +419,11 @@ async function evaluatePermission(check, session, resource, action, input) {
 * Convert a controller response envelope into an MCP `CallToolResult`.
 * Carries `meta` into the serialized payload so consumers see pagination
 * totals, stripped-field arrays, etc.
+*
+* Errors are not represented here — controllers throw `ArcError` and the
+* MCP tool wrapper catches them via {@link toCallToolError}.
 */
 function toCallToolResult(result) {
-	if (!result.success) return {
-		content: [{
-			type: "text",
-			text: result.error ?? "Operation failed"
-		}],
-		isError: true
-	};
 	const output = result.meta ? {
 		data: result.data,
 		...result.meta
@@ -435,6 +434,70 @@ function toCallToolResult(result) {
 	}] };
 }
 /**
+* Wrap a raw success payload as an MCP `CallToolResult`. Use when the
+* tool produced a value directly (action handler return, aggregation
+* rows, etc.) instead of an `IControllerResponse` envelope.
+*
+* Emits the value as JSON with no envelope — same no-envelope contract
+* the HTTP wire follows. The `isError: true` flag on `CallToolResult`
+* is the success/error discriminant for MCP, mirroring HTTP status.
+*/
+function toCallToolSuccess(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value)
+	}] };
+}
+/**
+* Wrap an error as an MCP `CallToolResult` with the canonical
+* `ErrorContract` shape inside the text payload. Single source of truth
+* for MCP error serialization — every tool surface (CRUD, action, route,
+* aggregation) routes through here so the JSON shape an agent sees is
+* identical to what an HTTP client sees.
+*
+* Accepts:
+*  - An `ArcError` (or any `HttpError`-shaped throw) → routes through
+*    `toErrorContract()` for the canonical conversion.
+*  - A partial contract `{code, message, status, details?}` → used as-is.
+*  - Any other `Error` → falls back to `arc.internal_error` 500.
+*/
+function toCallToolError(input) {
+	let contract;
+	if (input instanceof Error) if (isArcError(input) || isHttpError(input)) contract = toErrorContract(input);
+	else contract = {
+		code: "arc.internal_error",
+		message: input.message || "Internal Server Error",
+		status: 500
+	};
+	else contract = {
+		code: input.code,
+		message: input.message,
+		...input.status !== void 0 ? { status: input.status } : {},
+		...input.details ? { details: input.details } : {}
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(contract)
+		}],
+		isError: true
+	};
+}
+/**
+* Build the canonical permission-denied `CallToolResult` for an MCP
+* tool. Discriminates 401 (no session — "Authentication required") from
+* 403 (session present, denied — "Permission denied"). Mirrors the
+* status split the HTTP `errorHandler` plugin uses.
+*/
+function permissionDeniedResult(args) {
+	const authenticated = args.session != null;
+	return toCallToolError({
+		code: authenticated ? "arc.forbidden" : "arc.unauthorized",
+		message: args.reason ?? (authenticated ? `Permission denied for '${args.operation}' on '${args.resource}'` : "Authentication required"),
+		status: authenticated ? 403 : 401
+	});
+}
+/**
 * Auto-create a BaseController from the resource's adapter for MCP use.
 * Called when the resource has an adapter but no controller
 * (e.g. `disableDefaultRoutes: true` skips controller creation in
@@ -482,32 +545,24 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 		const session = ctx.session;
 		if (allowedKeys) {
 			const extras = Object.keys(input).filter((k) => !allowedKeys.has(k));
-			if (extras.length > 0) return {
-				content: [{
-					type: "text",
-					text: JSON.stringify({
-						success: false,
-						error: `Unknown properties not allowed: ${extras.join(", ")}`,
-						details: {
-							action: actionName,
-							unexpected: extras
-						}
-					})
-				}],
-				isError: true
-			};
+			if (extras.length > 0) return toCallToolError({
+				code: "arc.bad_request",
+				message: `Unknown properties not allowed: ${extras.join(", ")}`,
+				status: 400,
+				details: [{
+					path: "input",
+					code: "unknown_properties",
+					message: `Unexpected fields: ${extras.join(", ")}`
+				}]
+			});
 		}
 		const permResult = await evaluatePermission(permissions, session, resourceName, actionName, input);
-		if (permResult && !permResult.granted) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					success: false,
-					error: permResult.reason ?? `Permission denied for action '${actionName}'`
-				})
-			}],
-			isError: true
-		};
+		if (permResult && !permResult.granted) return permissionDeniedResult({
+			resource: resourceName,
+			operation: `action.${actionName}`,
+			reason: permResult.reason,
+			session
+		});
 		const reqCtx = buildRequestContext({
 			...input,
 			action: actionName
@@ -515,26 +570,111 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 		const id = typeof input.id === "string" ? input.id : "";
 		const { id: _discardId, ...data } = input;
 		try {
-			const result = await handler(id, data, reqCtx);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					success: true,
-					data: result
-				})
-			}] };
+			return toCallToolSuccess(await handler(id, data, reqCtx));
 		} catch (err) {
-			return {
-				content: [{
-					type: "text",
-					text: `Error: ${err instanceof Error ? err.message : String(err)}`
-				}],
-				isError: true
-			};
+			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
 	};
 }
 //#endregion
+//#region src/integrations/mcp/aggregation-tools.ts
+/**
+* Build MCP tools for a resource's aggregations.
+*
+* Returns an empty array when the resource has no aggregations or
+* every aggregation opts out via `mcp: false`.
+*/
+function buildAggregationTools(args) {
+	const { resourceName, displayName, aggregations, schemaOptions, repo, buildOptionsFromSession, prefix } = args;
+	if (!aggregations || Object.keys(aggregations).length === 0) return [];
+	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
+	const tools = [];
+	for (const norm of normalized) {
+		const config = norm.base;
+		if (config.mcp === false) continue;
+		const mcpCfg = typeof config.mcp === "object" ? config.mcp : void 0;
+		const description = buildAggregationToolDescription(norm, mcpCfg?.description);
+		const annotations = mcpCfg?.annotations ? { ...mcpCfg.annotations } : {
+			readOnlyHint: true,
+			idempotentHint: true
+		};
+		const toolName = prefix ? `${prefix}_aggregation_${norm.name}_${resourceName}` : `aggregation_${norm.name}_${resourceName}`;
+		tools.push({
+			name: toolName,
+			description,
+			annotations,
+			inputSchema: buildAggregationInputSchema(norm),
+			handler: createAggregationToolHandler({
+				normalized: norm,
+				permissions: config.permissions,
+				resourceName,
+				repo,
+				buildOptionsFromSession
+			})
+		});
+	}
+	return tools;
+}
+function buildAggregationToolDescription(norm, override) {
+	if (override) return override;
+	const config = norm.base;
+	const parts = [];
+	if (config.summary) parts.push(config.summary);
+	if (config.description && config.description !== config.summary) parts.push(config.description);
+	const groupSummary = describeGroupBy(config.groupBy);
+	const measureSummary = Object.keys(norm.compiled.measures).join(", ");
+	if (groupSummary) parts.push(`Groups by ${groupSummary}; measures: ${measureSummary}.`);
+	else parts.push(`Scalar aggregate. Measures: ${measureSummary}.`);
+	if (config.requireDateRange) parts.push(`Requires a bounded date range on \`${config.requireDateRange.field}\`.` + (config.requireDateRange.maxRangeDays ? ` Max range: ${config.requireDateRange.maxRangeDays} days.` : ""));
+	if (config.requireFilters?.length) parts.push(`Requires filters on: ${config.requireFilters.join(", ")}.`);
+	return parts.join(" ");
+}
+function describeGroupBy(groupBy) {
+	if (!groupBy) return "";
+	if (typeof groupBy === "string") return `\`${groupBy}\``;
+	if (groupBy.length === 0) return "";
+	return groupBy.map((g) => `\`${g}\``).join(", ");
+}
+/**
+* Build the MCP tool input schema.
+*
+* Aggregation tools accept a single `filter` object mapping field
+* name → value or operator object. Open-shape so agents can pass any
+* caller-side narrows; safety guards inside `executeAggregation`
+* enforce required fields.
+*/
+function buildAggregationInputSchema(norm) {
+	const config = norm.base;
+	const shape = { filter: z.record(z.string(), z.unknown()).optional().describe("Caller-supplied filter narrowing. Keys are field names (or `'<alias>.<field>'` joined-alias paths when the aggregation declares lookups). Values are literals or operator objects (`{ gte, lte, in, ... }`).") };
+	if (config.requireFilters?.length) shape.requireFiltersHint = z.literal(config.requireFilters.join(", ")).optional().describe(`REQUIRED FILTERS — supply ${config.requireFilters.map((f) => `\`filter.${f}\``).join(" + ")} for this aggregation to run. Missing fields → 400.`);
+	if (config.requireDateRange) shape.requireDateRangeHint = z.literal(config.requireDateRange.field).optional().describe(`REQUIRED DATE RANGE — supply \`filter['${config.requireDateRange.field}'] = { gte: '<lower>', lte: '<upper>' }\`.` + (config.requireDateRange.maxRangeDays ? ` Range capped at ${config.requireDateRange.maxRangeDays} days.` : ""));
+	return shape;
+}
+function createAggregationToolHandler(args) {
+	const { normalized, permissions, resourceName, repo, buildOptionsFromSession } = args;
+	return async (input, ctx) => {
+		const permResult = await evaluatePermission(permissions, ctx.session, resourceName, `aggregation:${normalized.name}`, input);
+		if (permResult && !permResult.granted) return permissionDeniedResult({
+			resource: resourceName,
+			operation: `aggregation:${normalized.name}`,
+			reason: permResult.reason,
+			session: ctx.session
+		});
+		const filterInput = input.filter ?? {};
+		const tenantOptions = buildOptionsFromSession(ctx.session);
+		if (permResult?.filters) Object.assign(tenantOptions, { _policyFilters: permResult.filters });
+		const result = await executeAggregation(normalized, {
+			repo,
+			buildOptions: () => tenantOptions
+		}, {
+			query: filterInput,
+			tenantOptions
+		});
+		if (result.status === 200) return toCallToolSuccess(result.body);
+		return toCallToolError(result.body);
+	};
+}
+//#endregion
 //#region src/integrations/mcp/crud-tools.ts
 const ALL_CRUD_OPS = [
 	"list",
@@ -928,16 +1068,12 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 	return async (input, _ctx) => {
 		const session = _ctx.session;
 		const permResult = await evaluatePermission(permissions, session, resourceName, operationName, input);
-		if (permResult && !permResult.granted) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					success: false,
-					error: permResult.reason ?? (session ? `Permission denied for '${operationName}'` : "Authentication required")
-				})
-			}],
-			isError: true
-		};
+		if (permResult && !permResult.granted) return permissionDeniedResult({
+			resource: resourceName,
+			operation: operationName,
+			reason: permResult.reason,
+			session
+		});
 		try {
 			const reqCtx = buildRequestContext(input, session, hasId ? "update" : "create", permResult?.filters, permResult?.scope);
 			if (typeof route.handler === "function") {
@@ -948,16 +1084,10 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 					operation: operationName
 				}, async (ctx) => {
 					const raw = await fn(ctx);
-					return raw !== null && typeof raw === "object" && "success" in raw ? raw : {
-						success: true,
-						data: raw
-					};
+					return raw !== null && typeof raw === "object" && "data" in raw ? raw : { data: raw };
 				}, operationName));
 				const out = await fn(reqCtx);
-				return toCallToolResult(out !== null && typeof out === "object" && "success" in out ? out : {
-					success: true,
-					data: out
-				});
+				return toCallToolResult(out !== null && typeof out === "object" && "data" in out ? out : { data: out });
 			}
 			if (!ctrl) return {
 				content: [{
@@ -1154,6 +1284,29 @@ function resourceToTools(resource, config = {}) {
 			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema)
 		});
 	}
+	if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
+		const repoForAgg = resource.controller?.repository;
+		const buildOptionsFromSession = (session) => {
+			const s = session;
+			const out = {};
+			const orgId = s?.scope?.organizationId;
+			if (orgId) out.organizationId = orgId;
+			const userId = s?.scope?.userId ?? s?.user?.id;
+			if (userId) out.userId = userId;
+			if (s?.user) out.user = s.user;
+			if (s?.requestId) out.requestId = s.requestId;
+			return out;
+		};
+		tools.push(...buildAggregationTools({
+			resourceName: resource.name,
+			displayName: resource.displayName ?? resource.name,
+			aggregations: resource.aggregations,
+			schemaOptions: resource.schemaOptions,
+			repo: repoForAgg,
+			buildOptionsFromSession,
+			prefix
+		}));
+	}
 	return tools;
 }
 //#endregion

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

@@ -1,8 +1,10 @@
-import { _ as isElevated, n as PUBLIC_SCOPE, o as getOrgId, p as getUserId, v as isMember } from "./types-AOD8fxIw.mjs";
-import { P as resolveEffectiveRoles, j as applyFieldReadPermissions, k as evaluateAndApplyPermission } from "./permissions-gd_aUWrR.mjs";
-import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { t as requestContext } from "./requestContext-C5XeK3VA.mjs";
-import { t as executePipeline } from "./pipe-DVoIheVC.mjs";
+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 { t as requestContext } from "./requestContext-SSaaTgW8.mjs";
+import { I as evaluateAndApplyPermission, p as resolveEffectiveRoles, u as applyFieldReadPermissions } from "./permissions-ohQyv50e.mjs";
+import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { t as executePipeline } from "./pipe-Zr0KXjQe.mjs";
+import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
 //#region src/scope/projection.ts
 /**
 * Compute the request-scope projection. Returns `undefined` when no
@@ -165,32 +167,44 @@ function sendControllerResponse(reply, response, request) {
 		return result;
 	};
 	if (response.headers) for (const [key, value] of Object.entries(response.headers)) reply.header(key, value);
-	if (response.success && response.data && typeof response.data === "object" && "docs" in response.data) {
-		const paginatedData = response.data;
-		const filteredDocs = hasFieldRestrictions ? applyPermissions(paginatedData.docs) : paginatedData.docs;
+	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({
-			success: true,
-			docs: filteredDocs,
-			page: paginatedData.page,
-			limit: paginatedData.limit,
-			total: paginatedData.total,
-			pages: paginatedData.pages,
-			hasNext: paginatedData.hasNext,
-			hasPrev: paginatedData.hasPrev,
+			...canonical,
 			...response.meta ?? {},
 			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
 		});
 		return;
 	}
-	const filteredData = hasFieldRestrictions ? applyPermissions(response.data) : response.data;
-	reply.code(response.status ?? (response.success ? 200 : 400)).send({
-		success: response.success,
-		data: filteredData,
-		error: response.error,
-		details: response.details,
-		...response.meta ?? {},
-		...fieldCaps ? { fieldPermissions: fieldCaps } : {}
-	});
+	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);
 }
 /**
 * Create Fastify route handler from IController method
@@ -370,15 +384,7 @@ function buildActionPermissionMw(actionEnum, actionPermissions, globalAuth, reso
 	return async (req, reply) => {
 		const body = req.body ?? {};
 		const action = body.action;
-		if (!action || !enumSet.has(action)) {
-			sendControllerResponse(reply, {
-				success: false,
-				status: 400,
-				error: `Invalid action '${action ?? ""}'. Valid actions: ${validActions.join(", ")}`,
-				meta: { validActions }
-			}, req);
-			return;
-		}
+		if (!action || !enumSet.has(action)) throw createError(400, `Invalid action '${action ?? ""}'. Valid actions: ${validActions.join(", ")}`, { validActions });
 		const permissionCheck = actionPermissions[action] ?? globalAuth;
 		if (!permissionCheck) return;
 		const { action: _discard, ...data } = body;
@@ -432,7 +438,6 @@ function buildPipelineHandler(controllerMethod, steps, operation, resourceName)
 */
 function buildActionPipelineHandler(handler, steps, operation, resourceName) {
 	if (steps.length === 0) return async (id, data, req) => ({
-		success: true,
 		status: 200,
 		data: await handler(id, data, req)
 	});
@@ -442,7 +447,6 @@ function buildActionPipelineHandler(handler, steps, operation, resourceName) {
 			resource: resourceName,
 			operation
 		}, async (_ctx) => ({
-			success: true,
 			status: 200,
 			data: await handler(id, data, req)
 		}), operation);
@@ -556,6 +560,7 @@ function resolveRoutePreHandlers(preHandler, fastify, routeId) {
 			const msg = err instanceof Error ? err.message : String(err);
 			throw new TypeError(`Route ${routeId}: preHandler factory threw during route registration: ${msg}.\nIf you intended to pass a single handler (e.g. \`multipartBody({...})\`), wrap it in an array: \`preHandler: [yourHandler]\`. The factory form is \`(fastify) => RouteHandlerMethod[]\` — it must return an array.`, { cause: err instanceof Error ? err : void 0 });
 		}
+		if (result && typeof result.then === "function") result.catch(() => void 0);
 		if (!Array.isArray(result)) throw new TypeError(`Route ${routeId}: preHandler factory must return an array of handlers, got ${describeValue(result)}.\nCommon cause: passing a single \`RouteHandlerMethod\` (e.g. \`multipartBody({...})\`) where an array was expected. Wrap it: \`preHandler: [yourHandler]\`. The factory form \`(fastify) => RouteHandlerMethod[]\` is for cases that need the Fastify instance — e.g. \`(fastify) => [fastify.authenticate, myHandler]\`.`);
 		return result.filter((h) => typeof h === "function");
 	}

package/dist/{schemaIR-Dy2p4MxS.mjs → schemaIR-lYhC2gE5.mjs}

@@ -1,4 +1,4 @@
-import { a as toJsonSchema } from "./schemaConverter-B0oKLuqI.mjs";
+import { a as toJsonSchema } from "./schemaConverter-De34B1ZG.mjs";
 import { z } from "zod";
 //#region src/core/schemaIR.ts
 /**

package/dist/schemas/index.d.mts

@@ -1,15 +1,54 @@
+import { ErrorContract, ErrorDetail } from "@classytic/repo-core/errors";
 import { FastifyPluginAsyncTypebox, FastifyPluginCallbackTypebox, TypeBoxTypeProvider, TypeBoxValidatorCompiler } from "@fastify/type-provider-typebox";
 import * as _$_sinclair_typebox0 from "@sinclair/typebox";
 import { Static, TObject, TSchema, TSchema as TSchema$1, Type } from "@sinclair/typebox";
 
 //#region src/schemas/index.d.ts
 /**
- * Paginated list response — matches Arc's runtime format:
- * `{ success, docs: [...], page, limit, total, pages, hasNext, hasPrev }`
+ * Paginated list response — full union of every wire shape `toCanonicalList`
+ * emits. Mirrors `PaginatedResult<T>` from `@classytic/repo-core/pagination`:
+ *
+ *   - `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
+ *   - `{ method: 'keyset', data, limit, hasMore, next: string | null }`
+ *   - `{ method: 'aggregate', ...same as offset }`
+ *   - `{ data }` (bare list, no `method`)
+ *
+ * Use `ArcOffsetListResponse` / `ArcKeysetListResponse` /
+ * `ArcAggregateListResponse` / `ArcBareListResponse` to pin a single
+ * variant when your endpoint never emits the others. HTTP status
+ * discriminates success vs error — no `success` field.
  */
-declare function ArcListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
-  success: _$_sinclair_typebox0.TBoolean;
-  docs: _$_sinclair_typebox0.TArray<T>;
+declare function ArcListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TUnion<[_$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"offset">;
+  data: _$_sinclair_typebox0.TArray<T>;
+  page: _$_sinclair_typebox0.TInteger;
+  limit: _$_sinclair_typebox0.TInteger;
+  total: _$_sinclair_typebox0.TInteger;
+  pages: _$_sinclair_typebox0.TInteger;
+  hasNext: _$_sinclair_typebox0.TBoolean;
+  hasPrev: _$_sinclair_typebox0.TBoolean;
+}>, _$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"keyset">;
+  data: _$_sinclair_typebox0.TArray<T>;
+  limit: _$_sinclair_typebox0.TInteger;
+  hasMore: _$_sinclair_typebox0.TBoolean;
+  next: _$_sinclair_typebox0.TUnion<[_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TNull]>;
+}>, _$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"aggregate">;
+  data: _$_sinclair_typebox0.TArray<T>;
+  page: _$_sinclair_typebox0.TInteger;
+  limit: _$_sinclair_typebox0.TInteger;
+  total: _$_sinclair_typebox0.TInteger;
+  pages: _$_sinclair_typebox0.TInteger;
+  hasNext: _$_sinclair_typebox0.TBoolean;
+  hasPrev: _$_sinclair_typebox0.TBoolean;
+}>, _$_sinclair_typebox0.TObject<{
+  data: _$_sinclair_typebox0.TArray<T>;
+}>]>;
+/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
+declare function ArcOffsetListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"offset">;
+  data: _$_sinclair_typebox0.TArray<T>;
   page: _$_sinclair_typebox0.TInteger;
   limit: _$_sinclair_typebox0.TInteger;
   total: _$_sinclair_typebox0.TInteger;
@@ -17,47 +56,78 @@ declare function ArcListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclai
   hasNext: _$_sinclair_typebox0.TBoolean;
   hasPrev: _$_sinclair_typebox0.TBoolean;
 }>;
-/**
- * Single item response — `{ success, data: {...} }`
- */
-declare function ArcItemResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
-  success: _$_sinclair_typebox0.TBoolean;
-  data: T;
+/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
+declare function ArcKeysetListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"keyset">;
+  data: _$_sinclair_typebox0.TArray<T>;
+  limit: _$_sinclair_typebox0.TInteger;
+  hasMore: _$_sinclair_typebox0.TBoolean;
+  next: _$_sinclair_typebox0.TUnion<[_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TNull]>;
 }>;
-/**
- * Mutation (create/update) response — `{ success, data: {...}, message? }`
- */
-declare function ArcMutationResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
-  success: _$_sinclair_typebox0.TBoolean;
-  data: T;
-  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+/** Aggregate variant — `{ method: 'aggregate', ...same as offset }`. */
+declare function ArcAggregateListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  method: _$_sinclair_typebox0.TLiteral<"aggregate">;
+  data: _$_sinclair_typebox0.TArray<T>;
+  page: _$_sinclair_typebox0.TInteger;
+  limit: _$_sinclair_typebox0.TInteger;
+  total: _$_sinclair_typebox0.TInteger;
+  pages: _$_sinclair_typebox0.TInteger;
+  hasNext: _$_sinclair_typebox0.TBoolean;
+  hasPrev: _$_sinclair_typebox0.TBoolean;
+}>;
+/** Bare variant — `{ data }`, no `method` discriminant. */
+declare function ArcBareListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  data: _$_sinclair_typebox0.TArray<T>;
 }>;
 /**
- * Delete response — `{ success, message }`
+ * Delete response — `{ message, id?, soft? }` raw at the top level.
  */
 declare function ArcDeleteResponse(): _$_sinclair_typebox0.TObject<{
-  success: _$_sinclair_typebox0.TBoolean;
-  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  message: _$_sinclair_typebox0.TString;
+  id: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  soft: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TBoolean>;
 }>;
 /**
- * Error response schema
+ * Single field-scoped error detail — `Type.Unsafe<ErrorDetail>` over the
+ * canonical JSON Schema `errorDetailSchema` from
+ * `@classytic/repo-core/errors`. One schema constant, two adapters
+ * (JSON-Schema + TypeBox), zero drift surface — the schema and the TS
+ * type both come from repo-core.
+ *
+ * Exported standalone so hosts can embed it in custom 422 / 409 response
+ * schemas.
  */
-declare function ArcErrorResponse(): _$_sinclair_typebox0.TObject<{
-  success: _$_sinclair_typebox0.TLiteral<false>;
-  error: _$_sinclair_typebox0.TString;
-  code: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
-  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
-}>;
+declare function ArcErrorDetail(): _$_sinclair_typebox0.TUnsafe<ErrorDetail>;
+/**
+ * Error response schema — `Type.Unsafe<ErrorContract>` over the canonical
+ * JSON Schema `errorContractSchema` from `@classytic/repo-core/errors`.
+ * Same trick as `ArcErrorDetail`: the schema bytes and the TS type both
+ * come from repo-core, so the JSON-Schema sibling
+ * (`errorContractSchema`) and this TypeBox helper cannot drift —
+ * literally one source.
+ */
+declare function ArcErrorResponse(): _$_sinclair_typebox0.TUnsafe<ErrorContract>;
 /**
  * Standard pagination + sorting + filtering query parameters.
  * Matches Arc's list endpoint conventions.
+ *
+ * `select` accepts every shape `QueryResolver` preserves DB-agnostically
+ * (gotcha #5):
+ *
+ *   - `string`  — `"name email -password"` (Mongoose space-separated)
+ *   - `string[]` — `["name", "email", "-password"]` (Arc parser)
+ *   - `Record<string, 0 | 1>` — `{ name: 1, email: 1, password: 0 }` (Mongo projection)
+ *
+ * Narrowing `select` to `string` would have rejected the array and
+ * projection forms at the request-validation gate even though arc passes
+ * them through unchanged.
  */
 declare function ArcPaginationQuery(): _$_sinclair_typebox0.TObject<{
   page: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TInteger>;
   limit: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TInteger>;
   sort: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
-  select: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  select: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TUnion<[_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TArray<_$_sinclair_typebox0.TString>, _$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TUnion<[_$_sinclair_typebox0.TLiteral<0>, _$_sinclair_typebox0.TLiteral<1>]>>]>>;
   populate: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TAny>;
 }>;
 //#endregion
-export { ArcDeleteResponse, ArcErrorResponse, ArcItemResponse, ArcListResponse, ArcMutationResponse, ArcPaginationQuery, type FastifyPluginAsyncTypebox, type FastifyPluginCallbackTypebox, type Static, type TObject, type TSchema, Type, type TypeBoxTypeProvider, TypeBoxValidatorCompiler };
+export { ArcAggregateListResponse, ArcBareListResponse, ArcDeleteResponse, ArcErrorDetail, ArcErrorResponse, ArcKeysetListResponse, ArcListResponse, ArcOffsetListResponse, ArcPaginationQuery, type FastifyPluginAsyncTypebox, type FastifyPluginCallbackTypebox, type Static, type TObject, type TSchema, Type, type TypeBoxTypeProvider, TypeBoxValidatorCompiler };