@classytic/arc 2.40.0 → 2.41.1

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/usage/index.mjs

@@ -1,6 +1,7 @@
-/*! @classytic/arc v2.40.0 | MIT | https://classytic.com */
-import { t as ArcError } from "../errors-BHD3L8of.mjs";
-import { c as getOrgId, g as getUserId, i as getClientId } from "../types-CNQyOrLk.mjs";
+/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+import { t as ArcError } from "../errors-BH7YU_9O.mjs";
+import { c as getOrgId, g as getUserId, i as getClientId } from "../types-CgenB1gv.mjs";
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-CkhS6jn6.mjs";
 import { usagePeriod } from "@classytic/repo-core/usage";
 import fp from "fastify-plugin";
 //#region src/usage/requireQuota.ts
@@ -85,6 +86,51 @@ var MemoryUsageStore = class {
 	}
 };
 //#endregion
+//#region src/usage/stores/redis.ts
+/** Period-bucketed usage counters in Redis hashes. See the module header. */
+var RedisUsageStore = class {
+	name = "redis";
+	#redis;
+	#prefix;
+	#retentionSeconds;
+	constructor(options) {
+		this.#redis = options.redis;
+		this.#prefix = options.prefix ?? "arc:usage:";
+		const retention = options.retentionSeconds;
+		if (retention !== void 0 && (!Number.isFinite(retention) || retention <= 0)) throw new Error(`[arc-usage] RedisUsageStore: retentionSeconds must be a positive number, got ${String(retention)}. Omit it to keep counters forever.`);
+		this.#retentionSeconds = retention;
+	}
+	#key(actor, period) {
+		return `${this.#prefix}${actor}:${period}`;
+	}
+	async increment(bucket, amount) {
+		const key = this.#key(bucket.actor, bucket.period);
+		const ttl = this.#retentionSeconds;
+		if (ttl === void 0) {
+			await this.#redis.hincrby(key, bucket.kind, amount);
+			return;
+		}
+		const pipeline = this.#redis.pipeline?.();
+		if (pipeline) {
+			pipeline.hincrby(key, bucket.kind, amount);
+			pipeline.expire(key, ttl);
+			await pipeline.exec();
+			return;
+		}
+		await this.#redis.hincrby(key, bucket.kind, amount);
+		await this.#redis.expire(key, ttl);
+	}
+	async summary(actor, period) {
+		const raw = await this.#redis.hgetall(this.#key(actor, period));
+		const out = {};
+		for (const [kind, value] of Object.entries(raw ?? {})) {
+			const n = Number(value);
+			if (Number.isFinite(n)) out[kind] = n;
+		}
+		return out;
+	}
+};
+//#endregion
 //#region src/usage/usagePlugin.ts
 function actorFromScope(scope) {
 	if (!scope) return void 0;
@@ -113,6 +159,11 @@ const usagePluginFn = async (fastify, opts) => {
 		return;
 	}
 	const store = opts.store ?? new MemoryUsageStore();
+	declareRuntimeCapability(fastify, {
+		subsystem: "usage.store",
+		durability: opts.store ? "shared" : "memory",
+		detail: "default MemoryUsageStore: counters are replica-local"
+	});
 	const track = {
 		requests: true,
 		egress: false,
@@ -166,4 +217,4 @@ var usagePlugin_default = fp(usagePluginFn, {
 	fastify: "5.x"
 });
 //#endregion
-export { MemoryUsageStore, usagePlugin_default as default, requireQuota, usagePeriod, usagePluginFn as usagePlugin };
+export { MemoryUsageStore, RedisUsageStore, usagePlugin_default as default, requireQuota, usagePeriod, usagePluginFn as usagePlugin };

package/dist/{userHelpers-DLueLQdQ.mjs → userHelpers-ChRvkuSZ.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.40.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.41.1 | 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,7 +1,7 @@
 
 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-D3sIPcD4.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";
@@ -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
@@ -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.40.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-BHD3L8of.mjs";
-import { n as requireSingleHeaderValue, t as getHeader } from "../headers-BFEEshDS.mjs";
-import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-DLueLQdQ.mjs";
-import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Cldubvul.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-CUFBrhq-.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DENbixyA.mjs";
-import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-CFwCzEvU.mjs";
-import { n as declareRuntimeCapability } from "../runtimeCapabilities-Bo7rSKjm.mjs";
-import { t as openSseStream } from "../sseStream-BfZtL5-m.mjs";
-import { t as hasEvents } from "../typeGuards-t_CVgRXN.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.1 | 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-BH7YU_9O.mjs";
+import { n as requireSingleHeaderValue, t as getHeader } from "../headers-BIXWKrzQ.mjs";
+import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-ChRvkuSZ.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-C9bzq2gO.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-CxcctrAh.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-BVA7cFRG.mjs";
+import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-IcRFjWQU.mjs";
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-CkhS6jn6.mjs";
+import { t as openSseStream } from "../sseStream-Ppzo-WUH.mjs";
+import { t as hasEvents } from "../typeGuards-BLjPgVBm.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-CUFBrhq-.mjs → utils-CxcctrAh.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.40.0 | MIT | https://classytic.com */
-import { m as RESERVED_QUERY_PARAMS } from "./constants-BQ2FbhPB.mjs";
+/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+import { m as RESERVED_QUERY_PARAMS } from "./constants-D5Ubn1fe.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError, u as ValidationError } from "./errors-BHD3L8of.mjs";
+import { t as ArcError, u as ValidationError } from "./errors-BH7YU_9O.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
@@ -971,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;
@@ -1051,6 +1054,7 @@ var CircuitBreaker = class {
 			if (this.successes >= this.successThreshold) {
 				this.setState(CircuitState.CLOSED);
 				this.successes = 0;
+				this.clearSharedWindow();
 			}
 		}
 	}
@@ -1061,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
@@ -1213,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
@@ -1480,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-DV3hRbsz.mjs → validate-DrYWnOzI.mjs}

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

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

@@ -1,6 +1,62 @@
 
-import { n as DomainEvent } from "./EventTransport-BPOQsEer.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-BXwmj5SD.mjs → versioning-DKkT4hNJ.mjs}

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.40.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-DzE6ikSH.mjs";
-import { d as createDomainError } from "./errors-BHD3L8of.mjs";
+/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
+import { d as createDomainError } from "./errors-BH7YU_9O.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({

package/dist/{workScope-CoGpuzDX.mjs → workScope-CxKqoIFn.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.40.0 | MIT | https://classytic.com */
-import { n as requestContext } from "./requestContext-D4PuGhEw.mjs";
+/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+import { n as requestContext } from "./requestContext-cDkAUr-P.mjs";
 //#region src/context/workScope.ts
 /** Enter a scope for `fn`, or run it inside the active one. */
 function runWorkScope(seed, fn) {
@@ -20,8 +20,7 @@ function scopedValue(slot, create) {
 	const store = requestContext.get();
 	if (!store) return void 0;
 	const slots = store;
-	const existing = slots[slot];
-	if (existing !== void 0) return existing;
+	if (Object.hasOwn(slots, slot)) return slots[slot];
 	const created = create();
 	slots[slot] = created;
 	return created;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.40.0",
+  "version": "2.41.1",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -353,8 +353,8 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.27.0",
-    "@classytic/repo-core": ">=0.27.0",
+    "@classytic/primitives": ">=0.28.0",
+    "@classytic/repo-core": ">=0.28.0",
     "@classytic/streamline": ">=2.8.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -489,8 +489,8 @@
     "@classytic/gitkit": ">=0.1.0",
     "@classytic/mongokit": "^3.33.0",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.27.0",
-    "@classytic/repo-core": "^0.27.0",
+    "@classytic/primitives": "^0.28.0",
+    "@classytic/repo-core": "^0.28.0",
     "@classytic/sqlitekit": "^0.9.0",
     "@classytic/streamline": "^2.8.2",
     "@electric-sql/pglite": "^0.5.4",

package/skills/arc/SKILL.md

@@ -725,7 +725,7 @@ await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
 
 ## Usage counters + plan limits (2.22)
 
-`@classytic/arc/usage` — `usagePlugin` decorates `fastify.usage` with per-actor, per-UTC-month counters (`record`/`summary`/`period`/`actorOf`; actor chain org → user → client → ip). Auto-tracks `api.requests` (default on) + `api.egress.bytes` (opt-in); recording is fail-safe (a throwing `UsageStore` never fails a request; `MemoryUsageStore` built in, Redis/kit backends are ~5 lines). Pair with `createApp({ rateLimit: { plan: { resolve, limits: { free: { max: 60 }, enterprise: false }, default: 'free' } } })` for per-plan ceilings — `false` = unlimited, unknown/throwing resolvers fall back to `default` then global `max`, and buckets follow the tenant key chain by default. Caveat: the limiter runs before route auth, so `resolve` sees the raw request.
+`@classytic/arc/usage` — `usagePlugin` decorates `fastify.usage` with per-actor, per-UTC-month counters (`record`/`summary`/`period`/`actorOf`; actor chain org → user → client → ip). Auto-tracks `api.requests` (default on) + `api.egress.bytes` (opt-in); recording is fail-safe (a throwing `UsageStore` never fails a request). Stores: `MemoryUsageStore` (default, single-process) and `RedisUsageStore` (2.41 — `HINCRBY`, the right shape for a hot per-request counter) both from `@classytic/arc/usage`; or a kit's (`@classytic/mongokit/usage`) when counters belong beside domain data. `RedisUsageStore` keeps counters forever by default — `retentionSeconds` is opt-in, because expiring billing history on an unchosen schedule is silent (`summary()` returns `{}` for an expired bucket and a never-written one alike). Pair with `createApp({ rateLimit: { plan: { resolve, limits: { free: { max: 60 }, enterprise: false }, default: 'free' } } })` for per-plan ceilings — `false` = unlimited, unknown/throwing resolvers fall back to `default` then global `max`, and buckets follow the tenant key chain by default. Caveat: the limiter runs before route auth, so `resolve` sees the raw request.
 
 ## Runtime capability registry (2.33)
 
@@ -737,12 +737,16 @@ import { declareRuntimeCapability } from '@classytic/arc/utils';
 declareRuntimeCapability(fastify, {
   subsystem: 'billing.sequence-cache',
   durability: 'memory',        // 'memory' | 'shared'
-  accepted: true,              // per-process BY DESIGN (logged, never fatal)
-  detail: 'short-TTL cache; correctness from TTL, not shared state',
+  detail: 'invoice numbering cached per process',
+  // accepted: true,           // ONLY when per-process is intended by design
+  //                           // (logged, never fatal). Must be stated by the
+  //                           // declarant — the audit never infers it.
 });
 ```
 
-`createApp`'s constructor-time guard only sees what it is passed; state a host wires inside `plugins()` was invisible to it and lived on a checklist. This makes the checklist enforcement. Arc's webhooks plugin declares its default in-memory store.
+`createApp`'s constructor-time guard only sees what it is passed; state a host wires inside `plugins()` was invisible to it and lived on a checklist. This makes the checklist enforcement. Declare from anywhere a registration reaches — `plugins()`, a module phase, or your own encapsulated `fastify.register()`; all land in the one audit (2.41).
+
+**Since 2.41 every memory-backed default arc ships declares itself**: `auth.sessions`, `usage.store`, `audit.store`, `cache.query`, `permissions.dynamic-cache` (pass `fastify:` to the matrix — it has no handle of its own), `websocket.adapter`, `websocket.pushref-store`, `webhooks.store`. `http.response-cache` declares `accepted` (per-replica by design). So a distributed app that booted before 2.41 can now fail on a default it was silently running replica-local — the error names each one, and `references/production.md` has the store-by-store fix table.
 
 ## Adapters