@classytic/arc 2.38.0 → 2.41.0

package/dist/{types-LQFwC37d.d.mts → types-CWQn9-IC.d.mts}

@@ -1,5 +1,5 @@
 
-import { V as ResourceDefinition } from "./index-B78WZom8.mjs";
+import { V as ResourceDefinition } from "./index-DHbyPo5j.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -275,6 +275,51 @@ interface McpPluginOptions {
    * - `McpAuthResolver` — custom function that resolves identity from headers
    */
   auth?: BetterAuthHandler | McpAuthResolver | false;
+  /**
+   * DNS-rebinding protection for the MCP routes — `Host` / `Origin` validation.
+   *
+   * The attack this closes: a page the developer visits can POST to
+   * `127.0.0.1:<port>`. If a DNS name the attacker controls resolves to
+   * loopback, the browser treats the response as same-origin and the page can
+   * READ it — every registered tool, from any website. Validating that `Host`
+   * names a host you expect is what breaks it, which is why the MCP SDK ships
+   * this as a default for localhost servers.
+   *
+   * **Default: on when `auth: false`, off otherwise.** Not a guess — it follows
+   * the threat:
+   * - `auth: false` is the local/dev shape the attack targets, and nothing else
+   *   is standing in the way. Defaults to the SDK's localhost set
+   *   (`localhost`, `127.0.0.1`, `[::1]`).
+   * - With auth configured, the endpoint is normally a real domain whose `Host`
+   *   is not localhost — defaulting protection ON would 403 every production
+   *   deployment. There, credentials are the gate.
+   *
+   * Set explicitly whenever the default's assumption is wrong for you: a
+   * localhost server that DOES use auth, or a deliberately-public `auth: false`
+   * endpoint that must keep answering (`false` to disable).
+   *
+   * Validation itself is `@modelcontextprotocol/server`'s `validateHostHeader` /
+   * `validateOriginHeader` — arc does not reimplement the matching rules.
+   * Hostnames only, no scheme or port; IPv6 in brackets (`[::1]`). A request
+   * with no `Origin` header passes (non-browser MCP clients send none); a
+   * present-but-unlisted `Origin` is rejected.
+   *
+   * @example
+   * ```ts
+   * // localhost server that uses auth — opt in explicitly
+   * mcpPlugin({ resources, auth, dnsRebindingProtection: {} });
+   * // reachable under a known public name
+   * mcpPlugin({ resources, dnsRebindingProtection: { allowedHosts: ['mcp.example.com'] } });
+   * // deliberately public, no Host constraint
+   * mcpPlugin({ resources, auth: false, dnsRebindingProtection: false });
+   * ```
+   */
+  dnsRebindingProtection?: false | {
+    /** Allowed `Host` hostnames. Default: `localhost`, `127.0.0.1`, `[::1]`. */
+    allowedHosts?: string[];
+    /** Allowed `Origin` hostnames. Default: same localhost set. */
+    allowedOrigins?: string[];
+  };
   /** MCP endpoint path (default: '/mcp') */
   prefix?: string;
   /** Server identity */

package/dist/{types-BRU-Kd3t.d.mts → types-DfVDvkdP.d.mts}

@@ -1,6 +1,6 @@
 
-import { n as DomainEvent, r as EventHandler } from "./EventTransport-Cx60_s-6.mjs";
-import { n as ErrorMapper } from "./errorHandler-DI5AN2b5.mjs";
+import { n as DomainEvent, r as EventHandler } from "./EventTransport-CbUKDzZZ.mjs";
+import { n as ErrorMapper } from "./errorHandler--4rSMMvq.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import { LockAdapter } from "@classytic/repo-core/lock";
 //#region src/plugins/health.d.ts
@@ -90,6 +90,24 @@ interface SchedulesPluginOptions {
    * environments), same pattern as `idempotencyPlugin`.
    */
   enabled?: boolean;
