@classytic/arc 2.15.0 → 2.15.4

package/README.md

@@ -155,6 +155,50 @@ Custom checks return `{ granted, reason?, filters?, scope? }` — `filters` prop
 
 ---
 
+## Aggregations
+
+Add `aggregations: { … }` to a resource and arc registers `GET /:prefix/aggregations/:name` per entry. Each runs a portable `$match → $group → $project → $sort → $limit` pipeline against the kit's `repo.aggregate(req, options)` — same shape across mongokit / sqlitekit / prismakit, so dashboards work unchanged across backends.
+
+```typescript
+import { defineResource, defineAggregation } from '@classytic/arc';
+
+defineResource({
+  name: 'transaction',
+  adapter,
+  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
+  permissions: { list: canViewRevenue() },
+
+  aggregations: {
+    byPaymentMethod: defineAggregation({
+      groupBy: 'method',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { total: -1 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byDay: defineAggregation({
+      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+  },
+});
+```
+
+Caller filters via query string compose with the declaration:
+
+```
+GET /api/transactions/aggregations/byPaymentMethod?status=verified
+GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
+```
+
+Tenant scope flows through `repo.aggregate(req, options)` — the kit's multi-tenant plugin handles type-coercion (string → ObjectId for mongokit `fieldType: 'objectId'`, UUID/text for sqlitekit, etc.). Arc itself stays out of the filter slot because it's DB-agnostic. Safety guards on the declaration: `requireFilters`, `requireDateRange { maxRangeDays }`, `maxGroups`. SWR cache + tag invalidation tie aggregations to CRUD writes. Every aggregation auto-exports as an MCP tool with the same permissions and filter validation.
+
+---
+
 ## Authentication
 
 Discriminated union on `type`:

package/dist/{BaseController-Cn8KykUn.mjs → BaseController-dx3m2J8V.mjs}

