@classytic/arc 2.21.0 → 2.23.0

package/dist/testing/index.mjs

@@ -1,5 +1,5 @@
 import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CHw3_oA_.mjs";
+import { d as getModuleExports, h as preloadResourcesAsync, m as preloadResources, n as createApp } from "../createApp-CjOeWJ9_.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -462,6 +462,73 @@ async function setupBetterAuthTestApp(input) {
 	};
 }
 //#endregion
+//#region src/testing/bootModuleApp.ts
+/**
+* The built-in DB factory: in-memory MongoDB via lazy devDep imports.
+* Everything Mongo-specific about the harness lives HERE — the harness
+* itself is driver-blind and any kit can replace this via `database`.
+*/
+async function mongoMemoryDatabase(opts) {
+	let mms;
+	try {
+		mms = await import("mongodb-memory-server");
+	} catch {
+		throw new Error("[arc-testing] bootModuleApp's default database is in-memory MongoDB — install 'mongodb-memory-server' + 'mongoose' as devDependencies, or inject your own `database` factory for a different store");
+	}
+	const server = opts.replset ? await mms.MongoMemoryReplSet.create({ replSet: { count: 1 } }) : await mms.MongoMemoryServer.create();
+	const uri = server.getUri();
+	const mongoose = (await import("mongoose")).default;
+	if (mongoose.connection.readyState !== 0) await mongoose.disconnect();
+	await mongoose.connect(uri);
+	mongoose.connection.deleteModel(/.*/);
+	return {
+		uri,
+		connection: mongoose.connection,
+		teardown: async () => {
+			if (mongoose.connection.readyState !== 0) await mongoose.disconnect().catch(() => void 0);
+			await server.stop().catch(() => void 0);
+		}
+	};
+}
+async function bootModuleApp(modules, options = {}) {
+	const db = await (options.database ?? mongoMemoryDatabase)({ replset: options.replset ?? false });
+	const ctx = {
+		uri: db.uri,
+		mongoUri: db.uri,
+		connection: db.connection
+	};
+	const resolved = typeof modules === "function" ? await modules(ctx) : modules;
+	const list = Array.isArray(resolved) ? resolved : [resolved];
+	let app;
+	try {
+		app = await createApp({
+			preset: "testing",
+			auth: false,
+			sensible: false,
+			...options.app,
+			modules: list
+		});
+		await app.ready();
+	} catch (err) {
+		await db.teardown().catch(() => void 0);
+		throw err;
+	}
+	let closed = false;
+	return {
+		app,
+		uri: db.uri,
+		mongoUri: db.uri,
+		connection: db.connection,
+		exports: (name) => getModuleExports(app, name),
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await app.close().catch(() => void 0);
+			await db.teardown().catch(() => void 0);
+		}
+	};
+}
+//#endregion
 //#region src/testing/fixtures.ts
 function createTestFixtures() {
 	const registry = /* @__PURE__ */ new Map();
@@ -1049,7 +1116,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-Bi61XxqU.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-CjOeWJ9_.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;
@@ -1119,4 +1186,4 @@ function createMinimalTestApp(options = {}) {
 	});
 }
 //#endregion
