@classytic/arc 2.11.4 → 2.14.0

package/dist/buildHandler-olo-gt94.mjs

@@ -0,0 +1,610 @@
+//#region src/core/aggregation/validate.ts
+/** Thrown on aggregation misconfig at boot time. */
+var ArcAggregationConfigError = class extends Error {
+	name = "ArcAggregationConfigError";
+};
+/**
+* Validate + normalize all aggregations on a resource. Throws on first
+* misconfig with the offending aggregation name in the message — hosts
+* see exactly which entry needs fixing.
+*
+* Adapter feature-detection runs only when an `adapter` is present;
+* boot order means the controller's `repository` may be the
+* `RepositoryLike` shape. Best-effort `'aggregate' in repo` check covers
+* mongokit / sqlitekit; missing `aggregate()` deferred to request time
+* with a clear 501 (handled in the request handler).
+*/
+function validateAggregations(resourceName, aggregations, schemaOptions) {
+	const out = [];
+	const blockedFields = collectBlockedFields(schemaOptions);
+	for (const [name, config] of Object.entries(aggregations)) {
+		if (!isValidAggregationName(name)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation key "${name}" is invalid — keys map to URL segments and must be alphanumeric or underscore/hyphen.`);
+		if (typeof config.permissions !== "function") throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${name}" is missing a "permissions" check. Aggregations must declare permissions explicitly — no default-allow. Use a permission helper from @classytic/arc/permissions.`);
+		if (!config.measures || Object.keys(config.measures).length === 0) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${name}" has no measures. An empty "measures" map is a wiring bug — at least one measure is required.`);
+		const lookupAliases = collectLookupAliases(config.lookups);
+		const measures = compileMeasures(resourceName, name, config.measures);
+		const groupBy = normalizeGroupBy(config.groupBy);
+		const bucketAliases = config.dateBuckets ? Object.keys(config.dateBuckets) : [];
+		if (config.dateBuckets) validateDateBuckets({
+			resourceName,
+			aggregationName: name,
+			dateBuckets: config.dateBuckets,
+			groupBy,
+			measures,
+			lookupAliases,
+			blockedFields
+		});
+		validateFieldReferences({
+			resourceName,
+			aggregationName: name,
+			groupBy,
+			measures,
+			sort: config.sort,
+			having: config.having,
+			lookupAliases,
+			blockedFields,
+			bucketAliases
+		});
+		if (config.topN) validateTopNConfig(resourceName, name, config.topN, groupBy, measures, bucketAliases);
+		out.push({
+			name,
+			base: config,
+			compiled: {
+				filter: config.filter,
+				lookups: config.lookups,
+				groupBy: groupBy.length > 0 ? groupBy : void 0,
+				dateBuckets: config.dateBuckets,
+				measures,
+				having: config.having,
+				sort: config.sort,
+				limit: config.limit,
+				topN: config.topN
+			}
+		});
+	}
+	return out;
+}
+/**
+* Adapter feature-detect for `aggregate()`. Called at boot when the
+* repository instance is available. Returns `true` when the kit ships
+* `aggregate`; `false` when missing.
+*
+* `materialized`-only aggregations bypass this check at the request
+* handler — they never call `repo.aggregate`.
+*/
+function adapterSupportsAggregate(repo) {
+	if (!repo || typeof repo !== "object") return false;
+	return typeof repo.aggregate === "function";
+}
+/** 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,
+		...callerFilter
+	};
+	const executionHints = buildExecutionHints(normalized.base);
+	const cache = buildCacheOptions(normalized.base);
+	return {
+		measures: normalized.compiled.measures,
+		...Object.keys(filter).length > 0 ? { filter } : {},
+		...normalized.compiled.lookups ? { lookups: normalized.compiled.lookups } : {},
+		...normalized.compiled.groupBy ? { groupBy: normalized.compiled.groupBy } : {},
+		...normalized.compiled.dateBuckets ? { dateBuckets: normalized.compiled.dateBuckets } : {},
+		...normalized.compiled.having ? { having: normalized.compiled.having } : {},
+		...normalized.compiled.sort ? { sort: normalized.compiled.sort } : {},
+		...normalized.compiled.limit !== void 0 ? { limit: normalized.compiled.limit } : {},
+		...normalized.compiled.topN ? { topN: normalized.compiled.topN } : {},
+		...executionHints ? { executionHints } : {},
+		...cache ? { cache } : {}
+	};
+}
+/**
+* Translate the host's declarative `cache:` config into the TanStack-
+* shaped `CacheOptions` repo-core's unified cache plugin reads from
+* `req.cache`. The plugin handles SWR semantics, version-bump
+* invalidation, and tag side-index — arc just declares the policy.
+*
+* No translation needed when the host disabled cache (returns
+* undefined, kit falls through to a non-cached call).
+*/
+function buildCacheOptions(config) {
+	const c = config.cache;
+	if (!c) return void 0;
+	return {
+		...c.staleTime !== void 0 ? { staleTime: c.staleTime } : {},
+		...c.gcTime !== void 0 ? { gcTime: c.gcTime } : {},
+		...c.tags ? { tags: c.tags } : {},
+		swr: c.swr ?? true
+	};
+}
+/**
+* Boot validation for `topN`. Mirrors the contract mongokit + sqlitekit
+* enforce at request time — both kits check the same three rules and
+* throw with kit-prefixed messages. Running them at boot gives hosts
+* the misconfig surface BEFORE the first dashboard request, with the
+* offending aggregation name included for debugging. Same logic /
+* messages stay aligned across the kits and arc.
+*/
+function validateTopNConfig(resource, aggregation, topN, groupBy, measures, bucketAliases) {
+	if (!Number.isInteger(topN.limit) || topN.limit <= 0) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" topN.limit must be a positive integer — got ${String(topN.limit)}.`);
+	if (!topN.sortBy || Object.keys(topN.sortBy).length === 0) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" topN.sortBy must declare at least one ranking field.`);
+	const partitionList = Array.isArray(topN.partitionBy) ? topN.partitionBy : [topN.partitionBy];
+	if (partitionList.length === 0) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" topN.partitionBy must declare at least one partition column.`);
+	const validKeys = new Set([
+		...groupBy,
+		...bucketAliases,
+		...Object.keys(measures)
+	]);
+	for (const key of partitionList) if (!validKeys.has(key)) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" topN.partitionBy "${key}" is not a groupBy field, dateBucket alias, or measure alias. Available: ${[...validKeys].join(", ") || "(none — declare groupBy, dateBuckets, or measures)"}.`);
+}
+const VALID_BUCKET_UNITS = new Set([
+	"minute",
+	"hour",
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"year"
+]);
+const CUSTOM_BIN_UNIT_BLOCKLIST = new Set(["quarter", "year"]);
+/**
+* Validate `dateBuckets`. Catches the two classes of misconfig kits
+* already throw on at runtime — alias collisions and field-rule
+* violations — at boot, with the offending aggregation name in the
+* message.
+*
+* Rules (parity with mongokit's `validateBucketAliases` + sqlitekit's
+* `compileDateBucket` field-rule pass):
+*   1. Bucket alias MUST NOT collide with a groupBy field or measure
+*      alias — output row would have an ambiguous key.
+*   2. Bucket `field` (resolves to a base column or joined-alias path)
+*      must NOT be hidden / systemManaged.
+*   3. Custom-bin form (`{ every, unit }`): `every` is a positive
+*      integer; `unit` is in the supported set (minute/hour/day/week/
+*      month — quarter and year aren't valid in custom-bin form).
+*/
+function validateDateBuckets(input) {
+	const { resourceName, aggregationName, dateBuckets, groupBy, measures, lookupAliases, blockedFields } = input;
+	const groupBySet = new Set(groupBy);
+	const measureAliases = new Set(Object.keys(measures));
+	for (const [alias, bucket] of Object.entries(dateBuckets)) {
+		if (groupBySet.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket alias "${alias}" collides with a groupBy field. Pick a unique alias.`);
+		if (measureAliases.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket alias "${alias}" collides with a measure alias. Pick a unique alias.`);
+		assertBucketFieldAllowed({
+			resourceName,
+			aggregationName,
+			alias,
+			field: bucket.field,
+			lookupAliases,
+			blockedFields
+		});
+		if (typeof bucket.interval === "string") {
+			if (!VALID_BUCKET_UNITS.has(bucket.interval)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" interval "${bucket.interval}" is not a recognized unit. Use one of: ${[...VALID_BUCKET_UNITS].join(", ")}.`);
+			continue;
+		}
+		const { every, unit } = bucket.interval;
+		if (!Number.isInteger(every) || every <= 0) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" interval.every must be a positive integer — got ${String(every)}.`);
+		if (!VALID_BUCKET_UNITS.has(unit) || CUSTOM_BIN_UNIT_BLOCKLIST.has(unit)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" interval.unit "${unit}" is not valid in custom-bin form. Use minute / hour / day / week / month (quarter and year aren't supported as custom bins).`);
+	}
+}
+function assertBucketFieldAllowed(input) {
+	const { resourceName, aggregationName, alias, field, lookupAliases, blockedFields } = input;
+	const dot = field.indexOf(".");
+	if (dot > 0) {
+		const a = field.slice(0, dot);
+		if (lookupAliases.has(a)) return;
+		if (blockedFields.has(a)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}" whose root "${a}" is marked hidden or systemManaged in schemaOptions.fieldRules. Bucketing on hidden fields would leak temporal info.`);
+		return;
+	}
+	if (blockedFields.has(field)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}", but the field is marked hidden or systemManaged in schemaOptions.fieldRules. Bucketing on hidden fields would leak temporal info.`);
+}
+/**
+* Map arc's declarative knobs onto repo-core's portable `AggExecutionHints`.
+* Kits that don't honor a given hint silently ignore it (per IR contract);
+* mongokit threads `maxTimeMs` → `maxTimeMS` and `indexHint` → `aggregate.option({ hint })`.
+*/
+function buildExecutionHints(config) {
+	const hints = {};
+	if (typeof config.timeout === "number" && config.timeout > 0) hints.maxTimeMs = config.timeout;
+	if (config.indexHint && config.indexHint.leadingKeys.length > 0) {
+		const hintObj = {};
+		for (const key of config.indexHint.leadingKeys) hintObj[key] = 1;
+		hints.indexHint = hintObj;
+	}
+	return Object.keys(hints).length > 0 ? hints : void 0;
+}
+const NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+function isValidAggregationName(name) {
+	return NAME_PATTERN.test(name);
+}
+function compileMeasures(resource, aggregation, measures) {
+	const out = {};
+	for (const [alias, input] of Object.entries(measures)) out[alias] = expandMeasure(input, resource, aggregation, alias);
+	return out;
+}
+function expandMeasure(input, resource, aggregation, alias) {
+	let measure;
+	if (typeof input === "object" && input !== null) measure = input;
+	else if (typeof input === "string") {
+		const expanded = parseMeasureShorthand(input);
+		if (!expanded) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" measure "${alias}" has invalid shorthand "${input}". Use 'count', 'count:field', 'sum:field', 'avg:field', 'min:field', 'max:field', 'countDistinct:field', or 'percentile:field:p' (p ∈ [0, 1]).`);
+		measure = expanded;
+	} else throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" measure "${alias}" is not a string or object: got ${typeof input}.`);
+	validateMeasure(measure, resource, aggregation, alias);
+	return measure;
+}
+function parseMeasureShorthand(s) {
+	if (s === "count") return { op: "count" };
+	const colon = s.indexOf(":");
+	if (colon < 0) return null;
+	const op = s.slice(0, colon);
+	const rest = s.slice(colon + 1);
+	if (!rest) return null;
+	if (op === "percentile") {
+		const lastColon = rest.lastIndexOf(":");
+		if (lastColon < 0) return null;
+		const field = rest.slice(0, lastColon);
+		const pStr = rest.slice(lastColon + 1);
+		if (!field || !pStr) return null;
+		const p = Number(pStr);
+		if (!Number.isFinite(p)) return null;
+		return {
+			op: "percentile",
+			field,
+			p
+		};
+	}
+	switch (op) {
+		case "count": return {
+			op: "count",
+			field: rest
+		};
+		case "countDistinct": return {
+			op: "countDistinct",
+			field: rest
+		};
+		case "sum": return {
+			op: "sum",
+			field: rest
+		};
+		case "avg": return {
+			op: "avg",
+			field: rest
+		};
+		case "min": return {
+			op: "min",
+			field: rest
+		};
+		case "max": return {
+			op: "max",
+			field: rest
+		};
+		default: return null;
+	}
+}
+/**
+* Per-measure boot validation. Currently only `percentile` carries a
+* numeric constraint — `p ∈ [0, 1]` matches mongokit's request-time
+* check (and SQL's `PERCENTILE_CONT` semantics). Running it at boot
+* surfaces the misconfig with the offending aggregation + measure
+* alias instead of a kit-side error at first traffic.
+*/
+function validateMeasure(measure, resource, aggregation, alias) {
+	if (measure.op === "percentile") {
+		if (!Number.isFinite(measure.p) || measure.p < 0 || measure.p > 1) throw new ArcAggregationConfigError(`Resource "${resource}" aggregation "${aggregation}" measure "${alias}" has invalid percentile p=${String(measure.p)} — must be a finite number in [0, 1] (e.g. 0.5 for median, 0.95 for P95).`);
+	}
+}
+function normalizeGroupBy(groupBy) {
+	if (!groupBy) return [];
+	if (typeof groupBy === "string") return [groupBy];
+	return [...groupBy];
+}
+function collectLookupAliases(lookups) {
+	const aliases = /* @__PURE__ */ new Set();
+	if (!lookups) return aliases;
+	for (const lookup of lookups) aliases.add(lookup.as ?? lookup.from);
+	return aliases;
+}
+function collectBlockedFields(schemaOptions) {
+	const blocked = /* @__PURE__ */ new Set();
+	const fieldRules = schemaOptions?.fieldRules;
+	if (!fieldRules) return blocked;
+	for (const [field, rules] of Object.entries(fieldRules)) {
+		if (!rules) continue;
+		if (rules.hidden || rules.systemManaged) blocked.add(field);
+	}
+	return blocked;
+}
+/**
+* Reject:
+*   - groupBy / measure.field / sort key referencing a hidden /
+*     systemManaged field
+*   - dotted-path references (`alias.field`) where `alias` doesn't
+*     match a `LookupSpec.as` (or `from` default)
+*
+* Sort keys may also reference measure aliases, groupBy fields, or
+* dateBucket aliases (all auto-valid — already validated upstream) —
+* those branches accept without further checks.
+*/
+function validateFieldReferences(input) {
+	const { groupBy, measures, sort, bucketAliases } = input;
+	for (const key of groupBy) assertFieldAllowed("groupBy", key, input);
+	for (const [alias, measure] of Object.entries(measures)) if ("field" in measure && measure.field) assertFieldAllowed(`measures.${alias}`, measure.field, input);
+	if (sort) {
+		const measureAliases = new Set(Object.keys(measures));
+		const groupBySet = new Set(groupBy);
+		const bucketSet = new Set(bucketAliases);
+		for (const key of Object.keys(sort)) {
+			if (measureAliases.has(key) || groupBySet.has(key) || bucketSet.has(key)) continue;
+			assertFieldAllowed(`sort.${key}`, key, input);
+		}
+	}
+}
+function assertFieldAllowed(context, ref, input) {
+	const { resourceName, aggregationName, lookupAliases, blockedFields } = input;
+	const dot = ref.indexOf(".");
+	if (dot > 0) {
+		const alias = ref.slice(0, dot);
+		if (lookupAliases.has(alias)) return;
+		if (blockedFields.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context} whose root "${alias}" is marked hidden or systemManaged in schemaOptions.fieldRules. Aggregating hidden fields would leak cardinality information.`);
+		return;
+	}
+	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is marked hidden or systemManaged 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
+/**
+* Framework-agnostic aggregation execution. Runs safety guards,
+* compiles the AggRequest, dispatches to the materialized hook or
+* `repo.aggregate()`, and applies the post-execution `maxGroups` cap.
+*
+* Returns an envelope describing the response — Fastify wrappers
+* apply it to a reply, MCP wrappers convert it to a tool-call result.
+*
+* **Does NOT run the per-aggregation permission check.** Auth runs
+* upstream (Fastify preHandler chain or MCP `evaluatePermission`)
+* because the permission shape differs by surface (FastifyRequest vs
+* MCP session). Both surfaces fail-closed BEFORE reaching this
+* function; this is purely the runtime executor.
+*/
+async function executeAggregation(normalized, deps, ctx) {
+	const { repo } = deps;
+	const config = normalized.base;
+	const aggregationName = normalized.name;
+	const { query, tenantOptions } = ctx;
+	const guardError = checkRequestGuards(query, config);
+	if (guardError) return {
+		status: 400,
+		body: guardError
+	};
+	const aggReq = compileAggRequest(normalized, extractCallerFilter(query), tenantOptions);
+	if (config.materialized) {
+		const matCtx = {
+			filter: aggReq.filter,
+			orgId: pickString(tenantOptions.organizationId),
+			userId: pickString(tenantOptions.userId),
+			requestId: pickString(tenantOptions.requestId),
+			query
+		};
+		return {
+			status: 200,
+			headers: { "x-aggregation-source": "materialized" },
+			body: { rows: (await config.materialized(matCtx)).rows }
+		};
+	}
+	if (!adapterSupportsAggregate(repo)) return {
+		status: 501,
+		body: {
+			code: "arc.adapter.capability_required",
+			message: `Aggregation "${aggregationName}" is not supported: the resource's storage adapter does not implement repo.aggregate(). Use a kit that ships StandardRepo.aggregate (mongokit / sqlitekit), or remove the aggregations entry.`,
+			status: 501,
+			meta: {
+				capability: "aggregate",
+				aggregation: aggregationName
+			}
+		}
+	};
+	let result;
+	try {
+		result = await repo.aggregate(aggReq);
+	} catch (err) {
+		return mapAggregateError(err, aggregationName);
+	}
+	if (config.maxGroups !== void 0 && result.rows.length > config.maxGroups) return {
+		status: 422,
+		body: {
+			code: "arc.aggregation.max_groups_exceeded",
+			message: `Aggregation "${aggregationName}" produced ${result.rows.length} groups, exceeding maxGroups (${config.maxGroups}). Narrow the filter or raise the cap.`,
+			status: 422,
+			meta: {
+				aggregation: aggregationName,
+				produced: result.rows.length,
+				maxGroups: config.maxGroups
+			}
+		}
+	};
+	return {
+		status: 200,
+		body: { rows: result.rows }
+	};
+}
+/**
+* Build the Fastify handler for a single aggregation.
+*
+* The returned function calls the repo (or materialized hook), shapes
+* the response envelope, and writes status/headers via Fastify's
+* `reply` API. Errors throw — the router's error handler converts to
+* the standard arc response shape.
+*/
+/**
+* Build the Fastify handler for a single aggregation.
+*
+* Caching lives in the kit's repo-core `cachePlugin` — when the host
+* declares `cache:` on the aggregation, `compileAggRequest` translates
+* to `aggReq.cache: CacheOptions` and the kit handles SWR + tag
+* invalidation + version-bump on writes. Arc passes the request
+* through; no duplicate cache layer at the HTTP handler.
+*/
+function buildAggregationHandler(normalized, deps) {
+	const { buildOptions } = deps;
+	return async (request, reply) => {
+		const result = await executeAggregation(normalized, deps, {
+			query: request.query ?? {},
+			tenantOptions: buildOptions(request)
+		});
+		reply.status(result.status);
+		if (result.headers) for (const [k, v] of Object.entries(result.headers)) reply.header(k, v);
+		return result.body;
+	};
+}
+function pickString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function checkRequestGuards(query, config) {
+	if (config.requireFilters) {
+		for (const field of config.requireFilters) if (!hasFilterOnField(query, field)) return {
+			code: "arc.aggregation.required_filter_missing",
+			message: `Aggregation requires filter on "${field}" — supply ?${field}=... or ?${field}[op]=... in the query string.`,
+			status: 400,
+			meta: { field }
+		};
+	}
+	if (config.requireDateRange) {
+		const { field, maxRangeDays } = config.requireDateRange;
+		const range = parseDateRange(query, field);
+		if (!range) return {
+			code: "arc.aggregation.required_date_range_missing",
+			message: `Aggregation requires a bounded date range on "${field}" — supply ?${field}[gte]=... and ?${field}[lt]=... (or ?${field}[lte]=...).`,
+			status: 400,
+			meta: { field }
+		};
+		if (maxRangeDays !== void 0) {
+			const days = (range.upper.getTime() - range.lower.getTime()) / 864e5;
+			if (days > maxRangeDays) return {
+				code: "arc.aggregation.date_range_exceeded",
+				message: `Aggregation date range on "${field}" exceeds the cap (${maxRangeDays} days). Requested range: ${days.toFixed(1)} days. Narrow the range and retry.`,
+				status: 400,
+				meta: {
+					field,
+					maxRangeDays,
+					requestedDays: days
+				}
+			};
+		}
+	}
+	return null;
+}
+function hasFilterOnField(query, field) {
+	const direct = query[field];
+	if (direct !== void 0 && direct !== "") return true;
+	for (const key of Object.keys(query)) if (key.startsWith(`${field}[`)) return true;
+	return false;
+}
+function parseDateRange(query, field) {
+	let gte;
+	let lte;
+	const nested = query[field];
+	if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+		const ops = nested;
+		gte = pickString(ops.gte) ?? pickString(ops.gt);
+		lte = pickString(ops.lte) ?? pickString(ops.lt);
+	}
+	if (!gte) gte = pickString(query[`${field}[gte]`]) ?? pickString(query[`${field}[gt]`]);
+	if (!lte) lte = pickString(query[`${field}[lte]`]) ?? pickString(query[`${field}[lt]`]);
+	if (!gte || !lte) return null;
+	const lower = new Date(gte);
+	const upper = new Date(lte);
+	if (Number.isNaN(lower.getTime()) || Number.isNaN(upper.getTime())) return null;
+	if (upper <= lower) return null;
+	return {
+		lower,
+		upper
+	};
+}
+/**
+* Strip control params (page/limit/sort/select/...) and the resource-
+* dispatch verbs from the query, leaving only filter predicates the
+* caller used to narrow the aggregation.
+*
+* The resulting record is shallow-merged into the AggRequest filter
+* via `compileAggRequest`. Bracket-syntax keys (`createdAt[gte]`) are
+* preserved — the kit's filter compiler handles them.
+*/
+function extractCallerFilter(query) {
+	const out = {};
+	const reserved = new Set([
+		"page",
+		"limit",
+		"after",
+		"sort",
+		"select",
+		"populate",
+		"search",
+		"_count",
+		"_distinct",
+		"_exists"
+	]);
+	for (const [key, value] of Object.entries(query)) {
+		if (reserved.has(key)) continue;
+		if (value === void 0 || value === "") continue;
+		out[key] = value;
+	}
+	return out;
+}
+/**
+* Map a kit-thrown error to the framework-agnostic execute response.
+* Detects two well-known signals:
+*   - "unsupported" / "not implemented" → 501 with upgrade hint
+*   - timeout markers → 504
+*   - everything else → 500
+*/
+function mapAggregateError(err, aggregationName) {
+	const message = err instanceof Error ? err.message : String(err);
+	const lower = message.toLowerCase();
+	if (lower.includes("unsupported") || lower.includes("not implemented")) return {
+		status: 501,
+		body: {
+			code: "arc.adapter.capability_required",
+			message: `Aggregation "${aggregationName}" failed: ${message}. The kit may not yet support this feature (e.g. lookups in aggregate). Upgrade the kit or remove the unsupported field.`,
+			status: 501,
+			meta: { aggregation: aggregationName }
+		}
+	};
+	if (lower.includes("maxtimems") || lower.includes("timeout") || lower.includes("timed out")) return {
+		status: 504,
+		body: {
+			code: "arc.gateway_timeout",
+			message: `Aggregation "${aggregationName}" timed out: ${message}. Narrow the filter or raise the timeout.`,
+			status: 504,
+			meta: { aggregation: aggregationName }
+		}
+	};
+	return {
+		status: 500,
+		body: {
+			code: "arc.internal_error",
+			message: `Aggregation "${aggregationName}" failed: ${message}`,
+			status: 500,
+			meta: { aggregation: aggregationName }
+		}
+	};
+}
+//#endregion
+export { executeAggregation as n, validateAggregations as r, buildAggregationHandler as t };

package/dist/cache/index.mjs

@@ -1,6 +1,6 @@
-import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-CARyUjiR.mjs";
-import { t as MemoryCacheStore } from "../memory-DikHSvWa.mjs";
-import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-Bq6bO6vc.mjs";
+import { t as MemoryCacheStore } from "../memory-UBydS5ku.mjs";
+import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-CGcCbNyu.mjs";
+import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-m1XsgAIJ.mjs";
 //#region src/cache/redis.ts
 /**
 * Redis-backed cache store.