@@ -701,6 +701,7 @@ var BaseCrudController = class {
 		if (presetFields && typeof presetFields === "object") {
 			for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
 		}
+		if (this.tenantField && out[this.tenantField] == null && scope && isElevated(scope)) out.bypassTenant = true;
 		const userId = getUserId(req.user);
 		if (userId) out.userId = userId;
 		if (req.user) out.user = req.user;

package/dist/{buildHandler-jSZ6Fdvi.mjs → buildHandler-CcFOpJLh.mjs}

@@ -78,10 +78,8 @@ function adapterSupportsAggregate(repo) {
 }
 /** Compile to canonical `AggRequest` for `repo.aggregate()` at request time. */
 function compileAggRequest(normalized, callerFilter, tenantOptions) {
-	const baseFilter = normalized.compiled.filter ?? {};
 	const filter = {
-		...extractTenantFilter(tenantOptions),
-		...baseFilter,
+		...normalized.compiled.filter ?? {},
 		...callerFilter
 	};
 	const executionHints = buildExecutionHints(normalized.base);
@@ -374,21 +372,6 @@ function assertFieldAllowed(context, ref, input) {
 	}
 	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
 }
-function extractTenantFilter(tenantOptions) {
-	const out = {};
-	const optionOnlyKeys = new Set([
-		"userId",
-		"user",
-		"session",
-		"requestId"
-	]);
-	for (const [key, value] of Object.entries(tenantOptions)) {
-		if (optionOnlyKeys.has(key)) continue;
-		if (value === void 0 || value === null) continue;
-		out[key] = value;
-	}
-	return out;
-}
 //#endregion
 //#region src/core/aggregation/buildHandler.ts
 /**
@@ -444,7 +427,7 @@ async function executeAggregation(normalized, deps, ctx) {
 	};
 	let result;
 	try {
-		result = await repo.aggregate(aggReq);
+		result = await repo.aggregate(aggReq, tenantOptions);
 	} catch (err) {
 		return mapAggregateError(err, aggregationName);
 	}

package/dist/cli/commands/init.mjs

@@ -376,20 +376,29 @@ function packageJsonTemplate(config) {
 		test: "vitest run",
 		"test:watch": "vitest"
 	};
+	const imports = config.typescript ? {
+		"#config/*": "./dist/config/*",
+		"#shared/*": "./dist/shared/*",
+		"#resources/*": "./dist/resources/*",
+		"#plugins/*": "./dist/plugins/*",
+		"#services/*": "./dist/services/*",
+		"#lib/*": "./dist/lib/*",
+		"#utils/*": "./dist/utils/*"
+	} : {
+		"#config/*": "./src/config/*",
+		"#shared/*": "./src/shared/*",
+		"#resources/*": "./src/resources/*",
+		"#plugins/*": "./src/plugins/*",
+		"#services/*": "./src/services/*",
+		"#lib/*": "./src/lib/*",
+		"#utils/*": "./src/utils/*"
+	};
 	return JSON.stringify({
 		name: config.name,
 		version: "1.0.0",
 		type: "module",
 		main: config.typescript ? "dist/index.js" : "src/index.js",
-		imports: {
-			"#config/*": "./src/config/*",
-			"#shared/*": "./src/shared/*",
-			"#resources/*": "./src/resources/*",
-			"#plugins/*": "./src/plugins/*",
-			"#services/*": "./src/services/*",
-			"#lib/*": "./src/lib/*",
-			"#utils/*": "./src/utils/*"
-		},
+		imports,
 		scripts,
 		dependencies,
 		devDependencies,

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-Cxde4rpC.mjs";
-import { a as BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-Cn8KykUn.mjs";
+import { a as BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-dx3m2J8V.mjs";
 import { _ as getControllerContext, g as createRequestContext, h as createFastifyHandler, m as createCrudHandlers, v as getControllerScope, y as sendControllerResponse } from "../routerShared-DrOa-26E.mjs";
-import { a as defineResource, c as createPermissionMiddleware, i as defineResourceVariants, l as defineAggregation, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as createCrudRouter, t as getEntityId } from "../core--_Dnl7n-.mjs";
+import { a as defineResource, c as createPermissionMiddleware, i as defineResourceVariants, l as defineAggregation, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as createCrudRouter, t as getEntityId } from "../core-CvmOqEms.mjs";
 export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/{core--_Dnl7n-.mjs → core-CvmOqEms.mjs}

@@ -1,7 +1,7 @@
 import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-_h9B3c57.mjs";
-import { t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { t as BaseController } from "./BaseController-dx3m2J8V.mjs";
 import { t as applyPresets } from "./presets-BbkjdPeH.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "./typeGuards-BzkXkvVv.mjs";
@@ -840,6 +840,7 @@ function normalizeListQuerySchema(listQuerySchema) {
 		for (const key of Object.keys(normalizedProps)) normalizedProps[key] = NORMALIZED_PROPS[key] ?? {};
 	}
 	return {
+		type: "object",
 		...listQuerySchema,
 		...normalizedProps ? { properties: normalizedProps } : {},
 		additionalProperties: listQuerySchema.additionalProperties ?? true
@@ -997,7 +998,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const { createAggregationRouter } = await import("./createAggregationRouter-DhR-Ofiz.mjs");
+				const { createAggregationRouter } = await import("./createAggregationRouter-B0bPDf5b.mjs");
 				const repoForAgg = resource.controller?.repository;
 				const buildOptions = (req) => {
 					const ctrl = resource.controller;
@@ -1014,7 +1015,8 @@ function buildResourcePlugin(resource) {
 					permissions: resource.permissions,
 					routeGuards: resource.routeGuards,
 					repository: repoForAgg,
-					buildOptions
+					buildOptions,
+					middlewares: resource.middlewares?.aggregations
 				});
 			}
 			if (resource.events && Object.keys(resource.events).length > 0) typedInstance.log?.debug?.(`Resource '${resource.name}' defined ${Object.keys(resource.events).length} events`);

package/dist/{createAggregationRouter-DhR-Ofiz.mjs → createAggregationRouter-B0bPDf5b.mjs}

@@ -1,13 +1,13 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
 import { c as buildPreHandlerChain, f as resolveRouterPluginMw, i as buildAuthMiddleware, l as buildRateLimitConfig, p as selectPluginMw, r as buildArcDecorator } from "./routerShared-DrOa-26E.mjs";
-import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-jSZ6Fdvi.mjs";
+import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-CcFOpJLh.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is
 * empty — same convention `createActionRouter` follows.
 */
 function createAggregationRouter(fastify, config) {
-	const { tag, resourceName, aggregations, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], repository, buildOptions } = config;
+	const { tag, resourceName, aggregations, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], repository, buildOptions, middlewares = [] } = config;
 	if (!aggregations || Object.keys(aggregations).length === 0) return;
 	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
 	const arcDecorator = buildArcDecorator({
@@ -23,7 +23,8 @@ function createAggregationRouter(fastify, config) {
 		arcDecorator,
 		routeGuards,
 		repository,
-		buildOptions
+		buildOptions,
+		middlewares
 	});
 	fastify.log?.debug?.({
 		aggregations: normalized.map((a) => a.name),
@@ -31,7 +32,7 @@ function createAggregationRouter(fastify, config) {
 	}, `[createAggregationRouter] registered ${normalized.length} aggregation route(s)`);
 }
 function registerOne(fastify, normalized, ctx) {
-	const { tag, arcDecorator, routeGuards, repository, buildOptions } = ctx;
+	const { tag, arcDecorator, routeGuards, repository, buildOptions, middlewares } = ctx;
 	const { name } = normalized;
 	const config = normalized.base;
 	const authMw = buildAuthMiddleware(fastify, config.permissions);
@@ -50,7 +51,8 @@ function registerOne(fastify, normalized, ctx) {
 		authMw,
 		permissionMw,
 		pluginMw: selectPluginMw("GET", resolveRouterPluginMw(fastify, false)),
-		routeGuards
+		routeGuards,
+		customMws: middlewares
 	});
 	const rateLimitConfig = buildRateLimitConfig(config.rateLimit ? {
 		max: config.rateLimit.max,

package/dist/{createApp-BarYhXCZ.mjs → createApp-PFegs47-.mjs}

@@ -230,8 +230,9 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-request-id");
 	}
 	if (config.arcPlugins?.health !== false) {
-		await fastify.register(healthPlugin);
-		trackPlugin("arc-health");
+		const healthOpts = typeof config.arcPlugins?.health === "object" && config.arcPlugins.health !== null ? config.arcPlugins.health : {};
+		await fastify.register(healthPlugin, healthOpts);
+		trackPlugin("arc-health", healthOpts);
 	}
 	if (config.arcPlugins?.gracefulShutdown !== false) {
 		await fastify.register(gracefulShutdownPlugin);
@@ -707,9 +708,65 @@ async function registerUtilityPlugins(fastify, config) {
 */
 var createApp_exports = /* @__PURE__ */ __exportAll({
 	ArcFactory: () => ArcFactory,
-	createApp: () => createApp
+	DEFAULT_LOGGER_REDACT_PATHS: () => DEFAULT_LOGGER_REDACT_PATHS,
+	createApp: () => createApp,
+	resolveLoggerConfig: () => resolveLoggerConfig
 });
 const MEMORY_STORE_NAMES = new Set(["memory", "memory-cache"]);
+/**
+* Default redact paths layered into Fastify's pino logger when the host
+* doesn't supply a `logger.redact` of their own. Covers the common token /
+* cookie / password leak surfaces — `Authorization` and `Cookie` headers
+* (and their case-variants because Node lower-cases incoming headers but
+* outgoing logs may carry either), API-key headers, and any nested
+* `password` / `token` / `secret` / `apiKey` fields anywhere in the log
+* tree.
+*
+* Hosts that need NO redaction (test fixtures, security audits) opt out
+* with `logger: { redact: [] }`. Hosts that need MORE redaction supply
+* their own `redact` and arc steps aside — this default never overrides
+* an explicit setting. (2.15.1)
+*/
+const DEFAULT_LOGGER_REDACT_PATHS = [
+	"req.headers.authorization",
+	"req.headers[\"x-api-key\"]",
+	"req.headers[\"x-internal-api-key\"]",
+	"req.headers.cookie",
+	"req.headers[\"set-cookie\"]",
+	"res.headers[\"set-cookie\"]",
+	"*.password",
+	"*.passwordHash",
+	"*.token",
+	"*.accessToken",
+	"*.refreshToken",
+	"*.secret",
+	"*.apiKey"
+];
+/**
+* Resolve the host's `logger` option, layering safe redact defaults
+* when the host hasn't supplied any. Returns the value Fastify expects
+* for its `logger` server option.
+*
+* Three branches:
+*   - `logger === false` → pass through (no logger).
+*   - `logger === undefined` → enable with default redact paths.
+*   - `logger === true` → enable with default redact paths.
+*   - `logger` is an object → respect explicit `redact` (host wins);
+*     otherwise inject defaults.
+*/
+function resolveLoggerConfig(logger) {
+	if (logger === false) return false;
+	if (logger === true || logger === void 0) return { redact: [...DEFAULT_LOGGER_REDACT_PATHS] };
+	if (typeof logger === "object" && logger !== null) {
+		const objLogger = logger;
+		if (objLogger.redact !== void 0) return logger;
+		return {
+			...objLogger,
+			redact: [...DEFAULT_LOGGER_REDACT_PATHS]
+		};
+	}
+	return logger;
+}
 function validateAuthOptions(options) {
 	const authConfig = options.auth;
 	if (authConfig === false || !authConfig) return;
@@ -766,14 +823,17 @@ async function createApp(options) {
 		...options
 	};
 	const fastify = Fastify({
-		logger: config.logger ?? true,
+		logger: resolveLoggerConfig(config.logger),
 		trustProxy: config.trustProxy ?? false,
 		pluginTimeout: config.pluginTimeout ?? 1e4,
+		...config.bodyLimit !== void 0 ? { bodyLimit: config.bodyLimit } : {},
+		allowErrorHandlerOverride: true,
 		routerOptions: { querystringParser: (str) => qs.parse(str) },
 		ajv: { customOptions: {
 			coerceTypes: true,
 			useDefaults: true,
 			removeAdditional: false,
+			strictTypes: false,
 			keywords: ["example", ...config.ajv?.keywords ?? []]
 		} }
 	});

package/dist/factory/index.d.mts

@@ -1,5 +1,5 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-3YTpuLZ1.mjs";
-import { FastifyInstance } from "fastify";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-DrBaUwyV.mjs";
+import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts
 /**

package/dist/factory/index.mjs

@@ -1,4 +1,4 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-BarYhXCZ.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-PFegs47-.mjs";
 import { t as loadResources } from "../loadResources-DBMQg_Aj.mjs";
 //#region src/factory/edge.ts
 /**

package/dist/index.mjs

@@ -1,11 +1,11 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-Cxde4rpC.mjs";
 import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-j4aJm1Wg.mjs";
 import { t as getUserId } from "./utils-_h9B3c57.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-dx3m2J8V.mjs";
 import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf, T as denyAll, _ as requireOrgMembership, a as presets_exports, b as requireServiceScope, c as readOnly, d as applyFieldWritePermissions, f as fields, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, m as createDynamicPermissionMatrix, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as applyFieldReadPermissions, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "./permissions-ohQyv50e.mjs";
 import { v as getControllerScope } from "./routerShared-DrOa-26E.mjs";
-import { a as defineResource, i as defineResourceVariants, l as defineAggregation, o as ResourceDefinition } from "./core--_Dnl7n-.mjs";
+import { a as defineResource, i as defineResourceVariants, l as defineAggregation, o as ResourceDefinition } from "./core-CvmOqEms.mjs";
 //#region src/index.ts
-const version = "2.15.0";
+const version = "2.15.4";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, getUserId, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-D4pWzVGA.mjs";
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-tFYUNmM0.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/integrations/mcp/defineTool.ts

package/dist/integrations/mcp/testing.mjs

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

package/dist/integrations/streamline.d.mts

@@ -50,7 +50,40 @@ interface WorkflowLike {
     }; /** Repository — used by the list-runs endpoint to query workflow_runs. */
     repository?: {
       getAll(params: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+      /**
+       * Tenant-scoped lookup by id. Used by the DELETE handler for a
+       * defense-in-depth pre-flight: streamline 2.3.3's `wf.get(runId)` /
+       * `engine.get` does NOT accept tenant options, so a cross-tenant
+       * runId can leak data through the engine path. Going through the
+       * repository here means mongokit's tenant-filter plugin scopes the
+       * read — cross-tenant requests get a clean 404 and DELETEs only
+       * touch rows the caller actually owns.
+       */
+      getById?(id: string, options?: Record<string, unknown>): Promise<WorkflowRunLike | null>;
+      /**
+       * Hard-delete a run by id. Routed through mongokit's inherited
+       * `Repository.delete()` so multi-tenant scope + audit/cache plugins
+       * fire. Wired into `DELETE /:workflowId/runs/:runId` — operator
+       * escape hatch for dead-lettered or stuck rows.
+       */
+      delete?(id: string, options?: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * Streamline >= 2.3.2 — explicit deploy-time index sync (TTL on
+     * terminal runs + tenant compounds). When the host configured
+     * `createContainer({ retention })`, arc's app-level deploy hook
+     * should call `await container.syncRetentionIndexes()` after
+     * `mongoose.connect`. Optional so older streamline versions
+     * (and partial mocks) still satisfy the structural shape.
+     */
+    syncRetentionIndexes?: () => Promise<void>;
+    /**
+     * Streamline >= 2.3.2 — stop background sweepers and release timers.
+     * Arc's `onClose` hook below calls this on every workflow's container
+     * during graceful shutdown so SIGTERM doesn't leave the stale-run
+     * sweeper running. Optional + idempotent.
+     */
+    dispose?: () => void;
   };
 }
 interface WorkflowRunLike {
@@ -67,7 +100,36 @@ interface WorkflowRunLike {
   stepLogs?: unknown[];
   createdAt?: Date;
   updatedAt?: Date;
+  /**
+   * Streamline >= 2.3.3 — pinned definition version (semver) the run
+   * started under. Hosts surfacing a "stuck on old version" UI read this
+   * to decide whether to nudge a migration. Optional for back-compat
+   * with runs created before 2.3.3.
+   */
+  definitionVersion?: string;
+  /**
+   * Streamline >= 2.3.3 — count of stale-recovery / sweeper transitions
+   * applied to this run. Sweeper dead-letters once this hits
+   * `RetentionOptions.maxStaleRecoveries`; UIs can highlight runs trending
+   * toward dead-letter.
+   */
+  recoveryAttempts?: number;
 }
+/**
+ * Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
+ * `'failed'`; the discrimination is `error.code`:
+ *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
+ *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
+ *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
+ *     resume against; admin must rewind / migrate / cancel.
+ *
+ * Hosts switch on `error.code` for dashboards / alerting.
+ */
+declare const STREAMLINE_FAILURE_CODES: {
+  readonly STALE_HEARTBEAT: "stale_heartbeat";
+  readonly DEAD_LETTERED: "dead_lettered";
+  readonly VERSION_MISMATCH: "VERSION_MISMATCH";
+};
 interface StreamlinePluginOptions {
   /** Array of workflows created with createWorkflow() */
   workflows: WorkflowLike[];
@@ -176,7 +238,14 @@ declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed",
  * the run is still active after them.
  */
 declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled"];
-/** Pluggable streamline integration for Arc */
+/**
+ * Pluggable streamline integration for Arc.
+ *
+ * Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
+ * plain plugin option (NOT an encapsulation prefix). Without the wrapper,
+ * Fastify would prepend `options.prefix` to every route, then the plugin
+ * code would prepend it again — the duplicate-prefix bug.
+ */
 declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };

package/dist/integrations/streamline.mjs

@@ -1,6 +1,22 @@
 import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-j4aJm1Wg.mjs";
+import fp from "fastify-plugin";
 //#region src/integrations/streamline.ts
 /**
+* Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
+* `'failed'`; the discrimination is `error.code`:
+*   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
+*   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
+*   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
+*     resume against; admin must rewind / migrate / cancel.
+*
+* Hosts switch on `error.code` for dashboards / alerting.
+*/
+const STREAMLINE_FAILURE_CODES = {
+	STALE_HEARTBEAT: "stale_heartbeat",
+	DEAD_LETTERED: "dead_lettered",
+	VERSION_MISMATCH: "VERSION_MISMATCH"
+};
+/**
 * Full event list published on a streamline workflow's internal `eventBus`
 * (tracks streamline 2.3's `EventPayloadMap` in
 * `@classytic/streamline/src/core/events.ts`).
@@ -44,6 +60,7 @@ const STREAMLINE_TERMINAL_EVENTS = [
 ];
 const streamlinePluginImpl = async (fastify, options) => {
 	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms } = options;
+	const routeScope = prefix;
 	const bridgeBus = options.bridgeBusEvents ?? false;
 	const registry = /* @__PURE__ */ new Map();
 	for (const wf of workflows) {
@@ -70,7 +87,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 		return check(request);
 	};
 	for (const [id, wf] of registry) {
-		const routePrefix = `${prefix}/${id}`;
+		const routePrefix = `${routeScope}/${id}`;
 		fastify.post(`${routePrefix}/start`, { preHandler: authPreHandler }, async (request, reply) => {
 			if (!await checkPerm("start", request)) throw new ForbiddenError();
 			const { input, meta, idempotencyKey, priority } = request.body ?? {};
@@ -161,6 +178,24 @@ const streamlinePluginImpl = async (fastify, options) => {
 			const { runId } = request.params;
 			return await wf.engine.execute(runId);
 		});
+		const deleteRepo = wf.container?.repository;
+		const repoDeleteFn = deleteRepo?.delete;
+		const repoGetByIdFn = deleteRepo?.getById;
+		if (repoDeleteFn && repoGetByIdFn) fastify.delete(`${routePrefix}/runs/:runId`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("cancel", request)) throw new ForbiddenError();
+			const { runId } = request.params;
+			const tenantOpts = resolveTenantOpts(request);
+			const repoOpts = {
+				...tenantOpts.tenantId !== void 0 ? { tenantId: tenantOpts.tenantId } : {},
+				...tenantOpts.bypassTenant ? { bypassTenant: true } : {}
+			};
+			if (!await repoGetByIdFn(runId, repoOpts)) throw new NotFoundError(`Workflow run ${runId} not found`);
+			try {
+				await wf.cancel(runId);
+			} catch {}
+			await repoDeleteFn(runId, repoOpts);
+			return reply.status(204).send();
+		});
 		if (wf.engine.waitFor) fastify.get(`${routePrefix}/runs/:runId/wait`, { preHandler: authPreHandler }, async (request, _reply) => {
 			if (!await checkPerm("get", request)) throw new ForbiddenError();
 			const { runId } = request.params;
@@ -239,7 +274,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 	}
 	if (enableHookEndpoint) {
 		let resumeHookFn;
-		fastify.post(`${prefix}/hooks/:token`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routeScope}/hooks/:token`, { preHandler: authPreHandler }, async (request, _reply) => {
 			if (!resumeHookFn) resumeHookFn = (await import("@classytic/streamline")).resumeHook;
 			const { token } = request.params;
 			const result = await resumeHookFn(token, request.body);
@@ -249,7 +284,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			};
 		});
 	}
-	fastify.get(prefix, { preHandler: authPreHandler }, async () => {
+	fastify.get(routeScope || "/", { preHandler: authPreHandler }, async () => {
 		return Array.from(registry.entries()).map(([id, wf]) => ({
 			id,
 			name: wf.definition.name ?? id,
@@ -257,10 +292,23 @@ const streamlinePluginImpl = async (fastify, options) => {
 		}));
 	});
 	fastify.addHook("onClose", async () => {
-		for (const wf of registry.values()) wf.shutdown?.();
+		for (const wf of registry.values()) {
+			wf.shutdown?.();
+			wf.container?.dispose?.();
+		}
 	});
 };
-/** Pluggable streamline integration for Arc */
-const streamlinePlugin = streamlinePluginImpl;
+/**
+* Pluggable streamline integration for Arc.
+*
+* Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
+* plain plugin option (NOT an encapsulation prefix). Without the wrapper,
+* Fastify would prepend `options.prefix` to every route, then the plugin
+* code would prepend it again — the duplicate-prefix bug.
+*/
+const streamlinePlugin = fp(streamlinePluginImpl, {
+	name: "streamline-routes",
+	fastify: "5.x"
+});
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_TERMINAL_EVENTS, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, streamlinePlugin };

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
 import { On as HookSystem, Q as MiddlewareConfig, Wt as AnyRecord, ft as RouteSchemaOptions, lt as RouteDefinition, tt as PresetHook, z as ResourceRegistry } from "../index-BswOSJCE.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
-import { a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6 } from "../versioning-DTTvc80y.mjs";
+import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6, v as _default$3, y as healthPlugin } from "../versioning-hmkPcDlX.mjs";
 import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-DFr45ZG4.mjs";
 import { t as TracingOptions } from "../tracing-QJVprktp.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
@@ -137,39 +137,6 @@ declare module "fastify" {
 }
 declare const _default$2: FastifyPluginAsync<GracefulShutdownOptions>;
 //#endregion
-//#region src/plugins/health.d.ts
-declare module "fastify" {
-  interface FastifyRequest {
-    _startTime?: number;
-  }
-}
-interface HealthCheck {
-  /** Name of the dependency */
-  name: string;
-  /** Function that returns true if healthy, false otherwise */
-  check: () => Promise<boolean> | boolean;
-  /** Optional timeout in ms (default: 5000) */
-  timeout?: number;
-  /** Whether this check is critical for readiness (default: true) */
-  critical?: boolean;
-}
-interface HealthOptions {
-  /** Route prefix (default: '/_health') */
-  prefix?: string;
-  /** Health check dependencies */
-  checks?: HealthCheck[];
-  /** Enable metrics endpoint (default: false) */
-  metrics?: boolean;
-  /** Custom metrics collector function */
-  metricsCollector?: () => Promise<string> | string;
-  /** Version info to include in responses */
-  version?: string;
-  /** Collect HTTP request metrics (default: true if metrics enabled) */
-  collectHttpMetrics?: boolean;
-}
-declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
-declare const _default$3: FastifyPluginAsync<HealthOptions>;
-//#endregion
 //#region src/plugins/replyHelpers.d.ts
 declare module "fastify" {
   interface FastifyReply {

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.15.0";
+	const resolvedVersion = serviceVersion ?? "2.15.4";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/presets/multiTenant.mjs

@@ -185,7 +185,8 @@ function multiTenantPreset(options = {}) {
 			get: [getFilter("get")],
 			create: [tenantInjection],
 			update: [getFilter("update"), tenantInjection],
-			delete: [getFilter("delete")]
+			delete: [getFilter("delete")],
+			aggregations: [strictTenantFilter]
 		}
 	};
 }

package/dist/{resourceToTools-D4pWzVGA.mjs → resourceToTools-tFYUNmM0.mjs}

@@ -1,9 +1,9 @@
 import { p as isArcError } from "./errors-j4aJm1Wg.mjs";
-import { t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { t as BaseController } from "./BaseController-dx3m2J8V.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-jSZ6Fdvi.mjs";
+import { n as executeAggregation, r as validateAggregations } from "./buildHandler-CcFOpJLh.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";

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
 import { V as ResourceDefinition, Wt as AnyRecord } from "../index-BswOSJCE.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-3YTpuLZ1.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-DrBaUwyV.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1070,7 +1070,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-BarYhXCZ.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-PFegs47-.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/{types-3YTpuLZ1.d.mts → types-DrBaUwyV.d.mts}

@@ -5,7 +5,7 @@ import { a as EventTransport } from "./EventTransport-CT_52aWU.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BD5nw6St.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-CqMdLI2-.mjs";
 import { t as EventPluginOptions } from "./eventPlugin-qXpqTebY.mjs";
-import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DTTvc80y.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-hmkPcDlX.mjs";
 import { t as ErrorHandlerOptions } from "./errorHandler-DFr45ZG4.mjs";
 import { r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
@@ -488,6 +488,16 @@ interface CreateAppOptions {
   trustProxy?: boolean;
   /** Fastify plugin/onReady timeout in ms (default: 10_000). Raise for slow boot work (index materialisation, WAL replay, external warm-up). */
   pluginTimeout?: number;
+  /**
+   * Maximum JSON body size in bytes. Pass-through to Fastify's
+   * server-level `bodyLimit` option; default is Fastify's 1 MiB
+   * (1_048_576 bytes). Raise for hosts shipping bulk-import / CSV ingest
+   * / JSON-RPC batch endpoints — without this, Fastify rejects oversized
+   * payloads with `FST_ERR_CTP_BODY_TOO_LARGE` (413) before any route
+   * handler runs. File uploads on `multipart` routes are governed
+   * separately by `multipart.limits.fileSize`. (2.15.1)
+   */
+  bodyLimit?: number;
   /**
    * Auth configuration
    *
@@ -578,8 +588,34 @@ interface CreateAppOptions {
   rawBody?: RawBodyOptions | false;
   /** Enable Arc plugins (requestId, health, gracefulShutdown, events, caching, sse) */
   arcPlugins?: {
-    /** Request ID tracking (default: true) */requestId?: boolean; /** Health endpoints (default: true) */
-    health?: boolean; /** Graceful shutdown handling (default: true) */
+    /** Request ID tracking (default: true) */requestId?: boolean;
+    /**
+     * Health endpoints (default: true).
+     *
+     * Three forms:
+     *   - `true` (default) — register Arc's health plugin with no extra checks
+     *     (`/_health/live` always 200, `/_health/ready` 200 unless explicit
+     *     readiness probes are added later).
+     *   - `false` — disable Arc's health plugin entirely; the host registers
+     *     its own (or none).
+     *   - `{ checks: HealthCheck[] }` — register Arc's health plugin AND
+     *     attach the supplied readiness probes (Mongo connectivity, engine
+     *     warmup, queue connectivity, etc.). Closes the pre-2.15.1 hole
+     *     where adding checks meant `health: false` + manual re-registration.
+     *
+     * @example
+     * ```typescript
+     * arcPlugins: {
+     *   health: {
+     *     checks: [
+     *       { name: 'mongo', check: async () => mongoose.connection.readyState === 1 },
+     *       { name: 'catalog-engine', check: async () => catalog.isReady() },
+     *     ],
+     *   },
+     * }
+     * ```
+     */
+    health?: boolean | HealthOptions; /** Graceful shutdown handling (default: true) */
     gracefulShutdown?: boolean; /** Emit events for CRUD operations (default: true) */
     emitEvents?: boolean;
     /**

package/dist/{versioning-DTTvc80y.d.mts → versioning-hmkPcDlX.d.mts}

@@ -1,6 +1,39 @@
 import { n as DomainEvent } from "./EventTransport-CT_52aWU.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
+//#region src/plugins/health.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    _startTime?: number;
+  }
+}
+interface HealthCheck {
+  /** Name of the dependency */
+  name: string;
+  /** Function that returns true if healthy, false otherwise */
+  check: () => Promise<boolean> | boolean;
+  /** Optional timeout in ms (default: 5000) */
+  timeout?: number;
+  /** Whether this check is critical for readiness (default: true) */
+  critical?: boolean;
+}
+interface HealthOptions {
+  /** Route prefix (default: '/_health') */
+  prefix?: string;
+  /** Health check dependencies */
+  checks?: HealthCheck[];
+  /** Enable metrics endpoint (default: false) */
+  metrics?: boolean;
+  /** Custom metrics collector function */
+  metricsCollector?: () => Promise<string> | string;
+  /** Version info to include in responses */
+  version?: string;
+  /** Collect HTTP request metrics (default: true if metrics enabled) */
+  collectHttpMetrics?: boolean;
+}
+declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
+declare const _default$4: FastifyPluginAsync<HealthOptions>;
+//#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
   /** Path prefix to match (e.g., '/api/products') */
@@ -114,4 +147,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u };
+export { HealthOptions as _, MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, HealthCheck as g, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u, _default$4 as v, healthPlugin as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.15.0",
+  "version": "2.15.4",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -245,9 +245,9 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.4.0",
-    "@classytic/repo-core": ">=0.4.0",
-    "@classytic/streamline": ">=2.3.0",
+    "@classytic/primitives": ">=0.5.0",
+    "@classytic/repo-core": ">=0.4.1",
+    "@classytic/streamline": ">=2.3.3",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
     "@fastify/jwt": ">=10.0.0",
@@ -357,11 +357,11 @@
     "@better-auth/mongo-adapter": "^1.6.9",
     "@biomejs/biome": "^2.4.11",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.13.0",
+    "@classytic/mongokit": "^3.13.2",
     "@classytic/primitives": "^0.4.0",
-    "@classytic/repo-core": "^0.4.0",
-    "@classytic/sqlitekit": "^0.3.0",
-    "@classytic/streamline": "^2.3.0",
+    "@classytic/repo-core": "^0.4.1",
+    "@classytic/sqlitekit": "^0.3.1",
+    "@classytic/streamline": "^2.3.3",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
@@ -420,4 +420,4 @@
     "type": "git",
     "url": "https://github.com/classytic/arc.git"
   }
-}
+}

package/skills/arc/SKILL.md

@@ -27,7 +27,7 @@ progressive_disclosure:
   entry_point:
     summary: "Resource-oriented Fastify framework: defineResource(), presets, permissions, QueryCache, events, multi-tenant, OpenAPI, MCP"
     when_to_use: "Building REST APIs with Fastify, resource CRUD, authentication, presets, caching, events, or production deployment"
-    quick_start: "1. arc init my-api --mongokit --jwt --ts  2. defineResource({ name, adapter, presets, permissions })  3. createApp({ preset: 'production', resources, auth })"
+    quick_start: "1. npx @classytic/arc init my-api --mongokit --better-auth --single --ts  2. defineResource({ name, adapter, presets, permissions })  3. createApp({ preset: 'production', resources, auth })"
 ---
 
 # @classytic/arc
@@ -39,11 +39,11 @@ One `defineResource()` call → REST + auth + permissions + events + cache + Ope
 ## Scaffold a project
 
 ```bash
-npx @classytic/arc@latest init my-api --mongokit --jwt --ts
+npx @classytic/arc@latest init my-api --mongokit --better-auth --single --ts
 cd my-api && npm install && npm run dev
 ```
 
-Flags: `--mongokit | --custom`, `--jwt | --better-auth`, `--single | --multi`, `--ts | --js`. The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass.
+Flags: `--mongokit | --custom`, `--better-auth | --jwt`, `--single | --multi`, `--ts | --js`, `--edge`, `--force`, `--skip-install`. Defaults: `--mongokit --better-auth --single --ts`. The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass.
 
 ## createApp()
 
@@ -639,6 +639,96 @@ defineResource({
 
 MCP auto-derives `filterableFields` from `queryParser`.
 
+## Aggregations — dashboards in declarative form
+
+Add `aggregations: { … }` to a resource and Arc registers `GET
+/{prefix}/aggregations/:name` per entry. Each runs a portable `$match
+→ $group → $project → $sort → $limit` pipeline against the kit's
+`repo.aggregate(req, options)` — same shape across mongokit /
+sqlitekit / prismakit, so dashboards work unchanged across backends.
+
+```typescript
+import { defineResource, defineAggregation } from '@classytic/arc';
+
+defineResource({
+  name: 'transaction',
+  adapter,
+  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
+  permissions: { list: canViewRevenue() },
+
+  aggregations: {
+    byPaymentMethod: defineAggregation({
+      groupBy: 'method',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { total: -1 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byFlow: defineAggregation({
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byDay: defineAggregation({
+      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { day: 1 },
+      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+  },
+});
+```
+
+**Tenant scope flows through the second arg, NOT the filter.** Arc is
+DB-agnostic — type-coercion (string → ObjectId for mongokit
+`fieldType: 'objectId'`, UUID/text for sqlitekit, etc.) belongs to the
+kit. Arc threads `tenantOptions` to `repo.aggregate(req, options)`;
+the kit's multi-tenant plugin reads `context.organizationId`, casts
+correctly, and merges into the request. Authors never inject the
+tenant key into `aggReq.filter` themselves.
+
+**2.15.3 — `multiTenantPreset` now wires `/aggregations/:name`.** Pre-2.15.3
+the preset only scoped CRUD; aggregation routes leaked across orgs for any
+caller whose `scope.kind !== 'member'`. Adding `multiTenantPreset({ tenantField: 'organizationId' })`
+now emits an `aggregations` middleware slot alongside the five CRUD slots, so
+member callers see only their org and `kind: 'elevated'` callers WITHOUT a
+target org get `bypassTenant: true` (platform-admin cross-tenant dashboards).
+**Kit config note:** set `scope: true` (or `scope: { fieldType: 'objectId' }`)
+on revenue/order/etc. engines — the pre-2.15.2 advice to use `scope: false`
+"to avoid double-scoping with arc" is no longer correct; arc 2.15.2+
+deliberately leaves `aggReq.filter` clean and relies on the kit. Required
+peers: `@classytic/repo-core ≥ 0.4.1`, `@classytic/mongokit ≥ 3.13.2`,
+`@classytic/sqlitekit ≥ 0.3.1`.
+
+**Caller filters via query string compose with `groupBy` / measures:**
+
+```
+GET /api/transactions/aggregations/byPaymentMethod?status=verified
+GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
+```
+
+**Safety guards on the declaration:**
+- `requireDateRange: { field, maxRangeDays }` — bounded range mandatory; kills accidental all-time scans
+- `requireFilters: ['orgId']` — mandatory scope keys
+- `maxGroups: 1000` — post-execution row cap; 422 on overflow
+
+**Cache invalidation:** writes through resource CRUD bump the
+matching tag. Aggregations cached with the same `tags` invalidate
+together. SWR mode serves stale immediately while revalidating in
+background.
+
+**MCP auto-export:** every aggregation surfaces as an MCP tool
+named `{resource}_aggregations_{name}` with the same permission gate
+and filter validation as the HTTP route.
+
+For backends without `repo.aggregate` (custom adapters), declare a
+`materialized` hook on the aggregation — Arc routes through it
+instead of the kit and returns the same `{ rows }` envelope.
+
 ## QueryCache
 
 TanStack Query-style server cache, stale-while-revalidate, auto-invalidation on mutations.
@@ -756,14 +846,17 @@ Full testing recipes → [references/testing.md](references/testing.md).
 
 ## CLI
 
+The bin is `arc` (registered by `@classytic/arc`). Outside an arc project use `npx @classytic/arc <cmd>`; inside one (devDep installed) bare `arc` resolves through `node_modules/.bin`.
+
 ```bash
-arc init my-api --mongokit --jwt --ts          # scaffold (also: --custom, --better-auth, --multi)
-arc generate resource product                   # generate a resource
-arc generate resource product --mcp             # + MCP tools file
-arc generate mcp analytics                      # standalone MCP tools file
-arc docs ./openapi.json --entry ./dist/index.js # emit OpenAPI
-arc introspect --entry ./dist/index.js
-arc doctor
+npx @classytic/arc init my-api --mongokit --better-auth --single --ts   # scaffold (also: --custom, --jwt, --multi, --js, --edge)
+npx @classytic/arc generate resource product                            # generate a resource (alias: arc g r product)
+npx @classytic/arc generate resource product --mcp                      # + MCP tools file
+npx @classytic/arc generate mcp analytics                               # standalone MCP tools file
+npx @classytic/arc docs ./openapi.json --entry ./dist/index.js          # emit OpenAPI
+npx @classytic/arc introspect --entry ./dist/index.js
+npx @classytic/arc describe ./dist/resources.js --json                  # JSON metadata for AI agents
+npx @classytic/arc doctor
 ```
 
 Set `"mcp": true` in `.arcrc` to always generate `.mcp.ts` alongside resources.

package/skills/arc-code-review/references/anti-patterns.md

@@ -894,6 +894,49 @@ Then check whether the hook body sets headers (`reply.header(`, `reply.headers[`
 
 ---
 
+## §33. Hand-rolled aggregation routes when `aggregations: { … }` would do 🟠
+
+**Detection:**
+```
+pattern: "Model\\.aggregate\\(\\["
+output_mode: content
+```
+Also: `\\.aggregate\\(\\s*\\[`, `\\$group\\b`, `\\$match\\b` inside resource handler files. Plus inline mongoose pipeline imports inside route handlers (vs. inside the kit's repository).
+
+**Anti-pattern:**
+```typescript
+// In a custom GET /aggregate/byPaymentMethod route:
+const orgId = getOrgId(getScope(req));
+const rows = await Transaction.aggregate([
+  { $match: { organizationId: new mongoose.Types.ObjectId(orgId), status: 'verified' } },
+  { $group: { _id: '$method', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+  { $sort: { total: -1 } },
+]);
+return reply.send({ rows });
+```
+
+**Why high:** loses every cross-cutting feature arc's aggregation router gives for free — per-aggregation permissions, OpenAPI schema, MCP tool export, SWR cache + tag invalidation, `requireFilters` / `requireDateRange` safety guards, `maxGroups` cap, multi-tenant scope without manual `ObjectId` casting. The hand-rolled version also drifts: every new bucket needs a new route, no central declaration, no unified shape across kits.
+
+**Fix:** declare `aggregations: { name: defineAggregation({ groupBy, measures, sort, cache, permissions }) }` on the resource. Arc registers `GET /:prefix/aggregations/:name` per entry, threads `tenantOptions` to `repo.aggregate(req, options)`, and the kit's multi-tenant plugin handles type-coercion. Type-coercion (string → ObjectId / UUID / text) is **the kit's responsibility, not the framework's** — never inject the tenant key into `aggReq.filter` from arc-host code.
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byPaymentMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+For backends without `repo.aggregate`, declare a `materialized` hook on the aggregation — the router calls it instead of the kit and keeps the same `{ rows }` envelope, permission gate, and cache contract.
+
+---
+
 ## Detection checklist (run-order)
 
 Run sweeps in this order — early hits often invalidate later context:
@@ -909,3 +952,4 @@ Run sweeps in this order — early hits often invalidate later context:
 9. §14, §18, §19 — preset adoption + custom controller wiring
 10. §11, §12, §13, §29, §30, §31 — style and edges
 11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
+12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`

package/skills/arc-code-review/references/arc-cheatsheet.md

@@ -246,6 +246,33 @@ Modes: `memory` (default) | `distributed` (`stores.queryCache: RedisCacheStore`)
 
 ---
 
+## Aggregations (declarative dashboards)
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+  byDay: defineAggregation({
+    dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+    groupBy: 'flow',
+    measures: { total: 'sum:amount' },
+    requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+Registers `GET /:prefix/aggregations/:name` per entry. Same permissions, OpenAPI, MCP tool, cache + tag invalidation as CRUD. Tenant flows via the kit's multi-tenant plugin (string → ObjectId casting handled by the kit, **not** by hand). Caller filters via query string (`?status=verified&createdAt[gte]=...`) compose with the declaration. Safety: `requireFilters`, `requireDateRange`, `maxGroups`. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly — see anti-patterns §33.
+
+---
+
 ## CLI
 
 ```bash