-export { HttpTestHarness, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, preloadResources, preloadResourcesAsync, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { HttpTestHarness, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OnTenantDeleteConfig, $t as UserOrganization, A as RequestIdOptions, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Fn as BaseControllerOptions, G as ActionsMap, Gt as JwtContext, H as ActionDefinition, Ht as AuthPluginOptions, I as MiddlewareHandler, J as CrudRouteKey, Jt as ApiResponse, K as ArcFieldRule, Kt as TokenPair, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserLike, S as QueryParserInterface, St as RouteHandler, T as CrudRouterOptions, U as ActionEntry, Ut as Authenticator, Vt as AuthHelpers, W as ActionHandlerFn, Wt as AuthenticatorContext, X as EventDefinition, Xt as JWTPayload, Y as CrudSchemas, Yt as ArcRequest, Z as FieldRule, Zt as ObjectId, _ as ControllerQueryOptions, _t as ControllerLike, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IControllerResponse, c as TypedController, ct as ResourceExtensions, d as PaginationResult, dt as ResourcePermissions, et as OpenApiSchemas, f as IntrospectionData, ft as RouteDefinition, g as ArcInternalMetadata, gt as ControllerHandler, h as ResourceMetadata, ht as RouteSchemaOptions, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHookContext, m as RegistryStats, mt as RouteMethod, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourceHooks, v as LookupOption, vt as FastifyHandler, w as ServiceContext, x as PopulateOption, xt as IRequestContext, y as OwnershipCheck, yt as IController } from "../index-Dtrj6XZk.mjs";
+import { $ as OpenApiSchemas, $t as UserLike, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, In as BaseControllerOptions, It as FastifyHandler, J as PresetHook, Jt as AnyRecord, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Qt as ObjectId, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Xt as ArcRequest, Y as PresetResult, Yt as ApiResponse, Z as CrudSchemas, Zt as JWTPayload, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, en as UserOrganization, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-BBsvQt7U.mjs";
 import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-BGqrAa_u.mjs";
+import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
 export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/{types-DRj-Ut4n.d.mts → types-5OuqeTDX.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-Dtrj6XZk.mjs";
+import { V as ResourceDefinition } from "./index-BBsvQt7U.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -157,6 +157,41 @@ interface CrudDescriptionMeta {
  *   Arc's auto-derived filterable-fields blurb.
  */
 type CrudDescriptionOverride = string | ((meta: CrudDescriptionMeta) => string);
+/**
+ * Execution wiring for MCP tools — the app-level services HTTP requests
+ * receive via Fastify decorators (`fastify.arc.hooks`, `fastify.events`,
+ * `fastify.audit`, `fastify.log`, `fastify.idempotency`) and MCP's
+ * synthetic-context path historically dropped.
+ *
+ * When present, tool handlers thread it into the request context so the
+ * controller pipeline achieves FULL HTTP parity: resource hooks run
+ * (before/around/after), the arcCorePlugin after-hook publishes
+ * `<resource>.<op>d` events (→ realtime feeds, webhooks, event-driven
+ * cache invalidation all see MCP-originated mutations), `ctx.server.*`
+ * works inside handlers, and mutating CRUD tools accept an optional
+ * `_idempotencyKey` input for retry-safe execution.
+ *
+ * `mcpPlugin` builds this automatically from its Fastify instance (lazy
+ * getters — decorator registration order doesn't matter). Standalone
+ * `resourceToTools()` / `createMcpServer()` callers pass their own, or
+ * omit it to keep the legacy dispatch-only behavior.
+ */
+interface McpExecutionWiring {
+  /** Shared `HookSystem` — `fastify.arc.hooks`. */
+  readonly hooks?: unknown;
+  /** Event bus decorator — `fastify.events`. */
+  readonly events?: unknown;
+  /** Audit decorator — `fastify.audit`. */
+  readonly audit?: unknown;
+  /** Structured logger — `fastify.log`. */
+  readonly log?: unknown;
+  /**
+   * Idempotency store (the `IdempotencyStore` contract from
+   * `@classytic/arc/idempotency`). Presence advertises `_idempotencyKey`
+   * on mutating CRUD tools and enables executor-level check/lock/replay.
+   */
+  readonly idempotencyStore?: unknown;
+}
 /** Per-resource MCP configuration overrides */
 interface McpResourceConfig {
   /** Which CRUD operations to expose (default: all enabled on the resource) */
@@ -392,4 +427,4 @@ interface CreateMcpServerConfig {
 /** CRUD operation type */
 type CrudOperation = "list" | "get" | "create" | "update" | "delete";
 //#endregion
-export { CrudDescriptionOverride as a, McpAuthResult as c, PromptDefinition as d, PromptResult as f, ToolDefinition as g, ToolContext as h, CrudDescriptionMeta as i, McpPluginOptions as l, ToolAnnotations as m, CallToolResult as n, CrudOperation as o, SessionEntry as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpResourceConfig as u };
+export { ToolDefinition as _, CrudDescriptionOverride as a, McpAuthResult as c, McpResourceConfig as d, PromptDefinition as f, ToolContext as g, ToolAnnotations as h, CrudDescriptionMeta as i, McpExecutionWiring as l, SessionEntry as m, CallToolResult as n, CrudOperation as o, PromptResult as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpPluginOptions as u };

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, $t as UserLike, Jt as AnyRecord, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery } from "../index-BBsvQt7U.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";
@@ -437,6 +437,34 @@ declare const NEUTRAL_DIALECT: FilterDialect;
  */
 declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
+//#region src/utils/headers.d.ts
+/**
+ * Canonical header typing + accessor.
+ *
+ * Node/Fastify header values are `string | string[] | undefined` — repeated
+ * headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+ * `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+ * adapter passes Fastify's headers object through unchanged, so `string[]`
+ * CAN appear at runtime behind the narrower type (the declared type is
+ * scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+ * through {@link getHeader} instead of indexing — it's honest about arrays
+ * and deterministic about duplicates.
+ */
+/** What a headers bag actually contains at runtime — HTTP or synthetic MCP. */
+type ArcHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Read a single header value. Lowercases the name (Node normalizes incoming
+ * header names to lowercase) and returns the FIRST value when the header
+ * was repeated.
+ *
+ * Duplicate policy: first-value is deterministic, but for security-sensitive
+ * headers (authorization material, forwarded-for chains, content-length) a
+ * duplicate usually signals smuggling or a broken proxy — consumers that
+ * care should check `Array.isArray(headers[name])` and REJECT instead of
+ * picking a winner.
+ */
+declare function getHeader(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+//#endregion
 //#region src/utils/queryParser.d.ts
 interface ArcQueryParserOptions {
   /** Maximum allowed limit value (default: 1000) */
@@ -599,9 +627,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 +650,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 +697,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 +1136,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 +1157,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.
@@ -1193,6 +1243,38 @@ declare function convertRouteSchema(schema: Record<string, unknown>, target?: Js
  */
 declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
 //#endregion
+//#region src/utils/sseStream.d.ts
+interface SseStreamOptions {
+  /** Heartbeat comment interval in ms (default: 30000). */
+  heartbeatMs?: number;
+  /**
+   * Reconnection-delay hint written once at connect as the standard SSE
+   * `retry:` field (WHATWG EventSource honors it natively). Omit to send
+   * no hint (browser default ~3s).
+   */
+  retryMs?: number;
+}
+interface SseStream {
+  /**
+   * Write one SSE frame. `id` (optional) becomes the standard SSE `id:`
+   * field — clients receive it as `lastEventId` (WHATWG), enabling
+   * client-side dedup/resume bookkeeping even when the server keeps no
+   * replay log. Returns `false` when the connection was destroyed
+   * (backpressure) — the stream is already cleaned up; stop writing.
+   */
+  write(eventName: string, data: string, id?: string): boolean;
+  /** Idempotent teardown: heartbeat cleared, cleanups run, socket ended. */
+  close(): void;
+  /** Register teardown work (unsubscribes etc.) — runs exactly once. */
+  onCleanup(fn: () => void): void;
+}
+/**
+ * Take over the reply socket and open an SSE stream. Call ONLY after every
+ * gate (auth, permissions, validation) has passed — after `hijack()` no
+ * JSON error can be sent.
+ */
+declare function openSseStream(request: FastifyRequest, reply: FastifyReply, options?: SseStreamOptions): SseStream;
+//#endregion
 //#region src/utils/stateMachine.d.ts
 /**
  * State Machine Utility
@@ -1453,4 +1535,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
  */
 declare function getUserId(user: UserLike | null | undefined): string | undefined;
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, 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 };
+export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/utils/index.mjs

@@ -1,6 +1,8 @@
 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 { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Cg05HPsn.mjs";
+import { A as CircuitState, C as defineGuard, D as CircuitBreaker, E as withCompensation, F as validateResourceConfig, M as createCircuitBreakerRegistry, N as assertValidConfig, O as CircuitBreakerError, P as formatValidationErrors, S as NEUTRAL_DIALECT, T as defineCompensation, _ as ArcQueryParser, a as bareListResponse, b as handleRaw, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreaker, k as CircuitBreakerRegistry, 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 defineErrorMapper, x as MONGO_DIALECT, y as getHeader } from "../utils-CZyeRXTh.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DJvodiHj.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 openSseStream } from "../sseStream-BQ7Qaynp.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 };
+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, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };