@classytic/arc 2.18.2 → 2.18.3

package/dist/{validate-DFIP2VrM.mjs → validate-0__MuUsK.mjs}

@@ -1,4 +1,192 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+//#region src/core/aggregation/normalize.ts
+/**
+* Framework cap on URL-driven aggregation limits when the host opts
+* in to `defaultLimit` without explicit `maxLimit`. Set to the same
+* order of magnitude as a "large dashboard page" — bigger than every
+* realistic grouped tile, smaller than "we returned the whole table."
+*/
+const AGG_FRAMEWORK_MAX_LIMIT = 1e3;
+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;
+	}
+}
+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;
+}
+/**
+* Collect fields that aggregation MUST NOT reference.
+*
+* Default rule: only `hidden: true` blocks. `hidden` means the field is
+* omitted from list/get responses, so exposing it via aggregation would
+* leak data the client can't otherwise see. `systemManaged` is a write
+* rule (server stamps the value, clients can't PATCH it) — those fields
+* are still visible per-row, so aggregating them leaks nothing.
+*
+* Two opt-in overrides via `ArcFieldRule.aggregable`:
+*   - `aggregable: false` — explicit deny on a visible field (rare; use
+*     when the per-row value is fine but the across-row distribution is
+*     itself sensitive).
+*   - `aggregable: true` — explicit allow, even on a `hidden` field
+*     (escape hatch — caller asserts cardinality leak isn't a concern).
+*/
+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.aggregable === true) continue;
+		if (rules.aggregable === false) {
+			blocked.add(field);
+			continue;
+		}
+		if (rules.hidden) blocked.add(field);
+	}
+	return blocked;
+}
+/**
+* Resolve the URL-driven limit policy into a concrete `{ default, max }`
+* pair. Returns `undefined` when the host uses the static `limit` form
+* (or no limit at all) — the request handler reads the absence to know
+* "do not parse `?limit=N` from the URL."
+*/
+function resolveLimitPolicy(config) {
+	if (config.defaultLimit === void 0) return void 0;
+	return {
+		defaultLimit: config.defaultLimit,
+		maxLimit: config.maxLimit ?? AGG_FRAMEWORK_MAX_LIMIT
+	};
+}
+/**
+* Resolve the effective per-request `limit` — three cases:
+*
+*   1. Host declared static `limit` → URL `?limit` ignored, static wins.
+*   2. Host declared `defaultLimit` → parse `?limit=N`, cap at
+*      `maxLimit`, fall back to default on absent / invalid input.
+*   3. Host declared neither → returns `undefined` (no limit applied,
+*      preserves pre-2.16.1 behavior).
+*/
+function resolveAggRequestLimit(normalized, query) {
+	const policy = normalized.compiled.limitPolicy;
+	if (!policy) return normalized.compiled.limit;
+	const raw = query["limit"];
+	if (raw === void 0 || raw === "") return policy.defaultLimit;
+	const parsed = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return policy.defaultLimit;
+	return Math.min(Math.floor(parsed), policy.maxLimit);
+}
+/** Compile to canonical `AggRequest` for `repo.aggregate()` at request time. */
+function compileAggRequest(normalized, callerFilter, tenantOptions, query) {
+	const filter = {
+		...normalized.compiled.filter ?? {},
+		...callerFilter
+	};
+	const executionHints = buildExecutionHints(normalized.base);
+	const cache = buildCacheOptions(normalized.base);
+	const limit = query ? resolveAggRequestLimit(normalized, query) : normalized.compiled.limit;
+	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 } : {},
+		...limit !== void 0 ? { 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
+	};
+}
+/**
+* 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;
+}
+//#endregion
 //#region src/core/aggregation/validate.ts
 var validate_exports = /* @__PURE__ */ __exportAll({
 	ArcAggregationConfigError: () => ArcAggregationConfigError,
@@ -11,13 +199,6 @@ var ArcAggregationConfigError = class extends Error {
 	name = "ArcAggregationConfigError";
 };
 /**
-* Framework cap on URL-driven aggregation limits when the host opts
-* in to `defaultLimit` without explicit `maxLimit`. Set to the same
-* order of magnitude as a "large dashboard page" — bigger than every
-* realistic grouped tile, smaller than "we returned the whole table."
-*/
-const AGG_FRAMEWORK_MAX_LIMIT = 1e3;
-/**
 * 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.
@@ -32,9 +213,9 @@ 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.`);
+		validateAggregationName(resourceName, name);
+		validatePermissionsDeclared(resourceName, name, config);
+		validateMeasuresNonEmpty(resourceName, name, config);
 		const lookupAliases = collectLookupAliases(config.lookups);
 		const measures = compileMeasures(resourceName, name, config.measures);
 		const groupBy = normalizeGroupBy(config.groupBy);
@@ -81,6 +262,15 @@ function validateAggregations(resourceName, aggregations, schemaOptions) {
 	}
 	return out;
 }
+function validateAggregationName(resourceName, name) {
+	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.`);
+}
+function validatePermissionsDeclared(resourceName, name, config) {
+	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.`);
+}
+function validateMeasuresNonEmpty(resourceName, name, config) {
+	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.`);
+}
 /**
 * Validate `limit` / `defaultLimit` / `maxLimit` triad. Throws on
 * misconfig at boot — boundary value, hosts see exactly what to fix.
@@ -102,19 +292,6 @@ function validateLimitConfig(resourceName, aggName, config) {
 	}
 }
 /**
-* Resolve the URL-driven limit policy into a concrete `{ default, max }`
-* pair. Returns `undefined` when the host uses the static `limit` form
-* (or no limit at all) — the request handler reads the absence to know
-* "do not parse `?limit=N` from the URL."
-*/
-function resolveLimitPolicy(config) {
-	if (config.defaultLimit === void 0) return void 0;
-	return {
-		defaultLimit: config.defaultLimit,
-		maxLimit: config.maxLimit ?? AGG_FRAMEWORK_MAX_LIMIT
-	};
-}
-/**
 * Adapter feature-detect for `aggregate()`. Called at boot when the
 * repository instance is available. Returns `true` when the kit ships
 * `aggregate`; `false` when missing.
@@ -127,66 +304,6 @@ function adapterSupportsAggregate(repo) {
 	return typeof repo.aggregate === "function";
 }
 /**
-* Resolve the effective per-request `limit` — three cases:
-*
-*   1. Host declared static `limit` → URL `?limit` ignored, static wins.
-*   2. Host declared `defaultLimit` → parse `?limit=N`, cap at
-*      `maxLimit`, fall back to default on absent / invalid input.
-*   3. Host declared neither → returns `undefined` (no limit applied,
-*      preserves pre-2.16.1 behavior).
-*/
-function resolveAggRequestLimit(normalized, query) {
-	const policy = normalized.compiled.limitPolicy;
-	if (!policy) return normalized.compiled.limit;
-	const raw = query["limit"];
-	if (raw === void 0 || raw === "") return policy.defaultLimit;
-	const parsed = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
-	if (!Number.isFinite(parsed) || parsed <= 0) return policy.defaultLimit;
-	return Math.min(Math.floor(parsed), policy.maxLimit);
-}
-/** Compile to canonical `AggRequest` for `repo.aggregate()` at request time. */
-function compileAggRequest(normalized, callerFilter, tenantOptions, query) {
-	const filter = {
-		...normalized.compiled.filter ?? {},
-		...callerFilter
-	};
-	const executionHints = buildExecutionHints(normalized.base);
-	const cache = buildCacheOptions(normalized.base);
-	const limit = query ? resolveAggRequestLimit(normalized, query) : normalized.compiled.limit;
-	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 } : {},
-		...limit !== void 0 ? { 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
@@ -267,21 +384,6 @@ function assertBucketFieldAllowed(input) {
 	}
 	if (blockedFields.has(field)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}", but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Bucketing 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);
@@ -302,55 +404,6 @@ function expandMeasure(input, resource, aggregation, alias) {
 	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
@@ -363,48 +416,6 @@ function validateMeasure(measure, resource, aggregation, alias) {
 		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;
-}
-/**
-* Collect fields that aggregation MUST NOT reference.
-*
-* Default rule: only `hidden: true` blocks. `hidden` means the field is
-* omitted from list/get responses, so exposing it via aggregation would
-* leak data the client can't otherwise see. `systemManaged` is a write
-* rule (server stamps the value, clients can't PATCH it) — those fields
-* are still visible per-row, so aggregating them leaks nothing.
-*
-* Two opt-in overrides via `ArcFieldRule.aggregable`:
-*   - `aggregable: false` — explicit deny on a visible field (rare; use
-*     when the per-row value is fine but the across-row distribution is
-*     itself sensitive).
-*   - `aggregable: true` — explicit allow, even on a `hidden` field
-*     (escape hatch — caller asserts cardinality leak isn't a concern).
-*/
-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.aggregable === true) continue;
-		if (rules.aggregable === false) {
-			blocked.add(field);
-			continue;
-		}
-		if (rules.hidden) blocked.add(field);
-	}
-	return blocked;
-}
 /**
 * Reject:
 *   - groupBy / measure.field / sort key referencing a hidden /
@@ -442,4 +453,4 @@ 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.`);
 }
 //#endregion
-export { validate_exports as i, compileAggRequest as n, validateAggregations as r, adapterSupportsAggregate as t };
+export { compileAggRequest as i, validateAggregations as n, validate_exports as r, adapterSupportsAggregate as t };

package/dist/{versioning-5H4930tj.d.mts → versioning-BSEDGXKC.d.mts}

@@ -1,4 +1,4 @@
-import { n as DomainEvent } from "./EventTransport-B1GFiYUy.mjs";
+import { n as DomainEvent } from "./EventTransport-CaaXM5Y1.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/plugins/health.d.ts

package/dist/{websocket-BZMUP7Gr.d.mts → websocket-BFBT5rH-.d.mts}

@@ -1,4 +1,4 @@
-import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-Bq_-EVsC.mjs";
+import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-Dqclzjy7.mjs";
 import { FastifyBaseLogger, FastifyPluginAsync } from "fastify";
 
 //#region src/integrations/websocket/adapter.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.18.2",
+  "version": "2.18.3",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -237,7 +237,7 @@
     "push": "classytic-push",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
     "release": "npm run push -- main && npm run release:tag && npm publish",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:main && npm run smoke"
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
   },
   "engines": {
     "node": ">=22"
@@ -359,10 +359,10 @@
     "@better-auth/mongo-adapter": "^1.6.9",
     "@biomejs/biome": "^2.4.15",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.14.0",
+    "@classytic/mongokit": "^3.16.0",
     "@classytic/primitives": "^0.6.0",
-    "@classytic/repo-core": "^0.5.0",
-    "@classytic/sqlitekit": "^0.5.0",
+    "@classytic/repo-core": "^0.6.0",
+    "@classytic/sqlitekit": "^0.6.0",
     "@classytic/streamline": "^2.3.3",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",

package/skills/arc/references/api-reference.md

@@ -183,7 +183,7 @@ import type { ArcRequest, IRequestContext, IControllerResponse } from '@classyti
 
 ## Notes
 
-- **No default exports** outside Fastify plugin entry files (`auditPlugin`, `authPlugin`, `eventPlugin`, `idempotencyPlugin`, `introspectionPlugin`).
+- **No default exports** outside Fastify plugin entry files (`fp()`-wrapped plugin entries — grep `export default fp` in src/ for the authoritative list).
 - **Type-only subpaths** produce `export {}` at runtime — interfaces are erased.
 - **Adapters live in kits**, not arc. Arc 2.12+ ships zero kit-bound adapters.
 - **Event types live in `@classytic/primitives/events`**, not `@classytic/arc/events`. Arc re-exports the runtime `MemoryEventTransport` only.