@classytic/arc 2.41.1 → 2.44.0

package/dist/utils/index.d.mts

@@ -1,48 +1,19 @@
 
 import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-Ddl9OjmE.mjs";
-import { f as getUserId, m as normalizeRoles, p as getUserRoles, t as AnyRecord } from "../base-CxrV1LmG.mjs";
-import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-DHbyPo5j.mjs";
+import { f as getUserId, m as normalizeRoles, p as getUserRoles, t as AnyRecord } from "../base-CZyixEQR.mjs";
+import { Y as OpenApiSchemas, h as QueryParserInterface, p as ParsedQuery } from "../index-WH7xgvxS.mjs";
 import { n as ErrorMapper } from "../errorHandler--4rSMMvq.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-BGdVwP25.mjs";
-import { scheduleBackground } from "@classytic/repo-core/cache";
-import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
+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-JYc9vwqE.mjs";
+import { errorContractSchema } from "@classytic/repo-core/errors";
+import { FilterClause } from "@classytic/repo-core/query-parser";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 //#region src/utils/circuitBreaker.d.ts
-/**
- * Circuit Breaker Pattern
- *
- * Wraps external service calls with failure protection.
- * Prevents cascading failures by "opening" the circuit when
- * a service is failing, allowing it time to recover.
- *
- * States:
- * - CLOSED: Normal operation, requests pass through
- * - OPEN: Too many failures, all requests fail fast
- * - HALF_OPEN: Testing if service recovered, limited requests
- *
- * @example
- * import { CircuitBreaker } from '@classytic/arc/utils';
- *
- * const paymentBreaker = new CircuitBreaker(async (amount) => {
- *   return await stripe.charges.create({ amount });
- * }, {
- *   failureThreshold: 5,
- *   resetTimeout: 30000,
- *   timeout: 5000,
- * });
- *
- * try {
- *   const result = await paymentBreaker.call(100);
- * } catch (error) {
- *   // Handle failure or circuit open
- * }
- */
-declare const CircuitState: {
+export declare const CircuitState: {
   readonly CLOSED: "CLOSED";
   readonly OPEN: "OPEN";
   readonly HALF_OPEN: "HALF_OPEN";
 };
-type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
+export type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
 /**
  * Generic constraint for "any async function" that survives strict TS.
  *
@@ -187,11 +158,29 @@ interface CircuitBreakerStats {
   openedAt: number | null;
   lastCallAt: number | null;
 }
-declare class CircuitBreakerError extends Error {
-  state: CircuitState;
-  constructor(message: string, state: CircuitState);
+/**
+ * Thrown when a call is refused because the circuit is OPEN (or HALF_OPEN with
+ * every probe slot taken).
+ *
+ * An `ArcError` with status **503**, code `arc.circuit_open`. It extended plain
+ * `Error` and carried no status, so an open circuit reaching arc's error
+ * handler was classified `arc.internal_error`: a 500, logged at error level
+ * with a stack trace, once per fast-failed call. That is the opposite of what
+ * a breaker is for — it turned deliberate, cheap load shedding into the
+ * loudest failure in the logs, during exactly the outage where it fires
+ * thousands of times a minute.
+ *
+ * `retryAfter` (seconds, rounded up) is when the circuit next probes; the
+ * error handler sends it as `Retry-After`, so well-behaved clients back off
+ * for as long as the breaker is actually going to refuse them.
+ */
+export declare class CircuitBreakerError extends ArcError {
+  readonly state: CircuitState;
+  /** Seconds until the circuit next probes, when known. */
+  readonly retryAfter?: number;
+  constructor(message: string, state: CircuitState, retryAfter?: number);
 }
-declare class CircuitBreaker<T extends AnyAsyncFn> {
+export declare class CircuitBreaker<T extends AnyAsyncFn> {
   private state;
   private failures;
   private successes;
@@ -278,11 +267,11 @@ declare class CircuitBreaker<T extends AnyAsyncFn> {
  *   { name: 'email-service' }
  * );
  */
-declare function createCircuitBreaker<T extends AnyAsyncFn>(fn: T, options?: CircuitBreakerOptions): CircuitBreaker<T>;
+export declare function createCircuitBreaker<T extends AnyAsyncFn>(fn: T, options?: CircuitBreakerOptions): CircuitBreaker<T>;
 /**
  * Circuit breaker registry for managing multiple breakers
  */
-declare class CircuitBreakerRegistry {
+export declare class CircuitBreakerRegistry {
   private breakers;
   /**
    * Register a circuit breaker
@@ -317,7 +306,7 @@ declare class CircuitBreakerRegistry {
  * Create a new CircuitBreakerRegistry instance.
  * Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
  */
-declare function createCircuitBreakerRegistry(): CircuitBreakerRegistry;
+export declare function createCircuitBreakerRegistry(): CircuitBreakerRegistry;
 //#endregion
 //#region src/utils/circuitBreakerRedis.d.ts
 /**
@@ -347,7 +336,7 @@ interface RedisCircuitBreakerStateOptions {
   windowMs?: number;
 }
 /** Fixed-window cluster failure counter. See the module header. */
-declare class RedisCircuitBreakerState implements CircuitBreakerSharedState {
+export declare class RedisCircuitBreakerState implements CircuitBreakerSharedState {
   #private;
   readonly name = "redis";
   constructor(options: RedisCircuitBreakerStateOptions);
@@ -457,12 +446,12 @@ type CompensationResult = {
  *
  * @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
  */
-declare function withCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(_name: string, steps: readonly CompensationStep<TCtx>[], initialContext?: TCtx, hooks?: CompensationHooks): Promise<CompensationResult>;
+export declare function withCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(_name: string, steps: readonly CompensationStep<TCtx>[], initialContext?: TCtx, hooks?: CompensationHooks): Promise<CompensationResult>;
 interface CompensationDefinition<TCtx extends Record<string, unknown> = Record<string, unknown>> {
   readonly name: string;
   readonly execute: (initialContext?: TCtx, hooks?: CompensationHooks) => Promise<CompensationResult>;
 }
-declare function defineCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: readonly CompensationStep<TCtx>[]): CompensationDefinition<TCtx>;
+export declare function defineCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: readonly CompensationStep<TCtx>[]): CompensationDefinition<TCtx>;
 //#endregion
 //#region src/utils/defineErrorMapper.d.ts
 /**
@@ -478,7 +467,7 @@ declare function defineCompensation<TCtx extends Record<string, unknown> = Recor
  * called with a non-`T` error at runtime. This helper codifies that invariant
  * in one place.
  */
-declare function defineErrorMapper<T extends Error>(mapper: ErrorMapper<T>): ErrorMapper;
+export declare function defineErrorMapper<T extends Error>(mapper: ErrorMapper<T>): ErrorMapper;
 //#endregion
 //#region src/utils/defineGuard.d.ts
 interface GuardConfig<T> {
@@ -505,50 +494,21 @@ interface Guard<T> {
 /**
  * Create a typed guard. See module JSDoc for usage.
  */
-declare function defineGuard<T>(config: GuardConfig<T>): Guard<T>;
+export declare function defineGuard<T>(config: GuardConfig<T>): Guard<T>;
 //#endregion
 //#region src/utils/filter-dialect.d.ts
-/**
- * Filter dialects — decouple `ArcQueryParser` from any single datastore's
- * operator vocabulary.
- *
- * The parser owns everything store-INDEPENDENT: URL parsing, field/operator
- * whitelisting, depth limits, value coercion, ReDoS-safe regex sanitisation.
- * A `FilterDialect` owns the ONLY store-specific part of the output — which
- * token each neutral operator (`gte`, `like`, `in`, …) is emitted as, and how a
- * case-insensitive text match is expressed. Swap the dialect (or the whole
- * parser via `QueryParserInterface`) to target a non-Mongo store; the default
- * stays Mongo, so existing hosts are unaffected.
- */
 interface FilterDialect {
-  /**
-   * Neutral operator name → emitted token. An operator absent from this map is
-   * treated as unsupported (dropped), so a dialect also defines its operator set.
-   */
-  readonly operators: Readonly<Record<string, string>>;
-  /**
-   * Extra keys merged into a field-filter when a documented case-insensitive
-   * text operator (`like` / `contains`) is used. Mongo expresses this as a
-   * sibling `{ $options: 'i' }`; a dialect that encodes case-insensitivity in
-   * the operator itself returns `{}`.
-   */
-  caseInsensitiveModifier(): Record<string, unknown>;
+  /** Emit the parsed clauses as one filter. Several clauses on a field are ANDed. */
+  emit(clauses: readonly FilterClause[]): Record<string, unknown>;
+  /** The operator tokens this dialect can emit — for audits and docs. */
+  readonly tokens: readonly string[];
 }
+export declare const MONGO_DIALECT: FilterDialect;
 /**
- * Default dialect — MongoDB / MongoKit operator shape. Emits `$`-prefixed
- * tokens and the `$options: 'i'` case-insensitive sibling. This is what
- * `ArcQueryParser` uses when no dialect is supplied, so behaviour is identical
- * to every prior arc version.
- */
-declare const MONGO_DIALECT: FilterDialect;
-/**
- * Store-neutral reference dialect — emits UN-prefixed operator tokens as a
- * translation AST (`?price[gte]=40` → `{ price: { gte: 40 } }`, with
- * `{ caseInsensitive: true }` for `like`/`contains`). A non-Mongo adapter can
- * consume this directly instead of writing a full `QueryParserInterface`. Use
- * as a starting point; adjust the token names to your store's vocabulary.
+ * Store-neutral: `{ field: { <op>: value } }` with the grammar's own operator names, for a host
+ * that compiles the canonical clauses itself.
  */
-declare const NEUTRAL_DIALECT: FilterDialect;
+export declare const NEUTRAL_DIALECT: FilterDialect;
 //#endregion
 //#region src/utils/handleRaw.d.ts
 /**
@@ -558,195 +518,86 @@ declare const NEUTRAL_DIALECT: FilterDialect;
  *   The return value is sent raw (no envelope). If it returns `undefined`,
  *   the response body is empty (HTTP status only).
  * @param statusCode - HTTP status code for successful responses (default: 200)
+ * @returns The reply, so Fastify waits for it: resolving `undefined` after `reply.send()` while an
+ *   async `preSerialization` hook (idempotency, encryption) is pending re-sends an empty body.
  */
-declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+export declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
 //#endregion
 //#region src/utils/queryParser.d.ts
 interface ArcQueryParserOptions {
-  /** Maximum allowed limit value (default: 1000) */
+  /** Cap on `limit`; a larger request is clamped to it (default: 1000). */
   maxLimit?: number;
-  /** Default limit for pagination (default: 20) */
+  /** Per-page count when the URL omits `limit` (default: 20). */
   defaultLimit?: number;
-  /** Maximum regex pattern length (default: 500) */
+  /** Longest text-operator value or regex pattern (default: 200). */
   maxRegexLength?: number;
-  /** Maximum search query length (default: 200) */
+  /** Longest `search` (default: 200). */
   maxSearchLength?: number;
-  /** Maximum filter nesting depth (default: 10) */
-  maxFilterDepth?: number;
-  /**
-   * Whitelist of fields that can be filtered on.
-   * When set, only these fields are accepted as filters — all others are silently dropped.
-   * Also used by MCP to auto-derive filterable fields in tool schemas.
-   */
+  /** Filterable fields. Also used by MCP to derive filterable fields. */
   allowedFilterFields?: string[];
   /**
-   * REFUSE a filter key that is not in {@link allowedFilterFields}, instead of
-   * dropping it (default: `false` — today's drop behaviour, kept because arc
-   * is published and an unconditional throw would reject requests that work).
-   *
-   * Dropping a filter does not fail, it **WIDENS**: the caller asked for a
-   * narrower set and is silently answered with a broader one, HTTP 200. Two
-   * live instances:
-   *
-   *   `?filters[status]=pending` → 200, every row `status:"verified"`
-   *   `?productId=…` (the param is `skuRef`) → a different product's 75 units,
-   *     filed for weeks as "quant leakage"
-   *
-   * Turn this on per-parser, or fleet-wide via `ARC_STRICT_QUERY_PARAMS`.
-   * Mirrors the `ARC_STRICT_PERMISSIONS` precedent: off by default here, and
-   * the HOST opts in from its env-loader so a forgotten `.env` line cannot
-   * silently disable enforcement.
-   *
-   * Only the FILTER whitelist is covered. `allowedSortFields` /
-   * `allowedOperators` keep dropping: a rejected sort or operator degrades
-   * ordering, it does not widen the row set.
+   * REFUSE (400) a field, operator or sort field outside its allowlist — a dropped filter silently
+   * WIDENS the read. Default `true`; `false` (or `ARC_STRICT_QUERY_PARAMS=false`) logs and drops
+   * those instead. Malformed or smuggled input (`$where`, `x[$ne]`) is refused either way.
    */
   strictFilterFields?: boolean;
-  /**
-   * Whitelist of fields that can be sorted on.
-   * When set, sort fields not in this list are silently dropped.
-   * Also used by MCP to describe available sort options.
-   */
+  /** Sortable fields. Also used by MCP. */
   allowedSortFields?: string[];
-  /**
-   * Whitelist of filter operators (e.g. ['eq', 'ne', 'gt', 'lt', 'in']).
-   * When set, only these operators are accepted — all others are dropped.
-   * Also used by MCP to enrich list tool descriptions.
-   */
+  /** URL operator names permitted in `field[op]` (e.g. `['in', 'gte']`). Also used by MCP. */
   allowedOperators?: string[];
-  /**
-   * Datastore dialect for the EMITTED filter shape (operator tokens +
-   * case-insensitive expression). Defaults to `MONGO_DIALECT`. Pass
-   * `NEUTRAL_DIALECT` (or a custom one) to retarget the operator vocabulary
-   * without writing a full `QueryParserInterface`.
-   */
+  /** The emitted filter shape. Default `MONGO_DIALECT`. */
   dialect?: FilterDialect;
 }
 /**
- * Arc's default query parser
- *
- * Converts URL query parameters to a structured query format:
- * - Pagination: ?page=1&limit=20
- * - Sorting: ?sort=-createdAt,name (- prefix = descending)
- * - Filtering — TWO supported forms (both produce identical output):
- *     - Bare (default, terse):     `?status=active&price[gte]=100&price[lte]=500`
- *     - Bracket envelope:          `?filter[status]=active&filter[price][gte]=100`
- *   The envelope form matches the convention used by JSON:API / Stripe /
- *   most modern REST style guides, and is the safe choice on busy URLs
- *   that might otherwise collide with reserved meta keys (`page`, `sort`,
- *   `select`, `populate`, etc.). Operator notation (`[gte]`, `[lte]`,
- *   `[ne]`, `[in]`, ...) works inside either form.
- * - Search: ?search=keyword
- * - Populate: ?populate=author,category
- * - Field selection: ?select=name,price,status
- * - Keyset pagination: ?after=cursor_value
- *
- * **NOTE on parser portability.** `ArcQueryParser` accepts both filter
- * forms. Other parser implementations (`@classytic/mongokit`'s
- * `QueryParser`, custom hosts-side parsers) may accept only one form —
- * MongoKit historically only accepts the bare form. If your host swaps
- * `queryParser` to a different implementation, double-check which forms
- * it understands before publishing URLs that mix the two.
- *
- * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+ * Arc's default query parser:
+ * - Paging `?page=1&limit=20`, keyset `?after=cursor`; sort `?sort=-createdAt,name`
+ * - Filters bare (`?status=active&price[gte]=100`) or in the `?filter[...]` envelope, which
+ *   avoids collisions with reserved keys (`page`, `sort`, ...)
+ * - Search `?search=`, populate `?populate=a,b`, select `?select=a,-b`
  */
-declare class ArcQueryParser implements QueryParserInterface {
+export declare class ArcQueryParser implements QueryParserInterface {
   /**
-   * PUBLIC, deliberately: `QueryResolver` reads it so it does not apply a second cap
-   * on top of this one. Three layers capping independently, lowest winning silently,
-   * is what made a 696-row chart of accounts render as 100.
+   * Public so `QueryResolver` reuses this cap instead of stacking its own
+   * (independent caps silently truncate to the lowest).
    */
   readonly maxLimit: number;
   private readonly defaultLimit;
   private readonly maxRegexLength;
   private readonly maxSearchLength;
-  private readonly maxFilterDepth;
-  private readonly _allowedFilterFields?;
-  private readonly _allowedSortFields?;
-  private readonly _allowedOperators?;
-  private readonly strictFilterFields;
+  private readonly strict;
+  private readonly dialect;
   /** Allowed filter fields (used by MCP for auto-derive) */
   readonly allowedFilterFields?: readonly string[];
   /** Allowed sort fields (used by MCP for sort descriptions) */
   readonly allowedSortFields?: readonly string[];
   /** Allowed operators (used by MCP for operator descriptions) */
   readonly allowedOperators?: readonly string[];
-  /**
-   * Datastore dialect — owns the store-specific operator tokens + the
-   * case-insensitive modifier. Defaults to Mongo (backward-compatible).
-   */
-  private readonly dialect;
-  /** Supported filter operators (neutral name → emitted token), from the dialect. */
-  private get operators();
   constructor(options?: ArcQueryParserOptions);
-  /**
-   * Parse URL query parameters into structured query options
-   */
+  /** Parse URL query parameters into structured query options. Invalid input is a 400. */
   parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
-  private parseNumber;
-  private parseString;
+  /** A grammar refusal is a 400 (`ValidationError`) — unless lenient and only an allowlist miss. */
+  private read;
+  private drop;
   /**
-   * Parse populate parameter — handles both simple string and bracket notation.
-   *
-   * Simple: ?populate=author,category → { populate: 'author,category' }
-   * Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
+   * Simple `?populate=author,category`, or bracket `?populate[author][select]=name,email` and
+   * `?populate[author][match][field]=value` (field equality only).
    */
   private parsePopulate;
-  private parseSort;
-  private parseSearch;
-  private parseSelect;
   /**
-   * Check if a value exceeds the maximum nesting depth.
-   * Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
-   */
-  private exceedsDepth;
-  /**
-   * Parse all filter entries from the query, supporting BOTH the bare
-   * top-level form and the bracket-wrapped `filter[...]` envelope.
-   *
-   * Two equivalent ways to express the same query:
-   *   - Bare (legacy, arc default): `?status=active&price[gte]=40`
-   *   - Bracket envelope (REST convention): `?filter[status]=active&filter[price][gte]=40`
-   *
-   * Both forms parse to the same `filters: { status: 'active', price: { $gte: 40 } }`.
-   * The envelope form mirrors the convention used by most REST API style
-   * guides (JSON:API, Stripe API, etc.) and disambiguates filter fields
-   * from reserved meta params on busy URLs — a query string with a field
-   * literally named `page` or `sort` can't collide with the framework's
-   * meta keys when wrapped under `filter[...]`. The bare form stays as
-   * the default since it's the shortest path for simple queries; expect
-   * it to remain supported indefinitely.
-   *
-   * Precedence when the same key appears in both forms:
-   *   `?status=closed&filter[status]=active` → bare wins (`status: closed`).
-   * Mixing should be rare; the deterministic rule avoids silent surprises.
-   */
-  private parseFilters;
-  /**
-   * Apply one filter entry — used by both the bracket-envelope branch and
-   * the bare top-level branch of `parseFilters`. Centralising the field-
-   * validation + operator-conversion logic keeps the two forms in
-   * lockstep; a future regex/security tweak only changes one place.
-   */
-  private applyFilterEntry;
-  private parseFilterValue;
-  private coerceValue;
-  /**
-   * Generate OpenAPI-compatible JSON Schema for query parameters.
-   * Arc's defineResource() auto-detects this method and uses it
-   * to document list endpoint query parameters in OpenAPI/Swagger.
+   * A populate `match` is plain field EQUALITY in bracket form (`populate[p][match][f]=v`). A `$`
+   * key, a nested object or a non-object `match` (a JSON string) is refused, never passed to the
+   * driver or dropped — a dropped match populates every document.
    */
+  private parsePopulateMatch;
+  /** JSON Schema for list query parameters (auto-detected by `defineResource`). */
   getQuerySchema(): {
     type: "object";
     properties: Record<string, unknown>;
     required?: string[];
   };
-  private sanitizeRegex;
 }
-/**
- * Create a new ArcQueryParser instance
- */
-declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryParser;
+/** Create a new ArcQueryParser instance. */
+export declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryParser;
 //#endregion
 //#region src/utils/responseSchemas.d.ts
 interface JsonSchema {
@@ -773,7 +624,7 @@ interface JsonSchema {
  * Runtime format (flat fields):
  * { page, limit, total, pages, hasNext, hasPrev }
  */
-declare const paginationSchema: JsonSchema;
+export declare const paginationSchema: JsonSchema;
 /**
  * List response schema — accepts every wire shape `toCanonicalList` can
  * emit. Hosts who know their endpoint only ever produces one variant can
@@ -795,18 +646,18 @@ declare const paginationSchema: JsonSchema;
  * per-response branch validation. The list route also serves count, exists
  * and distinct dispatch verbs, so no field is common to every valid shape.
  */
-declare function listResponse(itemSchema: JsonSchema): JsonSchema;
+export declare function listResponse(itemSchema: JsonSchema): JsonSchema;
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
-declare function offsetListResponse(itemSchema: JsonSchema): JsonSchema;
+export declare function offsetListResponse(itemSchema: JsonSchema): JsonSchema;
 /** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
-declare function keysetListResponse(itemSchema: JsonSchema): JsonSchema;
+export declare function keysetListResponse(itemSchema: JsonSchema): JsonSchema;
 /** Aggregate variant — same shape as offset, discriminated by `method: 'aggregate'`. */
-declare function aggregateListResponse(itemSchema: JsonSchema): JsonSchema;
+export declare function aggregateListResponse(itemSchema: JsonSchema): JsonSchema;
 /** Bare variant — `{ data }`, no `method` discriminant. */
-declare function bareListResponse(itemSchema: JsonSchema): JsonSchema;
+export declare function bareListResponse(itemSchema: JsonSchema): JsonSchema;
 /** Delete response — flat shape mirroring the canonical delete envelope. */
-declare function deleteResponse(): JsonSchema;
-declare const responses: {
+export declare function deleteResponse(): JsonSchema;
+export declare const responses: {
   200: (schema: JsonSchema) => {
     description: string;
     content: {
@@ -1182,7 +1033,7 @@ declare const responses: {
     };
   };
 };
-declare const queryParams: {
+export declare const queryParams: {
   pagination: {
     page: {
       type: string;
@@ -1219,21 +1070,19 @@ declare const queryParams: {
 /**
  * Get standard list query parameters schema
  */
-declare function getListQueryParams(): AnyRecord;
+export declare function getListQueryParams(): AnyRecord;
 /**
  * Get default response schemas for all CRUD operations.
  *
- * When routes have response schemas, Fastify compiles them with
- * fast-json-stringify for 2-3x faster serialization and prevents
- * accidental field disclosure.
- *
- * These defaults use `additionalProperties: true` so all fields pass through.
- * Override with specific schemas for full serialization performance + safety.
+ * The envelope is typed (its fields are known); rows and single documents
+ * pass through as `{}` — see `genericItemSchema`. A resource that declares a
+ * response schema with real `properties` gets typed row serialization, which
+ * also drops undeclared fields.
  *
  * Note: `example` properties are stripped from defaults so they work with
  * any Fastify instance (not just createApp which adds `keywords: ['example']`).
  */
-declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
+export declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
 //#endregion
 //#region src/utils/runtimeCapabilities.d.ts
 /** What a subsystem declares about the state it holds. */
@@ -1257,7 +1106,7 @@ interface RuntimeCapabilityDeclaration {
  * and encapsulated children of any of them — which is the point: the audit
  * sees what the constructor-time guard cannot.
  */
-declare function declareRuntimeCapability(fastify: FastifyInstance, decl: RuntimeCapabilityDeclaration): void;
+export declare function declareRuntimeCapability(fastify: FastifyInstance, decl: RuntimeCapabilityDeclaration): void;
 //#endregion
 //#region src/utils/schemaConverter.d.ts
 /**
@@ -1278,11 +1127,11 @@ type SchemaIo = "input" | "output";
  * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
  * `allOf`, `anyOf`, `oneOf`, `items`, `enum`) and does NOT have Zod markers.
  */
-declare function isJsonSchema(input: unknown): input is Record<string, unknown>;
+export 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;
+export 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):
@@ -1316,7 +1165,7 @@ type UnconvertibleMode = "warn" | "throw";
  *               docblock. Defaults to `'output'`, matching Zod's own default;
  *               arc's request-side call sites pass `'input'` explicitly.
  */
-declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode, io?: SchemaIo): Record<string, unknown> | undefined;
+export declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode, io?: SchemaIo): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
@@ -1324,7 +1173,7 @@ declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?:
  * Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
  * generation, not Fastify route validation.
  */
-declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSchemaTarget): OpenApiSchemas;
+export declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSchemaTarget): OpenApiSchemas;
 /**
  * Convert schema values in a Fastify route schema record.
  *
@@ -1338,7 +1187,19 @@ declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSch
  * Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
  * Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
  */
-declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
+export declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
+//#endregion
+//#region src/utils/shutdown.d.ts
+interface ShutdownParticipant {
+  readonly name: string;
+  readonly kind?: "producer" | "consumer";
+  stop?(): void | Promise<void>;
+  drain?(): void | Promise<void>;
+}
+/** Descendants of admitted work may finish their causal publications during shutdown. */
+export declare function runAdmittedWork<T>(work: () => T | Promise<T>): Promise<T>;
+/** A participant's stop must prevent new work; drain waits for work already admitted. */
+export declare function registerShutdownParticipant(fastify: FastifyInstance, participant: ShutdownParticipant): void;
 //#endregion
 //#region src/utils/simpleEqualityMatcher.d.ts
 /**
@@ -1365,7 +1226,7 @@ declare function convertRouteSchema(schema: Record<string, unknown>, target?: Js
  *                                matchesFilter: simpleEqualityMatcher };
  * ```
  */
-declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
+export declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
 //#endregion
 //#region src/utils/sseStream.d.ts
 interface SseStreamOptions {
@@ -1397,7 +1258,7 @@ interface SseStream {
  * gate (auth, permissions, validation) has passed — after `hijack()` no
  * JSON error can be sent.
  */
-declare function openSseStream(request: FastifyRequest, reply: FastifyReply, options?: SseStreamOptions): SseStream;
+export declare function openSseStream(request: FastifyRequest, reply: FastifyReply, options?: SseStreamOptions): SseStream;
 //#endregion
 //#region src/utils/stateMachine.d.ts
 /**
@@ -1508,7 +1369,7 @@ type TransitionConfig = Record<string, string[] | {
  *   },
  * }, { trackHistory: true });
  */
-declare function createStateMachine(name: string, transitions?: TransitionConfig, options?: {
+export declare function createStateMachine(name: string, transitions?: TransitionConfig, options?: {
   trackHistory?: boolean;
 }): StateMachine;
 //#endregion
@@ -1520,7 +1381,7 @@ declare function createStateMachine(name: string, transitions?: TransitionConfig
  * client uses to detect the v1 UI message stream protocol (vs the older
  * data stream protocol). Surfaced as a constant so hosts don't memorise it.
  */
-declare const UI_MESSAGE_STREAM_HEADERS: {
+export declare const UI_MESSAGE_STREAM_HEADERS: {
   readonly "content-type": "text/event-stream";
   readonly "cache-control": "no-cache";
   readonly connection: "keep-alive";
@@ -1577,7 +1438,7 @@ interface PipeUIMessageStreamOptions {
  * });
  * ```
  */
-declare function pipeUIMessageStreamToReply(reply: FastifyReply, stream: ReadableStream<unknown>, options?: PipeUIMessageStreamOptions): Promise<void>;
+export declare function pipeUIMessageStreamToReply(reply: FastifyReply, stream: ReadableStream<unknown>, options?: PipeUIMessageStreamOptions): Promise<void>;
 /**
  * Promote a stream auth token from the query string into the `Authorization`
  * header, in place, so the standard `fastify.authenticate` decorator can read it.
@@ -1601,7 +1462,7 @@ declare function pipeUIMessageStreamToReply(reply: FastifyReply, stream: Readabl
  *
  * @param queryParam name of the query parameter carrying the token (default `token`).
  */
-declare function promoteStreamTokenToHeader(request: FastifyRequest, queryParam?: string): void;
+export declare function promoteStreamTokenToHeader(request: FastifyRequest, queryParam?: string): void;
 /**
  * Collect the CORS / `Vary` headers a plugin (e.g. `@fastify/cors`, whose default
  * `onRequest` hook runs BEFORE the route handler) has already set on the reply, so
@@ -1615,7 +1476,7 @@ declare function promoteStreamTokenToHeader(request: FastifyRequest, queryParam?
  * honors the host's configured policy (origin allowlist, credentials) rather than
  * re-deriving it. Returns lowercased header names suitable for `writeHead`.
  */
-declare function forwardedStreamHeaders(reply: FastifyReply): Record<string, string>;
+export declare function forwardedStreamHeaders(reply: FastifyReply): Record<string, string>;
 /**
  * Heuristic — does this value look like a Web `ReadableStream`?
  *
@@ -1625,7 +1486,7 @@ declare function forwardedStreamHeaders(reply: FastifyReply): Record<string, str
  * the Streams spec mandates: `getReader`, `cancel`, and the `locked`
  * getter.
  */
-declare function isReadableStream(value: unknown): value is ReadableStream<unknown>;
+export declare function isReadableStream(value: unknown): value is ReadableStream<unknown>;
 //#endregion
 //#region src/utils/typeGuards.d.ts
 interface EventsDecorator {
@@ -1638,8 +1499,8 @@ interface EventsDecorator {
   transportName: string;
 }
 /** Check if fastify has the events plugin registered */
-declare function hasEvents(instance: FastifyInstance): instance is FastifyInstance & {
+export declare function hasEvents(instance: FastifyInstance): instance is FastifyInstance & {
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, type CircuitBreakerRedisLike, CircuitBreakerRegistry, type CircuitBreakerSharedState, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, 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, RedisCircuitBreakerState, type RedisCircuitBreakerStateOptions, type RuntimeCapabilityDeclaration, type SchemaIo, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, declareRuntimeCapability, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };
+export { type AnyAsyncFn, ArcError, type ArcHeaders, type ArcQueryParserOptions, type CircuitBreakerOptions, type CircuitBreakerRedisLike, type CircuitBreakerSharedState, type CircuitBreakerStats, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, type RedisCircuitBreakerStateOptions, type RuntimeCapabilityDeclaration, type SchemaIo, ServiceUnavailableError, type ShutdownParticipant, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UnauthorizedError, type UnconvertibleMode, ValidationError, createDomainError, createError, errorContractSchema, getHeader, getUserId, getUserRoles, isArcError, normalizeRoles, requireSingleHeaderValue };