@classytic/arc 2.21.0 → 2.22.0

package/dist/{fields-BGqrAa_u.d.mts → types-Csxga7d3.d.mts}

@@ -195,124 +195,4 @@ interface PermissionCheckMeta {
   };
 }
 //#endregion
-//#region src/permissions/fields.d.ts
-/**
- * Field-Level Permissions
- *
- * Control field visibility and writability per role.
- * Integrated into the response path (read) and sanitization path (write).
- *
- * @example
- * ```typescript
- * import { fields, defineResource } from '@classytic/arc';
- *
- * const userResource = defineResource({
- *   name: 'user',
- *   adapter: userAdapter,
- *   fields: {
- *     salary: fields.visibleTo(['admin', 'hr']),
- *     internalNotes: fields.writableBy(['admin']),
- *     email: fields.redactFor(['viewer']),
- *     password: fields.hidden(),
- *   },
- * });
- * ```
- */
-type FieldPermissionType = "hidden" | "visibleTo" | "writableBy" | "redactFor";
-interface FieldPermission {
-  readonly _type: FieldPermissionType;
-  readonly roles?: readonly string[];
-  readonly redactValue?: unknown;
-}
-type FieldPermissionMap = Record<string, FieldPermission>;
-declare const fields: {
-  /**
-   * Field is never included in responses. Not writable via API.
-   *
-   * @example
-   * ```typescript
-   * fields: { password: fields.hidden() }
-   * ```
-   */
-  hidden(): FieldPermission;
-  /**
-   * Field is only visible to users with specified roles.
-   * Other users don't see the field at all.
-   *
-   * @example
-   * ```typescript
-   * fields: { salary: fields.visibleTo(['admin', 'hr']) }
-   * ```
-   */
-  visibleTo(roles: readonly string[]): FieldPermission;
-  /**
-   * Field is only writable by users with specified roles.
-   * All users can still read the field. Users without the role
-   * have the field silently stripped from write operations.
-   *
-   * @example
-   * ```typescript
-   * fields: { role: fields.writableBy(['admin']) }
-   * ```
-   */
-  writableBy(roles: readonly string[]): FieldPermission;
-  /**
-   * Field is redacted (replaced with a placeholder) for specified roles.
-   * Other users see the real value.
-   *
-   * @param roles - Roles that see the redacted value
-   * @param redactValue - Replacement value (default: '***')
-   *
-   * @example
-   * ```typescript
-   * fields: {
-   *   email: fields.redactFor(['viewer']),
-   *   ssn: fields.redactFor(['basic'], '***-**-****'),
-   * }
-   * ```
-   */
-  redactFor(roles: readonly string[], redactValue?: unknown): FieldPermission;
-};
-/**
- * Apply field-level READ permissions to a response object.
- * Strips hidden fields, enforces visibility, and applies redaction.
- *
- * @param data - The response object (mutated in place for performance)
- * @param fieldPermissions - Field permission map from resource config
- * @param userRoles - Current user's roles (empty array for unauthenticated)
- * @returns The filtered object
- */
-declare function applyFieldReadPermissions<T extends Record<string, unknown>>(data: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
-/**
- * Result of applying write permissions — includes both the filtered body
- * and the list of fields that were stripped so callers can decide whether
- * to reject the request (secure default) or silently strip (legacy).
- */
-interface FieldWritePermissionResult<T extends Record<string, unknown>> {
-  readonly body: T;
-  readonly deniedFields: readonly string[];
-}
-/**
- * Apply field-level WRITE permissions to request body.
- *
- * Returns both the filtered body and the list of denied fields. Callers are
- * expected to reject the request when `deniedFields.length > 0` — silently
- * stripping fields hides misconfigurations and real attacks. See
- * `BodySanitizer` for the default policy.
- *
- * @param body - The request body (returns a new filtered copy)
- * @param fieldPermissions - Field permission map from resource config
- * @param userRoles - Current user's roles
- */
-declare function applyFieldWritePermissions<T extends Record<string, unknown>>(body: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): FieldWritePermissionResult<T>;
-/**
- * Resolve effective roles by merging global user roles with org-level roles.
- *
- * Global roles come from `req.user.role` (normalized via getUserRoles()).
- * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
- *
- * When no org context exists, returns global roles only — backward compatible.
- */
-declare function resolveEffectiveRoles(userRoles: readonly string[], orgRoles: readonly string[]): string[];
-//#endregion
-export { applyFieldWritePermissions as a, PermissionCheck as c, UserBase as d, getUserRoles as f, applyFieldReadPermissions as i, PermissionContext as l, FieldPermissionMap as n, fields as o, normalizeRoles as p, FieldPermissionType as r, resolveEffectiveRoles as s, FieldPermission as t, PermissionResult as u };
+export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };

package/dist/usage/index.d.mts

@@ -0,0 +1,142 @@
+import { i as RequestScope } from "../types-DH0GupI7.mjs";
+import { n as PermissionContext, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+//#region src/usage/requireQuota.d.ts
+interface QuotaOptions {
+  /** Counter to enforce — `ai.tokens`, `export.runs`, `api.requests`, ... */
+  kind: string;
+  /**
+   * Ceiling for the current period. A number, `false` (unlimited — lets
+   * plan tables express "enterprise: false" uniformly), or a sync/async
+   * resolver receiving the permission context (plan-aware quotas).
+   */
+  limit: number | false | ((ctx: PermissionContext) => number | false | Promise<number | false>);
+  /**
+   * Actor key override. Default: the meter's own chain
+   * (org → user → client → `ip:<addr>`), so quota buckets are the same
+   * buckets usage writes and rate limits read.
+   */
+  actorOf?: (ctx: PermissionContext) => string | undefined;
+  /**
+   * Counter-store failure policy. Default `'allow'` (fail-open — see
+   * module header). `'deny'` throws the same 429 shape with
+   * `code: 'quota.unavailable'` and status 503.
+   */
+  onStoreError?: "allow" | "deny";
+  /** Memoize summary reads per (actor, kind) for this many ms. Default 0. */
+  cacheTtlMs?: number;
+}
+declare function requireQuota(options: QuotaOptions): PermissionCheck;
+//#endregion
+//#region src/usage/stores/interface.d.ts
+/**
+ * Usage store contract — period-bucketed counters per actor.
+ *
+ * CANONICAL HOME: `@classytic/repo-core/usage` (>=0.10) owns this
+ * contract for the ecosystem — kits implement it there without ever
+ * depending on arc (`@classytic/mongokit/usage`, ...). This file is a
+ * deliberate STRUCTURAL MIRROR of that shape — same trick as
+ * `ScheduleLockLike` vs repo-core's `LockAdapter` — so arc's emitted
+ * declarations carry no repo-core@>=0.10 subpath reference and the
+ * peer floor stays honest. Any conforming adapter assigns directly.
+ *
+ * The deliberately tiny surface (one increment, one read) is what makes
+ * every backend trivial: memory (dev/tests), Redis (`HINCRBY`), or any kit
+ * (Mongo `$inc` upsert) implements it in a handful of lines. Aggregation
+ * happens IN the store — arc never buffers counters in process memory
+ * beyond the built-in memory store, so multi-replica deployments stay
+ * correct as long as the store is shared.
+ *
+ * This is the HORIZONTAL usage layer (per-actor, per-period platform
+ * accounting for quotas/plans/billing). Itemized vertical records — e.g.
+ * `@classytic/arc-ai/usage`'s per-run AI token/cost tracking — keep their
+ * own richer stores and can sink into this one (`kind: 'ai.tokens'`).
+ */
+/** One counter cell: (actor, period, kind). */
+interface UsageBucket {
+  /** Who consumed — org / user / client id, or an IP-derived fallback. */
+  actor: string;
+  /** Aggregation period, `YYYY-MM` (see `usagePeriod()`). */
+  period: string;
+  /** Namespaced counter, dot-separated: `api.requests`, `ai.tokens`, `storage.bytes`. */
+  kind: string;
+}
+interface UsageStore {
+  /** Store name for diagnostics (e.g. 'memory', 'redis', 'mongo'). */
+  readonly name: string;
+  /** Add `amount` to the bucket's counter, creating it at 0 first. MUST be atomic per bucket. */
+  increment(bucket: UsageBucket, amount: number): Promise<void> | void;
+  /** Every counter for an actor in a period: `{ 'api.requests': 40231, ... }`. */
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+  /** Optional cleanup hook (connections, timers). */
+  close?(): Promise<void>;
+}
+/**
+ * Canonical period key for a date — calendar month, UTC: `2026-07`.
+ * Monthly is the billing-native granularity; stores that want finer
+ * windows can shard internally without changing the contract.
+ */
+declare function usagePeriod(date?: Date): string;
+//#endregion
+//#region src/usage/stores/memory.d.ts
+declare class MemoryUsageStore implements UsageStore {
+  #private;
+  readonly name = "memory";
+  increment(bucket: UsageBucket, amount: number): void;
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+  /** Test convenience — drop everything. */
+  clear(): void;
+}
+//#endregion
+//#region src/usage/usagePlugin.d.ts
+interface UsageTrackOptions {
+  /** Count every completed request as `api.requests` (default: true). */
+  requests?: boolean;
+  /** Sum `content-length` response bytes as `api.egress.bytes` (default: false). */
+  egress?: boolean;
+}
+interface UsagePluginOptions {
+  /** Master switch — `false` registers a typed no-op (config-gated environments). */
+  enabled?: boolean;
+  /** Counter backend. Default: in-memory (per-process — use a shared store in multi-replica). */
+  store?: UsageStore;
+  /** Automatic per-request accounting. Default: `{ requests: true, egress: false }`. */
+  track?: UsageTrackOptions;
+  /**
+   * Derive the actor key from a request. Default: org → user → client →
+   * `ip:<addr>` (same chain as `createTenantKeyGenerator`).
+   */
+  actorOf?: (request: FastifyRequest) => string | undefined;
+  /**
+   * Paths exempt from automatic tracking. Exact or trailing-`*` prefix.
+   * Default: `['/_health*', '/_metrics*']`.
+   */
+  ignorePaths?: string[];
+}
+/** The `fastify.usage` surface. */
+interface UsageMeter {
+  /**
+   * Add to a counter. `actor` may be a raw key or a `RequestScope`
+   * (derived via the org → user → client chain). Fire-and-forget safe:
+   * awaiting is optional, errors never throw into request flow.
+   */
+  record(actor: string | RequestScope | undefined, kind: string, amount?: number): Promise<void>;
+  /** All counters for an actor. Period defaults to the current month. */
+  summary(actor: string, period?: string): Promise<Record<string, number>>;
+  /** Canonical period key (`YYYY-MM`) for a date. */
+  period(date?: Date): string;
+  /** The actor key automatic tracking would use for this request. */
+  actorOf(request: FastifyRequest): string;
+  /** The active store (diagnostics). */
+  readonly store: UsageStore;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    /** Per-actor usage counters — registered by `usagePlugin`. */
+    usage?: UsageMeter;
+  }
+}
+declare const usagePluginFn: FastifyPluginAsync<UsagePluginOptions>;
+declare const _default: FastifyPluginAsync<UsagePluginOptions>;
+//#endregion
+export { MemoryUsageStore, type QuotaOptions, type UsageBucket, type UsageMeter, type UsagePluginOptions, type UsageStore, type UsageTrackOptions, _default as default, requireQuota, usagePeriod, usagePluginFn as usagePlugin };

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { Qt as UserLike, S as QueryParserInterface, b as ParsedQuery, et as OpenApiSchemas, qt as AnyRecord, st as ResourceConfig } from "../index-Dtrj6XZk.mjs";
-import { n as ErrorMapper } from "../errorHandler-B0e-bq-O.mjs";
+import { $ as OpenApiSchemas, Qt as UserLike, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
@@ -599,9 +599,8 @@ declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryPar
 interface JsonSchema {
   /**
    * Optional because JSON Schema allows top-level combinator-only schemas
-   * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-   * `listResponse()`, which emits a `oneOf` of the four canonical list
-   * shapes with no top-level `type`.
+   * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — hosts
+   * may pass such schemas anywhere a `JsonSchema` is accepted.
    */
   type?: string | string[];
   properties?: Record<string, JsonSchema | AnyRecord>;
@@ -623,18 +622,25 @@ interface JsonSchema {
  */
 declare const paginationSchema: JsonSchema;
 /**
- * List response schema — full union of every wire shape `toCanonicalList`
- * can emit. Hosts who know their endpoint only ever produces one variant
- * can pin to a narrower helper:
+ * List response schema — accepts every wire shape `toCanonicalList` can
+ * emit. Hosts who know their endpoint only ever produces one variant can
+ * pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
  *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
  *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
  *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
  *   - `bareListResponse(item)` — `{ data }`
  *
- * The default `listResponse(item)` is the union (`oneOf`) of all four so
- * Fastify validation accepts any canonical kit shape — pre-2.13 this only
- * modelled offset and rejected keyset/aggregate/bare lists at the
- * response-schema gate.
+ * SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+ * pre-2.22 union was semantically identical on the wire — every variant is
+ * `additionalProperties: true` and the property definitions never conflict
+ * (`next` only exists on keyset, the offset counters only on offset/
+ * aggregate; fast-json-stringify skips undefined optionals) — but
+ * fast-json-stringify implements top-level `oneOf` by running full AJV
+ * validation PER RESPONSE to pick the branch, on the hottest route of
+ * every arc app. The merge keeps the exact bytes (pinned by
+ * `tests/utils/list-response-serialization.test.ts`) and drops the
+ * per-response branch validation. Only `data` is required — the one field
+ * all four variants share.
  */
 declare function listResponse(itemSchema: JsonSchema): JsonSchema;
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
@@ -663,9 +669,8 @@ declare const responses: {
         schema: {
           /**
            * Optional because JSON Schema allows top-level combinator-only schemas
-           * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-           * `listResponse()`, which emits a `oneOf` of the four canonical list
-           * shapes with no top-level `type`.
+           * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — hosts
+           * may pass such schemas anywhere a `JsonSchema` is accepted.
            */
           type?: string | string[];
           properties?: Record<string, JsonSchema | AnyRecord>;
@@ -1103,6 +1108,20 @@ declare function isJsonSchema(input: unknown): input is Record<string, unknown>;
  * Check if an object is a Zod schema (has `_zod` marker from Zod v4).
  */
 declare function isZodSchema(input: unknown): boolean;
+/**
+ * How `toJsonSchema` reacts when a Zod schema CANNOT be converted (zod not
+ * installed/loaded, zod v3, or `z.toJSONSchema()` threw):
+ *
+ * - `'throw'` — fail fast with an actionable error. Used by
+ *   `convertRouteSchema` (VALIDATION path): a schema that silently degrades
+ *   to `{ type: 'object' }` is validation switched off — the worst outcome
+ *   for a wire contract, worse than a boot failure.
+ * - `'warn'` (default) — log loudly, degrade to a permissive `{ type:
+ *   'object' }`. Used by doc-generation paths (OpenAPI extraction of
+ *   Better Auth endpoints etc.), where the schema is third-party and a doc
+ *   gap must not take the app down.
+ */
+type UnconvertibleMode = "warn" | "throw";
 /**
  * Convert any schema input to JSON Schema.
  *
@@ -1110,13 +1129,16 @@ declare function isZodSchema(input: unknown): boolean;
  * 1. `null`/`undefined` → `undefined`
  * 2. Already JSON Schema → pass through as-is (zero overhead)
  * 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
- * 4. Unrecognized object → return as-is (treat as opaque schema)
+ * 4. Zod v3 schema → unconvertible (actionable "upgrade to v4" error/warn)
+ * 5. Unrecognized object → return as-is (treat as opaque schema)
  *
- * @param input Schema (Zod, plain JSON Schema, or opaque object)
+ * @param input  Schema (Zod, plain JSON Schema, or opaque object)
  * @param target Output target — defaults to `draft-7` for Fastify compatibility.
  *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
+ * @param mode   Failure policy for unconvertible Zod schemas — see
+ *               {@link UnconvertibleMode}. Defaults to `'warn'`.
  */
-declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget): Record<string, unknown> | undefined;
+declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.

package/dist/utils/index.mjs

@@ -1,6 +1,6 @@
 import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
-import { A as createCircuitBreaker, C as defineErrorMapper, D as CircuitBreakerError, E as CircuitBreaker, F as simpleEqualityMatcher, M as assertValidConfig, N as formatValidationErrors, O as CircuitBreakerRegistry, P as validateResourceConfig, S as defineGuard, T as withCompensation, _ as ArcQueryParser, a as bareListResponse, b as MONGO_DIALECT, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreakerRegistry, k as CircuitState, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as defineCompensation, x as NEUTRAL_DIALECT, y as handleRaw } from "../utils-CO8a3B_1.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-U0MnO9vd.mjs";
+import { A as createCircuitBreaker, C as defineErrorMapper, D as CircuitBreakerError, E as CircuitBreaker, F as simpleEqualityMatcher, M as assertValidConfig, N as formatValidationErrors, O as CircuitBreakerRegistry, P as validateResourceConfig, S as defineGuard, T as withCompensation, _ as ArcQueryParser, a as bareListResponse, b as MONGO_DIALECT, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreakerRegistry, k as CircuitState, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as defineCompensation, x as NEUTRAL_DIALECT, y as handleRaw } from "../utils-FhJ88TJE.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Ds5reSGs.mjs";
 import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-BQcW6_Kq.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/{utils-CO8a3B_1.mjs → utils-FhJ88TJE.mjs}

@@ -1295,26 +1295,72 @@ const paginationSchema = {
 	]
 };
 /**
-* List response schema — full union of every wire shape `toCanonicalList`
-* can emit. Hosts who know their endpoint only ever produces one variant
-* can pin to a narrower helper:
+* List response schema — accepts every wire shape `toCanonicalList` can
+* emit. Hosts who know their endpoint only ever produces one variant can
+* pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
 *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
 *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
 *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
 *   - `bareListResponse(item)` — `{ data }`
 *
-* The default `listResponse(item)` is the union (`oneOf`) of all four so
-* Fastify validation accepts any canonical kit shape — pre-2.13 this only
-* modelled offset and rejected keyset/aggregate/bare lists at the
-* response-schema gate.
+* SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+* pre-2.22 union was semantically identical on the wire — every variant is
+* `additionalProperties: true` and the property definitions never conflict
+* (`next` only exists on keyset, the offset counters only on offset/
+* aggregate; fast-json-stringify skips undefined optionals) — but
+* fast-json-stringify implements top-level `oneOf` by running full AJV
+* validation PER RESPONSE to pick the branch, on the hottest route of
+* every arc app. The merge keeps the exact bytes (pinned by
+* `tests/utils/list-response-serialization.test.ts`) and drops the
+* per-response branch validation. Only `data` is required — the one field
+* all four variants share.
 */
 function listResponse(itemSchema) {
-	return { oneOf: [
-		offsetListResponse(itemSchema),
-		keysetListResponse(itemSchema),
-		aggregateListResponse(itemSchema),
-		bareListResponse(itemSchema)
-	] };
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				description: "Pagination method discriminant — 'offset' | 'keyset' | 'aggregate'; absent on bare lists.",
+				example: "offset"
+			},
+			data: {
+				type: "array",
+				items: itemSchema
+			},
+			page: {
+				type: "integer",
+				example: 1
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			total: {
+				type: "integer",
+				example: 100
+			},
+			pages: {
+				type: "integer",
+				example: 5
+			},
+			hasNext: {
+				type: "boolean",
+				example: false
+			},
+			hasPrev: {
+				type: "boolean",
+				example: false
+			},
+			hasMore: { type: "boolean" },
+			next: {
+				type: ["string", "null"],
+				description: "Cursor token for the next page, or null."
+			}
+		},
+		required: ["data"],
+		additionalProperties: true
+	};
 }
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
 function offsetListResponse(itemSchema) {

package/dist/{versioning-DQ4mCvg0.d.mts → versioning-DLwklPlG.d.mts}

@@ -1,11 +1,6 @@
 import { n as DomainEvent } from "./EventTransport-QmY7A258.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;

package/llms.txt

@@ -0,0 +1,39 @@
+# @classytic/arc
+
+> Resource-oriented backend framework for Fastify. One `defineResource()` call =
+> REST + validation + auth + permissions + events + caching + OpenAPI + MCP tools.
+> DB-agnostic via @classytic/repo-core adapter kits (mongokit, sqlitekit, prismakit).
+
+IMPORTANT for coding agents: hand-rolling is a bug in arc apps. Before writing any
+route, validation, pagination, auth check, cron, queue worker, counter, or audit
+code, check whether arc provides it — it almost certainly does:
+
+- CRUD routes            → defineResource({ name, adapter, permissions })
+- Role/ownership checks  → @classytic/arc/permissions (requireRoles, requireOwnership, permissionMatrix, requireQuota)
+- Identity/tenant access → @classytic/arc/scope (getUserId, requireOrgId — never read scope fields directly)
+- Body/response schemas  → schemaOptions.fieldRules (customSchemas when wire ≠ model)
+- Query filter/sort/page → the resource queryParser (allow-listed) + keyset cursors
+- Soft delete/slug/tree/bulk/files/search → presets: [...]
+- Recurring jobs         → schedulesPlugin (@classytic/arc/plugins; LockAdapter leader safety)
+- Durable queues         → @classytic/arc/integrations/jobs (BullMQ/Redis) or @classytic/streamline (Mongo)
+- Headless worker process→ createWorker(sameOptions) (@classytic/arc/factory)
+- Usage counters/quotas  → @classytic/arc/usage (usagePlugin, requireQuota) + rateLimit.plan
+- Audit + record history → audit: true, history: true on the resource
+- Idempotency            → @classytic/arc/idempotency
+- Events/outbox/webhooks → @classytic/arc/events, integrations/webhooks
+- AI/MCP tools           → generated from every resource (incl. _count/_exists/_distinct list verbs)
+- App boot               → createApp({ beforeBoot: connectDatabase, ... }) — DB connect goes IN beforeBoot
+
+## Docs (inside this package)
+
+- skills/arc/SKILL.md — full framework guide (boot, defineResource, presets, auth, testing)
+- skills/arc/references/api-reference.md — every subpath import
+- skills/arc-code-review/references/arc-cheatsheet.md — hand-rolled-code → arc-feature map
+- skills/arc-code-review/SKILL.md — audit workflow for existing codebases
+
+## Conventions that bite
+
+- request.user is undefined on public routes — guard it.
+- Custom endpoints go in the resource's routes:/actions: (inherit auth/OpenAPI/MCP);
+  bare fastify.get() bypasses everything.
+- mongokit >=3.21 defaults schemaGenerator; schemaGenerator: false kills OpenAPI+MCP bodies.