+  /**
+   * States that exactly ONE replica of this deployment arms schedules, so no
+   * lock is needed. Same idiom as `eventPlugin, { singleProcess: true }`.
+   *
+   * Under `runtime: 'distributed'`, schedules with neither `lock` nor this
+   * flag FAIL the boot. Without one of them arc cannot tell a deliberately
+   * single-armed deployment — the `role: 'scheduler'` process pinned to one
+   * replica, which is the recommended topology — from the accidental default,
+   * where every replica in a fleet fires every tick. The accidental case is
+   * duplicate side effects: two invoices, two dunning emails, two charges.
+   * That is a worse failure than the replica-local stores arc already refuses
+   * to boot on, so it is held to the same standard rather than warned about.
+   *
+   * Set it only when the replica count for the process that arms schedules is
+   * genuinely one. It is a claim about your deployment, not a silencer — if
+   * you scale that deployment past one replica, remove it and pass a `lock`.
+   */
+  singleReplica?: boolean;
   /**
    * How long `onClose` waits for in-flight runs before abandoning them.
    * Default: 5000.

package/dist/usage/index.d.mts

@@ -1,6 +1,6 @@
 
 import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
-import { l as PermissionCheck, u as PermissionContext } from "../base-C-NL2fTi.mjs";
+import { l as PermissionCheck, u as PermissionContext } from "../base-CxrV1LmG.mjs";
 import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts
@@ -40,6 +40,62 @@ declare class MemoryUsageStore implements UsageStore {
   clear(): void;
 }
 //#endregion
+//#region src/usage/stores/redis.d.ts
+/**
+ * The three commands this store needs. Fixed arity with an `unknown[]` tail
+ * where ioredis overloads one — see the note in `idempotency/stores/redis.ts`
+ * for why a narrower tail makes a real `Redis` unassignable.
+ */
+interface UsageRedisLike {
+  hincrby(key: string, field: string, increment: number): Promise<number>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  expire(key: string, seconds: number, ...args: unknown[]): Promise<number>;
+  /**
+   * Optional. When present, a retention-enabled increment sends `HINCRBY` and
+   * `EXPIRE` as ONE round trip instead of two. ioredis has it; a minimal
+   * wrapper may not, and the store falls back to two sequential calls.
+   */
+  pipeline?(): {
+    hincrby(key: string, field: string, increment: number): unknown;
+    expire(key: string, seconds: number): unknown;
+    exec(): Promise<unknown>;
+  };
+}
+interface RedisUsageStoreOptions {
+  /** Redis client (ioredis or compatible). */
+  redis: UsageRedisLike;
+  /**
+   * Key prefix (default: `'arc:usage:'`).
+   *
+   * Keys are `{prefix}{actor}:{period}`. `usagePeriod()` never emits a `:`,
+   * so the split is unambiguous for every canonical period; a host that
+   * passes its own period key should keep `:` out of it.
+   */
+  prefix?: string;
+  /**
+   * Seconds a bucket survives after its LAST write, or `undefined` (the
+   * default) to keep counters forever.
+   *
+   * The default is deliberate and it is not the usual Redis default. These
+   * counters are what quota decisions and invoices are computed from —
+   * expiring them by default would delete billing history on a schedule
+   * nobody chose, and the loss is silent because `summary()` answers `{}` for
+   * a bucket that never existed and one that expired alike. Set it once you
+   * know your retention window (e.g. `86400 * 400` to keep a year plus a
+   * grace period), and only if the counters here are not your system of
+   * record.
+   */
+  retentionSeconds?: number;
+}
+/** Period-bucketed usage counters in Redis hashes. See the module header. */
+declare class RedisUsageStore implements UsageStore {
+  #private;
+  readonly name = "redis";
+  constructor(options: RedisUsageStoreOptions);
+  increment(bucket: UsageBucket, amount: number): Promise<void>;
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+}
+//#endregion
 //#region src/usage/usagePlugin.d.ts
 interface UsageTrackOptions {
   /** Count every completed request as `api.requests` (default: true). */
@@ -91,4 +147,4 @@ declare module "fastify" {
 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 };
+export { MemoryUsageStore, type QuotaOptions, RedisUsageStore, type RedisUsageStoreOptions, type UsageBucket, type UsageMeter, type UsagePluginOptions, type UsageRedisLike, type UsageStore, type UsageTrackOptions, _default as default, requireQuota, usagePeriod, usagePluginFn as usagePlugin };

package/dist/{userHelpers-CXySQFRg.mjs → userHelpers-DDMOZ_Pm.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
 //#region src/utils/userHelpers.ts
 /**
 * Extract a user ID from a user object. Accepts `id` or `_id` — returns

package/dist/utils/index.d.mts

@@ -1,8 +1,8 @@
 
 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-C-NL2fTi.mjs";
-import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-B78WZom8.mjs";
-import { n as ErrorMapper } from "../errorHandler-DI5AN2b5.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 { 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";
@@ -54,6 +54,53 @@ type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
  * Promise<any>` would silently disable type checking everywhere `T` flows.
  */
 type AnyAsyncFn = (...args: never[]) => Promise<unknown>;
+/**
+ * Cluster-wide failure counting for a circuit.
+ *
+ * ## What this shares, and what it deliberately does not
+ *
+ * It shares the failure SIGNAL, not the state machine. Each replica still owns
+ * its own CLOSED/OPEN/HALF_OPEN transitions and its own probe scheduling; what
+ * becomes cluster-wide is the count that decides when to trip.
+ *
+ * That is the whole of the problem worth solving. Per-replica counting means a
+ * downstream outage costs `failureThreshold × replicas` real requests before
+ * anything opens — at 5 and 50 that is 250 errors a failing payment gateway
+ * absorbs while every pod independently rediscovers the same outage. Sharing
+ * the count collapses it: the first replica trips at the threshold, and every
+ * other replica trips on its NEXT failure, because the shared window is
+ * already over the line.
+ *
+ * Sharing the full state machine instead would mean electing which replica
+ * probes in HALF_OPEN — consensus, plus a lock, plus a read on the hot path.
+ * The remaining gap without it is bounded and small: one extra failure per
+ * replica, once, versus `failureThreshold` per replica every time.
+ *
+ * ## Cost
+ *
+ * ONLY the failure path calls this. A successful call never touches the
+ * network, which matters because success is the common case and this wraps
+ * things like a payment charge. `reset` is called when a circuit closes.
+ *
+ * ## Failure of the store itself
+ *
+ * Never propagates. If the shared counter is unreachable the breaker falls
+ * back to its local count — degraded to the old behaviour, which is the
+ * correct direction: a Redis blip must not disable the protection that exists
+ * for a downstream outage, and the two often arrive together.
+ */
+interface CircuitBreakerSharedState {
+  /** Store name for diagnostics. */
+  readonly name: string;
+  /**
+   * Record one failure for `circuit` and return the CLUSTER-wide count within
+   * the current window. Implementations expire the window so a long-ago
+   * outage does not trip a healthy circuit.
+   */
+  recordFailure(circuit: string): Promise<number>;
+  /** Clear the window — called when this replica closes the circuit. */
+  reset(circuit: string): Promise<void>;
+}
 interface CircuitBreakerOptions {
   /**
    * Number of failures before opening circuit
@@ -117,6 +164,19 @@ interface CircuitBreakerOptions {
    * Name for logging/monitoring
    */
   name?: string;
+  /**
+   * Cluster-wide failure counting — see {@link CircuitBreakerSharedState}.
+   *
+   * Omit for a single process, where the local count already IS the cluster
+   * count. Under a multi-replica deployment this is what stops every replica
+   * absorbing the full threshold before anything trips.
+   *
+   * Requires a stable {@link CircuitBreakerOptions.name}: it is the key every
+   * replica must agree on. A breaker with `sharedState` and no `name` throws
+   * at construction rather than silently counting under a generated id that no
+   * other replica shares.
+   */
+  sharedState?: CircuitBreakerSharedState;
 }
 interface CircuitBreakerStats {
   name?: string;
@@ -150,6 +210,7 @@ declare class CircuitBreaker<T extends AnyAsyncFn> {
   private readonly onStateChange?;
   private readonly onError?;
   private readonly name;
+  private readonly sharedState?;
   private readonly fn;
   constructor(fn: T, options?: CircuitBreakerOptions);
   /**
@@ -171,6 +232,10 @@ declare class CircuitBreaker<T extends AnyAsyncFn> {
    * Handle failed call
    */
   private onFailure;
+  /** Open the circuit and schedule the next probe. */
+  private trip;
+  /** Best-effort clear of the cluster failure window. Never throws. */
+  private clearSharedWindow;
   /**
    * Change circuit state
    */
@@ -254,6 +319,42 @@ declare class CircuitBreakerRegistry {
  */
 declare function createCircuitBreakerRegistry(): CircuitBreakerRegistry;
 //#endregion
+//#region src/utils/circuitBreakerRedis.d.ts
+/**
+ * The two commands this needs. Variadic tail is `unknown[]` for the same
+ * reason as every other `*Like` shape in arc — ioredis types its commands as
+ * overloads mixing literal tokens and an optional callback, which a narrower
+ * tail matches none of. Pinned by `tests/types/ioredis-assignability.test.ts`.
+ */
+interface CircuitBreakerRedisLike {
+  incr(key: string): Promise<number>;
+  pexpire(key: string, milliseconds: number, ...args: unknown[]): Promise<number>;
+  del(...keys: string[]): Promise<number>;
+}
+interface RedisCircuitBreakerStateOptions {
+  /** Redis client (ioredis or compatible). */
+  redis: CircuitBreakerRedisLike;
+  /**
+   * Key prefix (default: `'arc:circuit:'`). Keys are `{prefix}{circuitName}`,
+   * so the circuit's `name` is what every replica must agree on.
+   */
+  prefix?: string;
+  /**
+   * Counting window in ms (default: `60_000`, matching the breaker's default
+   * `resetTimeout`). The period over which `failureThreshold` failures mean
+   * the downstream is down.
+   */
+  windowMs?: number;
+}
+/** Fixed-window cluster failure counter. See the module header. */
+declare class RedisCircuitBreakerState implements CircuitBreakerSharedState {
+  #private;
+  readonly name = "redis";
+  constructor(options: RedisCircuitBreakerStateOptions);
+  recordFailure(circuit: string): Promise<number>;
+  reset(circuit: string): Promise<void>;
+}
+//#endregion
 //#region src/utils/compensation.d.ts
 /**
  * Compensating Transaction — In-Process Rollback Primitive
@@ -691,8 +792,8 @@ declare const paginationSchema: JsonSchema;
  * 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.
+ * 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;
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
@@ -1152,8 +1253,9 @@ interface RuntimeCapabilityDeclaration {
 }
 /**
  * Declare a runtime capability. Callable from ANY registration context —
- * arc's own plugins, host `plugins()` callbacks, module `plugins` phases —
- * which is the point: the audit sees what the constructor-time guard cannot.
+ * arc's own plugins, host `plugins()` callbacks, module `plugins` phases,
+ * 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;
 //#endregion
@@ -1540,4 +1642,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-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, 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, 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 { 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 };

package/dist/utils/index.mjs

@@ -1,12 +1,12 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-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-2ExmOgIJ.mjs";
-import { n as requireSingleHeaderValue, t as getHeader } from "../headers-DeXNifVj.mjs";
-import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-CXySQFRg.mjs";
-import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-B7qVjQBv.mjs";
-import { A as scheduleBackground, C as paginationSchema, D as createQueryParser, E as ArcQueryParser, O as MONGO_DIALECT, S as offsetListResponse, T as responses, _ as errorDetailSchema, a as defineCompensation, b as keysetListResponse, c as CircuitBreakerError, d as createCircuitBreaker, f as createCircuitBreakerRegistry, g as errorContractSchema, h as deleteResponse, i as defineErrorMapper, k as NEUTRAL_DIALECT, l as CircuitBreakerRegistry, m as bareListResponse, n as handleRaw, o as withCompensation, p as aggregateListResponse, r as defineGuard, s as CircuitBreaker, t as createStateMachine, u as CircuitState, v as getDefaultCrudSchemas, w as queryParams, x as listResponse, y as getListQueryParams } from "../utils-BbGG8XNT.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Db-MMsH6.mjs";
-import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-DkpW1HwJ.mjs";
-import { n as declareRuntimeCapability } from "../runtimeCapabilities-D793Pxci.mjs";
-import { t as openSseStream } from "../sseStream-BuMNPR6r.mjs";
-import { t as hasEvents } from "../typeGuards-DHTnEs5X.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, 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 };
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+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-C_YhELhe.mjs";
+import { n as requireSingleHeaderValue, t as getHeader } from "../headers-CNECDE6q.mjs";
+import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-DDMOZ_Pm.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-BiOnyflP.mjs";
+import { A as NEUTRAL_DIALECT, C as offsetListResponse, D as ArcQueryParser, E as responses, O as createQueryParser, S as listResponse, T as queryParams, _ as errorContractSchema, a as defineCompensation, b as getListQueryParams, c as CircuitBreaker, d as CircuitState, f as createCircuitBreaker, g as deleteResponse, h as bareListResponse, i as defineErrorMapper, j as scheduleBackground, k as MONGO_DIALECT, l as CircuitBreakerError, m as aggregateListResponse, n as handleRaw, o as withCompensation, p as createCircuitBreakerRegistry, r as defineGuard, s as RedisCircuitBreakerState, t as createStateMachine, u as CircuitBreakerRegistry, v as errorDetailSchema, w as paginationSchema, x as keysetListResponse, y as getDefaultCrudSchemas } from "../utils-B-zj_b__.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-BLCSmNbr.mjs";
+import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-dvppnxsr.mjs";
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-DSA_dH1_.mjs";
+import { t as openSseStream } from "../sseStream-CN-Lh1Tu.mjs";
+import { t as hasEvents } from "../typeGuards-D7tHFdH6.mjs";
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, RedisCircuitBreakerState, ServiceUnavailableError, 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 };

package/dist/{utils-BbGG8XNT.mjs → utils-B-zj_b__.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { m as RESERVED_QUERY_PARAMS } from "./constants-BONghE1Y.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { m as RESERVED_QUERY_PARAMS } from "./constants-BxLgNFF7.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError, u as ValidationError } from "./errors-2ExmOgIJ.mjs";
+import { t as ArcError, u as ValidationError } from "./errors-C_YhELhe.mjs";
 import { scheduleBackground } from "@classytic/repo-core/cache";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 //#region src/utils/filter-dialect.ts
@@ -561,8 +561,8 @@ const paginationSchema = {
 * 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.
+* per-response branch validation. The list route also serves count, exists
+* and distinct dispatch verbs, so no field is common to every valid shape.
 */
 function listResponse(itemSchema) {
 	return {
@@ -577,6 +577,15 @@ function listResponse(itemSchema) {
 				type: "array",
 				items: itemSchema
 			},
+			count: {
+				type: "integer",
+				minimum: 0
+			},
+			exists: { type: "boolean" },
+			values: {
+				type: "array",
+				items: {}
+			},
 			page: {
 				type: "integer",
 				example: 1
@@ -607,7 +616,6 @@ function listResponse(itemSchema) {
 				description: "Cursor token for the next page, or null."
 			}
 		},
-		required: ["data"],
 		additionalProperties: true
 	};
 }
@@ -963,9 +971,12 @@ var CircuitBreaker = class {
 	onStateChange;
 	onError;
 	name;
+	sharedState;
 	fn;
 	constructor(fn, options = {}) {
 		this.fn = fn;
+		if (options.sharedState && !options.name) throw new Error("[arc] CircuitBreaker: `sharedState` requires an explicit `name` — it is the key every replica counts under. Without it each replica would count under its own key.");
+		this.sharedState = options.sharedState;
 		this.failureThreshold = options.failureThreshold ?? 5;
 		this.resetTimeout = options.resetTimeout ?? 6e4;
 		this.timeout = options.timeout ?? 1e4;
@@ -1043,6 +1054,7 @@ var CircuitBreaker = class {
 			if (this.successes >= this.successThreshold) {
 				this.setState(CircuitState.CLOSED);
 				this.successes = 0;
+				this.clearSharedWindow();
 			}
 		}
 	}
@@ -1053,11 +1065,23 @@ var CircuitBreaker = class {
 		this.failures++;
 		this.successes = 0;
 		if (this.onError) this.onError(error);
-		if (this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold) {
-			this.setState(CircuitState.OPEN);
-			this.nextAttempt = Date.now() + this.resetTimeout;
-			this.openedAt = Date.now();
-		}
+		const trippedLocally = this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold;
+		if (trippedLocally) this.trip();
+		if (!this.sharedState) return;
+		this.sharedState.recordFailure(this.name).then((clusterFailures) => {
+			if (!trippedLocally && this.state === CircuitState.CLOSED && clusterFailures >= this.failureThreshold) this.trip();
+		}).catch(() => {});
+	}
+	/** Open the circuit and schedule the next probe. */
+	trip() {
+		this.setState(CircuitState.OPEN);
+		this.nextAttempt = Date.now() + this.resetTimeout;
+		this.openedAt = Date.now();
+	}
+	/** Best-effort clear of the cluster failure window. Never throws. */
+	clearSharedWindow() {
+		if (!this.sharedState) return;
+		this.sharedState.reset(this.name).catch(() => {});
 	}
 	/**
 	* Change circuit state
@@ -1205,6 +1229,31 @@ function createCircuitBreakerRegistry() {
 	return new CircuitBreakerRegistry();
 }
 //#endregion
+//#region src/utils/circuitBreakerRedis.ts
+/** Fixed-window cluster failure counter. See the module header. */
+var RedisCircuitBreakerState = class {
+	name = "redis";
+	#redis;
+	#prefix;
+	#windowMs;
+	constructor(options) {
+		this.#redis = options.redis;
+		this.#prefix = options.prefix ?? "arc:circuit:";
+		const windowMs = options.windowMs ?? 6e4;
+		if (!Number.isFinite(windowMs) || windowMs <= 0) throw new Error(`[arc] RedisCircuitBreakerState: windowMs must be a positive number, got ${String(options.windowMs)}.`);
+		this.#windowMs = windowMs;
+	}
+	async recordFailure(circuit) {
+		const key = this.#prefix + circuit;
+		const count = await this.#redis.incr(key);
+		if (count === 1) await this.#redis.pexpire(key, this.#windowMs);
+		return count;
+	}
+	async reset(circuit) {
+		await this.#redis.del(this.#prefix + circuit);
+	}
+};
+//#endregion
 //#region src/utils/compensation.ts
 /**
 * Observability hooks must never alter the transaction: a throwing metrics
@@ -1472,4 +1521,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-export { scheduleBackground as A, paginationSchema as C, createQueryParser as D, ArcQueryParser as E, MONGO_DIALECT as O, offsetListResponse as S, responses as T, errorDetailSchema$1 as _, defineCompensation as a, keysetListResponse as b, CircuitBreakerError as c, createCircuitBreaker as d, createCircuitBreakerRegistry as f, errorContractSchema$1 as g, deleteResponse as h, defineErrorMapper as i, NEUTRAL_DIALECT as k, CircuitBreakerRegistry as l, bareListResponse as m, handleRaw as n, withCompensation as o, aggregateListResponse as p, defineGuard as r, CircuitBreaker as s, createStateMachine as t, CircuitState as u, getDefaultCrudSchemas as v, queryParams as w, listResponse as x, getListQueryParams as y };
+export { NEUTRAL_DIALECT as A, offsetListResponse as C, ArcQueryParser as D, responses as E, createQueryParser as O, listResponse as S, queryParams as T, errorContractSchema$1 as _, defineCompensation as a, getListQueryParams as b, CircuitBreaker as c, CircuitState as d, createCircuitBreaker as f, deleteResponse as g, bareListResponse as h, defineErrorMapper as i, scheduleBackground as j, MONGO_DIALECT as k, CircuitBreakerError as l, aggregateListResponse as m, handleRaw as n, withCompensation as o, createCircuitBreakerRegistry as p, defineGuard as r, RedisCircuitBreakerState as s, createStateMachine as t, CircuitBreakerRegistry as u, errorDetailSchema$1 as v, paginationSchema as w, keysetListResponse as x, getDefaultCrudSchemas as y };

package/dist/{validate-CidSeUrx.mjs → validate-R0G_JrnK.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-Add2L50I.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DjDuyglE.mjs";
 //#region src/core/aggregation/normalize.ts
 /**
 * Framework cap on URL-driven aggregation limits when the host opts

package/dist/{versioning-B843jOYX.d.mts → versioning-D6JIK8Tk.d.mts}

@@ -1,6 +1,62 @@
 
-import { n as DomainEvent } from "./EventTransport-Cx60_s-6.mjs";
+import { n as DomainEvent } from "./EventTransport-CbUKDzZZ.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
+//#region src/plugins/gracefulShutdown.d.ts
+interface GracefulShutdownOptions {
+  /** Maximum time to wait for graceful shutdown in ms (default: 30000) */
+  timeout?: number;
+  /** Custom cleanup function called before exit */
+  onShutdown?: () => Promise<void> | void;
+  /** Signals to handle (default: ['SIGTERM', 'SIGINT']) */
+  signals?: NodeJS.Signals[];
+  /** Whether to log shutdown events (default: true) */
+  logEvents?: boolean;
+  /**
+   * Lame-duck window in ms between flipping readiness and closing the
+   * server (default: 0 — close immediately, the pre-2.41 behaviour).
+   *
+   * A load balancer keeps routing to an instance until its readiness
+   * probe has failed for a few intervals; closing the moment SIGTERM
+   * arrives is the classic rolling-deploy 502. Set this to exceed the LB's
+   * deregistration window (typically 5000–15000) so `/ready` reports
+   * `draining` while the instance still answers everything routed to it.
+   * Counts against `timeout`.
+   */
+  drainDelayMs?: number;
+  /**
+   * Called when shutdown times out or encounters an error.
+   * Defaults to `process.exit(1)` — appropriate for production but dangerous in:
+   * - **Tests**: kills the test runner. Pass `() => {}` or `() => { throw … }`.
+   * - **Shared runtimes** (e.g., serverless): may kill unrelated handlers.
+   *
+   * @param reason - `'timeout'` if shutdown exceeded `timeout` ms,
+   *                 `'error'` if `onShutdown` or `fastify.close()` threw.
+   */
+  onForceExit?: (reason: "timeout" | "error") => void;
+}
+/**
+ * Readable shutdown state — `fastify.shutdownState`. Set the moment a signal
+ * (or `fastify.shutdown()`) arrives, BEFORE the server closes, so readiness
+ * can start failing while the instance is still serving. `/live` ignores it:
+ * a draining process is alive, that is the whole point of the window.
+ */
+interface ShutdownState {
+  /** True from the shutdown signal onward — never resets. */
+  readonly draining: boolean;
+  /** When draining began. */
+  readonly since?: Date;
+}
+declare const gracefulShutdownPlugin: FastifyPluginAsync<GracefulShutdownOptions>;
+declare module "fastify" {
+  interface FastifyInstance {
+    /** Trigger graceful shutdown manually */
+    shutdown: () => Promise<void>;
+    /** Draining flag + start time; read by the health plugin's `/ready`. */
+    shutdownState: ShutdownState;
+  }
+}
+declare const _default$5: FastifyPluginAsync<GracefulShutdownOptions>;
+//#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
   /** Path prefix to match (e.g., '/api/products') */
@@ -172,4 +228,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { CachingRule as _, MetricsCollector as a, metricsPlugin as c, _default$2 as d, realtimePlugin as f, CachingOptions as g, ssePlugin as h, MetricEntry as i, ChangeOperation as l, _default$3 as m, _default as n, MetricsOptions as o, SSEOptions as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, RealtimeOptions as u, _default$4 as v, cachingPlugin as y };
+export { gracefulShutdownPlugin as C, _default$5 as S, CachingRule as _, MetricsCollector as a, GracefulShutdownOptions as b, metricsPlugin as c, _default$2 as d, realtimePlugin as f, CachingOptions as g, ssePlugin as h, MetricEntry as i, ChangeOperation as l, _default$3 as m, _default as n, MetricsOptions as o, SSEOptions as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, RealtimeOptions as u, _default$4 as v, ShutdownState as x, cachingPlugin as y };

package/dist/{versioning-C2r0eOZ4.mjs → versioning-DuVWcu-F.mjs}

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-Add2L50I.mjs";
-import { d as createDomainError } from "./errors-2ExmOgIJ.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DjDuyglE.mjs";
+import { d as createDomainError } from "./errors-C_YhELhe.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({