@classytic/arc 2.41.1 → 2.44.0

package/dist/{redis-Bzi1y3F9.d.mts → redis-BDgv9Glw.d.mts}

@@ -1,5 +1,6 @@
 
-import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-DEWNOMza.mjs";
+import { n as UpstashKeyValueCommands, t as IoredisKeyValueCommands } from "./redisShapes-CQksY67q.mjs";
+import { i as IdempotencyStore, r as IdempotencyResult, t as IdempotencyAcquisition } from "./interface-JJzwH4Ro.mjs";
 //#region src/idempotency/stores/redis.d.ts
 interface RedisClient {
   get(key: string): Promise<string | null>;
@@ -26,6 +27,9 @@ interface RedisIdempotencyStoreOptions {
 }
 declare class RedisIdempotencyStore implements IdempotencyStore {
   readonly name = "redis";
+  readonly supportsFencedCompletion: boolean;
+  /** The fenced completion script deletes the lock; it needs `eval`, as fencing does. */
+  readonly completionReleasesLock: boolean;
   private client;
   private prefix;
   private lockPrefix;
@@ -34,8 +38,11 @@ declare class RedisIdempotencyStore implements IdempotencyStore {
   private resultKey;
   private lockKey;
   get(key: string): Promise<IdempotencyResult | undefined>;
+  private parseResult;
   set(key: string, result: Omit<IdempotencyResult, "key">): Promise<void>;
   tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+  acquire(key: string, requestId: string, lockTtlMs: number): Promise<IdempotencyAcquisition>;
+  setIfLocked(key: string, requestId: string, result: Omit<IdempotencyResult, "key">): Promise<boolean>;
   unlock(key: string, requestId: string): Promise<void>;
   isLocked(key: string): Promise<boolean>;
   delete(key: string): Promise<void>;
@@ -46,21 +53,12 @@ declare class RedisIdempotencyStore implements IdempotencyStore {
   close(): Promise<void>;
 }
 /**
- * Minimal ioredis shape we depend on — keeps this file peer-dep-free.
- *
- * Variadic tails are `unknown[]`, not `(string | number)[]`: ioredis types
- * every command as overloads whose tails mix literal tokens (`'MATCH'`),
- * `Buffer` and an optional callback, and a narrower tail matches NONE of
- * them — a real `Redis` instance then fails to assign (TS2345). Pinned by
- * `tests/types/ioredis-assignability.test.ts`.
+ * Minimal ioredis shape the idempotency store depends on — the shared
+ * key/value commands (`utils/redisShapes.ts`, where the `unknown[]`-tail rule
+ * is explained) plus `exists` and lifecycle. Keeps this file peer-dep-free.
  */
-interface IoredisLike {
-  get(key: string): Promise<string | null>;
-  set(...args: unknown[]): Promise<string | null>;
-  del(...keys: string[]): Promise<number>;
+interface IoredisLike extends IoredisKeyValueCommands {
   exists(...keys: string[]): Promise<number>;
-  scan(cursor: string | number, ...args: unknown[]): Promise<[string, string[]]>;
-  eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
   quit?(): Promise<string>;
   disconnect?(): void;
 }
@@ -86,17 +84,12 @@ interface IoredisLike {
 declare function ioredisAsIdempotencyClient(client: IoredisLike): RedisClient & {
   eval?: (script: string, numkeys: number, ...args: (string | number)[]) => Promise<unknown>;
 };
-/** Minimal `@upstash/redis` shape we depend on (REST client, edge-safe). */
-interface UpstashRedisLike {
-  get(key: string): Promise<string | null | unknown>;
-  set(key: string, value: unknown, opts?: Record<string, unknown>): Promise<unknown>;
-  del(...keys: string[]): Promise<number>;
+/**
+ * Minimal `@upstash/redis` shape the idempotency store depends on (REST,
+ * edge-safe) — the shared key/value commands plus `exists`.
+ */
+interface UpstashRedisLike extends UpstashKeyValueCommands {
   exists(...keys: string[]): Promise<number>;
-  scan(cursor: number | string, opts?: {
-    match?: string;
-    count?: number;
-  }): Promise<[number, string[]] | [string, string[]]>;
-  eval?(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
 }
 /**
  * Wrap an `@upstash/redis` REST client as an idempotency `RedisClient`.

package/dist/redis-stream-BMk-bpQS.d.mts

@@ -0,0 +1,219 @@
+
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-CiicKz2Z.mjs";
+//#region src/events/transports/redis-stream.d.ts
+interface RedisStreamLike {
+  xadd(key: string, id: string, ...fieldValues: string[]): Promise<string | null>;
+  /**
+   * Per-handler progress for a partially failed message — which handlers already completed, so
+   * a retry (on any replica) runs only the rest. Optional for custom wrappers; without them a
+   * retry re-runs every handler and the transport warns once.
+   */
+  hset?(key: string, ...fieldValues: string[]): Promise<unknown>;
+  hgetall?(key: string): Promise<Record<string, string>>;
+  del?(...keys: string[]): Promise<unknown>;
+  pexpire?(key: string, ms: number): Promise<unknown>;
+  xreadgroup(command: "GROUP", group: string, consumer: string, ...args: unknown[]): Promise<Array<[string, Array<[string, string[] | null]>]> | null>;
+  xack(key: string, group: string, ...ids: unknown[]): Promise<number>;
+  xgroup(command: string, key: string, group: string, ...args: unknown[]): Promise<unknown>;
+  xpending(key: string, group: string, ...args: unknown[]): Promise<unknown[]>;
+  xclaim(key: string, group: string, consumer: string, minIdleTime: number, ...ids: unknown[]): Promise<unknown[]>;
+  xlen(key: string): Promise<number>;
+  /**
+   * Lets the DLQ writer copy the original payload into the envelope, making
+   * dead-lettered events replayable. Without it the envelope keeps the error
+   * and attempt count but `event.payload` is `null` (warned once per process).
+   */
+  xrange?(key: string, start: string, end: string): Promise<Array<[string, string[]]>>;
+  /** Graceful close — flushes queued commands then closes. ioredis-style. */
+  quit(): Promise<unknown>;
+  /**
+   * Force-disconnect, abandoning a live `XREADGROUP BLOCK`. When missing,
+   * `close()` falls back to `quit()` and may wait up to `blockTimeMs`.
+   */
+  disconnect?(): void;
+}
+interface RedisStreamTransportOptions {
+  /**
+   * Redis stream key name.
+   * @default 'arc:events'
+   */
+  stream?: string;
+  /**
+   * How long a partially failed message's per-handler progress is kept, in ms. Must outlast the
+   * retry window. @default 7 days
+   */
+  handlerProgressTtlMs?: number;
+  /**
+   * Consumer group name. Each group receives every event independently.
+   * Multiple instances of the same service should share a group name.
+   * @default 'default'
+   */
+  group?: string;
+  /**
+   * Consumer name within the group. Must be unique per instance.
+   * @default 'consumer-<random>'
+   */
+  consumer?: string;
+  /**
+   * Block time in ms when waiting for new events.
+   * @default 5000
+   */
+  blockTimeMs?: number;
+  /**
+   * Max events to read per batch.
+   * @default 10
+   */
+  batchSize?: number;
+  /**
+   * Max entries of a batch processed concurrently. `1` keeps strict stream
+   * order; higher values let entries complete OUT OF ORDER, so raise it only
+   * for order-independent handlers. Handlers for a single event always run
+   * sequentially.
+   * @default 1
+   */
+  processingConcurrency?: number;
+  /**
+   * Max delivery attempts before moving to dead letter stream.
+   * @default 5
+   */
+  maxRetries?: number;
+  /**
+   * Idle time in ms before another consumer may claim a pending entry
+   * (crash recovery).
+   * @default 30000
+   */
+  claimTimeoutMs?: number;
+  /**
+   * Dead letter stream name. Failed events are moved here after maxRetries.
+   * Set to `false` to disable DLQ (failed events are acked and dropped).
+   * @default 'arc:events:dlq'
+   */
+  deadLetterStream?: string | false;
+  /**
+   * Max stream length (approximate, XADD MAXLEN ~). Trimming can drop entries still PENDING for a
+   * slow consumer, so it is opt-in: set it only with lag / oldest-pending monitoring in place.
+   * @default 0 (no trimming)
+   */
+  maxLen?: number;
+  /**
+   * Where a NEW consumer group starts reading. `'latest'` (`$`) skips entries published before the
+   * group existed; `'beginning'` (`0`) replays the whole stream — including every side effect.
+   * @default 'latest'
+   */
+  groupStart?: "latest" | "beginning";
+  /**
+   * Max serialized event size in bytes; `publish()` rejects larger events.
+   * @default 1_000_000 (1 MB)
+   */
+  maxPayloadBytes?: number;
+  /**
+   * If `true`, `close()` never quits/disconnects the client — for a Redis
+   * connection shared with other transports or stores.
+   * @default false
+   */
+  externalLifecycle?: boolean;
+  /**
+   * Max time `close()` waits for the in-flight `XREADGROUP BLOCK` to drain.
+   * On timeout the client is force-disconnected, or — under
+   * `externalLifecycle` — the loop drains in the background (see `close()`).
+   * @default 1000
+   */
+  closeTimeoutMs?: number;
+  /**
+   * Logger for error messages (default: console).
+   * Pass `fastify.log` to integrate with your application logger.
+   */
+  logger?: EventLogger;
+}
+declare class RedisStreamTransport implements EventTransport {
+  readonly name = "redis-stream";
+  private redis;
+  private stream;
+  private group;
+  private consumer;
+  private blockTimeMs;
+  private batchSize;
+  private processingConcurrency;
+  private maxRetries;
+  private claimTimeoutMs;
+  private deadLetterStream;
+  private maxLen;
+  private groupStartId;
+  private maxPayloadBytes;
+  private logger;
+  private externalLifecycle;
+  private closeTimeoutMs;
+  private router;
+  private running;
+  private pollPromise;
+  /**
+   * Bumped whenever the poll loop should stop (last unsubscribe, `close()`).
+   * Each loop exits once its captured generation is stale, so a fast
+   * unsubscribe → resubscribe never leaves two loops on one consumer name.
+   */
+  private generation;
+  private groupCreated;
+  /**
+   * Last handler failure per message id, so the DLQ envelope carries the real
+   * error. Cleared on ack / DLQ write; capped at {@link MAX_FAILURE_CONTEXT_ENTRIES}.
+   */
+  private failureContext;
+  /** Set by `hold()`: subscriptions register, consumption waits for `start()`. */
+  private held;
+  /** Handler → a key stable across replicas: pattern, name, and order among same-named handlers. */
+  private handlerKeys;
+  private handlerKeyOwners;
+  private handlerPatterns;
+  private handlerProgressTtlMs;
+  private readonly tracksProgress;
+  private xrangeWarningEmitted;
+  constructor(redis: RedisStreamLike, options?: RedisStreamTransportOptions);
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  /**
+   * Register subscriptions without consuming until `start()`. arc holds consumption for the whole
+   * boot, so an entry for a module whose handler installs later is not acked with no handler.
+   */
+  hold(): void;
+  /** Begin consuming — every handler registered while held sees the stream from here. */
+  start(): Promise<void>;
+  private startPolling;
+  /**
+   * Stop polling and release transport state. Waits up to `closeTimeoutMs`
+   * for the in-flight `XREADGROUP BLOCK`, then:
+   *
+   * - default: force-disconnects the client to break the BLOCK and awaits the
+   *   loop — the transport is fully closed on return.
+   * - `externalLifecycle: true`: returns without touching the host's client;
+   *   the loop drains in the background (up to `blockTimeMs` — keep it low)
+   *   with its outcome silenced. Handlers are already cleared, so nothing
+   *   dispatches meanwhile.
+   *
+   * A later `subscribe()` starts a fresh loop that never overlaps the stale one.
+   */
+  close(): Promise<void>;
+  private ensureGroup;
+  private pollLoop;
+  private readNewMessages;
+  /** Process a batch with at most `processingConcurrency` entries in flight. */
+  private processEntries;
+  private claimPending;
+  private processEntry;
+  /**
+   * Uses the primitives router — the same glob rules (and dedup) as the memory
+   * transport. Don't swap in a private matcher: subscriptions must behave
+   * identically in-process and on the stream.
+   */
+  private getMatchingHandlers;
+  private moveToDlq;
+  /**
+   * Build a `DeadLetteredEvent` from the original entry (via `xrange`) plus
+   * any local failure context. If the entry is unreadable (no `xrange`, error,
+   * or trimmed) the envelope keeps just the error and attempts. Returns `null`
+   * only when both are missing.
+   */
+  private buildDlqEnvelope;
+  private sleep;
+}
+//#endregion
+export { RedisStreamTransport as n, RedisStreamTransportOptions as r, RedisStreamLike as t };

package/dist/redisShapes-CQksY67q.d.mts

@@ -0,0 +1,55 @@
+
+//#region src/utils/redisShapes.d.ts
+/**
+ * The key/value command shapes arc's cache and idempotency stores share, for
+ * the two Redis clients hosts actually plug in: ioredis (TCP) and
+ * `@upstash/redis` (REST, edge-safe).
+ *
+ * Both stores used to declare their own copies of these, and they drifted the
+ * way copies do — the ioredis-assignability fix in 2.41 had to be applied to
+ * each separately. Each store's exported `IoredisLike` / `UpstashRedisLike`
+ * now EXTENDS the base here and adds only what that store uses beyond it, so
+ * the exported names are unchanged.
+ *
+ * Deliberately NOT a single shape for every Redis user in arc. Streams
+ * (`xadd`/`xreadgroup`), pub/sub (`subscribe`/`duplicate`), sessions (sets),
+ * usage (hashes) and circuit counters (`incr`) share almost no commands with
+ * each other, and where they overlap the signatures differ on purpose. A
+ * shared superset would couple unrelated features and make every host wrapper
+ * implement commands it never serves.
+ *
+ * ## The one rule every ioredis shape must follow
+ *
+ * Variadic tails are `unknown[]`, never `(string | number)[]`. ioredis types
+ * each command as a set of OVERLOADS whose tails mix literal tokens (`'MATCH'`,
+ * `'PX'`, `'NX'`), `Buffer`, and an optional trailing callback. A narrower
+ * tail matches none of them, and `new Redis(url)` then fails to assign with
+ * TS2345. Pinned for every arc shape by `tests/types/ioredis-assignability.test.ts`.
+ */
+/** ioredis key/value commands shared by the cache and idempotency stores. */
+interface IoredisKeyValueCommands {
+  get(key: string): Promise<string | null>;
+  set(...args: unknown[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  scan(cursor: string | number, ...args: unknown[]): Promise<[string, string[]]>;
+  eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+/**
+ * `@upstash/redis` key/value commands shared by the cache and idempotency
+ * stores. REST-based, so it runs on edge runtimes (Cloudflare Workers, Vercel
+ * Edge, Deno Deploy) where TCP — and thus ioredis — is unavailable. Note the
+ * different call shapes: options objects rather than positional tokens, and
+ * `eval(script, keys[], args[])`.
+ */
+interface UpstashKeyValueCommands {
+  get(key: string): Promise<string | null | unknown>;
+  set(key: string, value: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  scan(cursor: number | string, opts?: {
+    match?: string;
+    count?: number;
+  }): Promise<[number, string[]] | [string, string[]]>;
+  eval?(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+}
+//#endregion
+export { UpstashKeyValueCommands as n, IoredisKeyValueCommands as t };

package/dist/registry/index.d.mts

@@ -1,6 +1,6 @@
 
-import { K as ResolvedTenantPurge, R as RegisterOptions, V as ResourceDefinition, X as CrudRouteKey, k as IntrospectionPluginOptions, p as RegistryEntry, z as ResourceRegistry } from "../index-DHbyPo5j.mjs";
-import "../fastify-augmentation-Cq2nHVaW.mjs";
+import { F as ResourceDefinition, G as CrudRouteKey, M as ResourceRegistry, N as RouteRow, S as IntrospectionPluginOptions, V as ResolvedTenantPurge, j as RegisterOptions, o as RegistryEntry } from "../index-WH7xgvxS.mjs";
+import "../fastify-augmentation-DRlCIWE9.mjs";
 import { TenantPurgeProgress, TenantPurgeStrategy } from "@classytic/repo-core/repository";
 import { FastifyPluginAsync } from "fastify";
 //#region src/registry/assertNoTenantData.d.ts
@@ -60,7 +60,7 @@ interface AssertNoTenantDataReport {
  * });
  * ```
  */
-declare function assertNoTenantData(registry: ResourceRegistry, options: AssertNoTenantDataOptions): Promise<AssertNoTenantDataReport>;
+export declare function assertNoTenantData(registry: ResourceRegistry, options: AssertNoTenantDataOptions): Promise<AssertNoTenantDataReport>;
 //#endregion
 //#region src/registry/purgeResource.d.ts
 /**
@@ -232,7 +232,7 @@ interface CascadeCheckpoint {
  * A resource is cascading when its resolved strategy isn't `disabled`
  * (i.e. the host declared `onTenantDelete`).
  */
-declare function getCascadingResources(registry: ResourceRegistry): readonly string[];
+export declare function getCascadingResources(registry: ResourceRegistry): readonly string[];
 /**
  * Rich introspection — returns the resolved strategy + source per
  * cascading resource. Use for audit dashboards that answer "what
@@ -245,7 +245,7 @@ declare function getCascadingResources(registry: ResourceRegistry): readonly str
  * purge this" entry. Anonymize carries the field map. Custom carries
  * the handler reference. Narrow on `.strategy.type` for typed access.
  */
-declare function getCascadingResourcesWithMetadata(registry: ResourceRegistry): readonly {
+export declare function getCascadingResourcesWithMetadata(registry: ResourceRegistry): readonly {
   name: string;
   tenantField: string;
   strategy: TenantPurgeStrategy;
@@ -274,10 +274,9 @@ declare function getCascadingResourcesWithMetadata(registry: ResourceRegistry):
  * @param registry  The arc resource registry (`fastify.arc.registry`).
  * @param options   Org id + filters + logger + progress + signal.
  */
-declare function cascadeDeleteForOrganization(registry: ResourceRegistry, options: CascadeOptions): Promise<CascadeReport>;
+export declare function cascadeDeleteForOrganization(registry: ResourceRegistry, options: CascadeOptions): Promise<CascadeReport>;
 //#endregion
 //#region src/registry/introspectionPlugin.d.ts
-declare const introspectionPlugin: FastifyPluginAsync<IntrospectionPluginOptions>;
 declare const _default: FastifyPluginAsync<IntrospectionPluginOptions>;
 //#endregion
 //#region src/registry/manifest.d.ts
@@ -326,13 +325,19 @@ interface ResourceManifest {
   readonly customRoutes: readonly CustomRouteManifestEntry[];
   /** Tenant scoping field (when set) — surfaces for FE callers that need to send `x-organization-id`. */
   readonly tenantField?: string | false;
+  /**
+   * Optimistic-concurrency version field — present only when the resource declares
+   * `concurrency`. A client sends `If-Match: "<doc[versionField]>"` on update and gets
+   * `412 arc.precondition_failed` for a stale one (arc-next: `createCrudApi(entity, { versionField })`).
+   */
+  readonly versionField?: string;
 }
 /**
  * Build a manifest from a `ResourceDefinition` (the value returned by
  * `defineResource(...)`). Use at build time when you have direct access
  * to the resource module — typically the simplest codegen path.
  */
-declare function buildResourceManifest(resource: ResourceDefinition): ResourceManifest;
+export declare function buildResourceManifest(resource: ResourceDefinition): ResourceManifest;
 /**
  * Build a manifest from a `RegistryEntry` — use when the resource is
  * already registered (introspection endpoint, runtime audit script).
@@ -343,6 +348,6 @@ declare function buildResourceManifest(resource: ResourceDefinition): ResourceMa
  * `/_resources` endpoint) gets the same output without dragging the resource
  * module into the codegen path.
  */
-declare function buildResourceManifestFromRegistry(entry: RegistryEntry): ResourceManifest;
+export declare function buildResourceManifestFromRegistry(entry: RegistryEntry): ResourceManifest;
 //#endregion
-export { type ActionManifestEntry, type ActionMount, type AggregationManifestEntry, type AssertNoTenantDataOptions, type AssertNoTenantDataReport, type CascadeCheckpoint, type CascadeCheckpointState, type CascadeOptions, type CascadeReport, type CascadeResourceReport, type CustomRouteManifestEntry, type IntrospectionPluginOptions, type RegisterOptions, type ResourceManifest, ResourceRegistry, type TenantDataLeak, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, _default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };
+export { type ActionManifestEntry, type ActionMount, type AggregationManifestEntry, type AssertNoTenantDataOptions, type AssertNoTenantDataReport, type CascadeCheckpoint, type CascadeCheckpointState, type CascadeOptions, type CascadeReport, type CascadeResourceReport, type CustomRouteManifestEntry, type IntrospectionPluginOptions, type RegisterOptions, type ResourceManifest, ResourceRegistry, type RouteRow, type TenantDataLeak, _default as introspectionPlugin };

package/dist/registry/index.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { a as cascadeDeleteForOrganization, c as assertNoTenantData, i as introspectionPlugin_default, n as buildResourceManifestFromRegistry, o as getCascadingResources, r as introspectionPlugin, s as getCascadingResourcesWithMetadata, t as buildResourceManifest } from "../registry-DNkgGQcK.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-MGpXoxHZ.mjs";
-export { ResourceRegistry, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { a as getCascadingResources, i as cascadeDeleteForOrganization, n as buildResourceManifestFromRegistry, o as getCascadingResourcesWithMetadata, r as introspectionPlugin_default, s as assertNoTenantData, t as buildResourceManifest } from "../registry-Bdzg-hdm.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-DJxHUpE4.mjs";
+export { ResourceRegistry, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, introspectionPlugin_default as introspectionPlugin };

package/dist/{registry-DNkgGQcK.mjs → registry-Bdzg-hdm.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as CRUD_OPERATIONS } from "./constants-D5Ubn1fe.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as CRUD_OPERATIONS } from "./constants-B2QHb6u6.mjs";
 import fp from "fastify-plugin";
 //#region src/registry/assertNoTenantData.ts
 /**
@@ -405,7 +405,7 @@ const introspectionPlugin = async (fastify, opts = {}) => {
 	const typedFastify = fastify;
 	const authMiddleware = authRoles.length > 0 && typedFastify.authenticate ? [typedFastify.authenticate, typedFastify.authorize?.(...authRoles)].filter(Boolean) : [];
 	const getRegistry = () => fastify.arc?.registry;
-	await fastify.register(async (instance) => {
+	const introspectionRoutes = async (instance) => {
 		instance.get("/", { preHandler: authMiddleware }, async (_req, _reply) => {
 			return getRegistry()?.getIntrospection() ?? {
 				resources: [],
@@ -434,7 +434,8 @@ const introspectionPlugin = async (fastify, opts = {}) => {
 			if (!resource) return reply.code(404).send({ error: `Resource '${req.params.name}' not found` });
 			return resource;
 		});
-	}, { prefix });
+	};
+	await fastify.register(introspectionRoutes, { prefix });
 	fastify.log?.debug?.(`Introspection API at ${prefix}`);
 };
 var introspectionPlugin_default = fp(introspectionPlugin, { name: "arc-introspection" });
@@ -442,8 +443,8 @@ var introspectionPlugin_default = fp(introspectionPlugin, { name: "arc-introspec
 //#region src/registry/manifest.ts
 /**
 * Resource metadata for frontend code generators — `{ name, prefix, idField,
-* crudOps, actions[] }`, where each action carries its `mount` and
-* `requiresId`.
+* versionField?, crudOps, actions[] }`, where each action carries its `mount`
+* and `requiresId`.
 *
 * A hand-rolled FE client needs a method per declarative action and drifts the
 * moment a new one is declared. Arc owns the resource definition, so it can
@@ -502,7 +503,8 @@ function buildResourceManifest(resource) {
 		actions,
 		aggregations,
 		customRoutes,
-		...resource.tenantField !== void 0 ? { tenantField: resource.tenantField } : {}
+		...resource.tenantField !== void 0 ? { tenantField: resource.tenantField } : {},
+		...resource.versionField !== void 0 ? { versionField: resource.versionField } : {}
 	};
 }
 /**
@@ -544,14 +546,15 @@ function buildResourceManifestFromRegistry(entry) {
 		name: entry.name,
 		displayName: entry.displayName ?? entry.name,
 		prefix: entry.prefix,
-		idField: "_id",
+		idField: entry.idField ?? "_id",
 		updateMethod,
 		crudOps,
 		actions,
 		aggregations,
 		customRoutes,
-		...entry.tenantField !== void 0 ? { tenantField: entry.tenantField } : {}
+		...entry.tenantField !== void 0 ? { tenantField: entry.tenantField } : {},
+		...entry.versionField !== void 0 ? { versionField: entry.versionField } : {}
 	};
 }
 //#endregion
-export { cascadeDeleteForOrganization as a, assertNoTenantData as c, introspectionPlugin_default as i, buildResourceManifestFromRegistry as n, getCascadingResources as o, introspectionPlugin as r, getCascadingResourcesWithMetadata as s, buildResourceManifest as t };
+export { getCascadingResources as a, cascadeDeleteForOrganization as i, buildResourceManifestFromRegistry as n, getCascadingResourcesWithMetadata as o, introspectionPlugin_default as r, assertNoTenantData as s, buildResourceManifest as t };

package/dist/{renewingLease-yF8BdW4b.mjs → renewingLease-BFJxGPuh.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
 //#region src/lock/renewingLease.ts
 /**
 * Start renewing an ALREADY-ACQUIRED lease. The caller performed the

package/dist/{replyHelpers-CNdvMfM4.mjs → replyHelpers-Bnc6lJyy.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
 import { toCanonicalList } from "@classytic/repo-core/pagination";
 import fp from "fastify-plugin";
 //#region src/plugins/replyHelpers.ts

package/dist/{requestContext-cDkAUr-P.mjs → requestContext-C10UeFe5.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context/requestContext.ts
 /**

package/dist/requirement-Bu50QALH.mjs

@@ -0,0 +1,35 @@
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+//#region src/idempotency/requirement.ts
+/** What is wrong with a route's idempotency declaration, or `undefined` when it is sound. */
+function idempotencyConfigProblem(config) {
+	const idem = config?.idempotency;
+	if (!idem) return void 0;
+	const ownerOk = typeof idem.owner === "string" && idem.owner.trim() !== "";
+	if (idem.dedup !== void 0 && idem.dedup !== "handler") return `dedup must be 'handler', got '${String(idem.dedup)}'`;
+	if (idem.dedup === "handler" && idem.required !== true) return "dedup: 'handler' needs required: true (the key is still demanded)";
+	if (idem.dedup === "handler" && !ownerOk) return "dedup: 'handler' needs a non-empty `owner` naming the runner that deduplicates";
+	if (idem.dedup === void 0 && idem.owner !== void 0) return "`owner` is only meaningful with dedup: 'handler'";
+	for (const [action, owner] of Object.entries(idem.handlerDedup ?? {})) if (!idem.requiredActions?.includes(action) || owner.trim() === "") return `handlerDedup '${action}' must name an action in requiredActions and a non-empty owner`;
+}
+/** True iff the route declares a fence for at least one call shape. */
+function declaresIdempotencyFence(config) {
+	const idem = config?.idempotency;
+	return idem?.required === true || (idem?.requiredActions?.length ?? 0) > 0;
+}
+/** True iff THIS request's handler deduplicates itself (arc only demands and exposes the key). */
+function requestDedupedByHandler(request) {
+	const idem = request.routeOptions.config?.idempotency;
+	if (idem?.required === true) return idem.dedup === "handler";
+	const action = request.body?.action;
+	return typeof action === "string" && idem?.handlerDedup?.[action] !== void 0;
+}
+/** True iff THIS request is fenced — a keyless call is refused, a keyed one deduplicated. */
+function requestRequiresIdempotencyKey(request) {
+	const idem = request.routeOptions.config?.idempotency;
+	if (idem?.required === true) return true;
+	if (!idem?.requiredActions?.length) return false;
+	const action = request.body?.action;
+	return typeof action === "string" && idem.requiredActions.includes(action);
+}
+//#endregion
+export { requestRequiresIdempotencyKey as i, idempotencyConfigProblem as n, requestDedupedByHandler as r, declaresIdempotencyFence as t };

package/dist/requirement-CbiLdQ1n.d.mts

@@ -0,0 +1,22 @@
+
+import { FastifyRequest } from "fastify";
+//#region src/idempotency/requirement.d.ts
+/** The `config.idempotency` slot of a Fastify route. */
+interface RouteIdempotencyConfig {
+  /** Every call needs a key — any method, DELETE included. */
+  readonly required?: boolean;
+  /** Action route only: a call whose `body.action` is one of these needs a key. */
+  readonly requiredActions?: readonly string[];
+  /**
+   * `'handler'`: the handler owns at-most-once for this route (its own durable claim). Arc still
+   * refuses a keyless call and exposes the key on `request.idempotencyKey`, but stores, locks,
+   * fingerprints and replays nothing. Needs `required: true` and an `owner`.
+   */
+  readonly dedup?: "handler";
+  /** Names the runner that owns deduplication under `dedup: 'handler'`. */
+  readonly owner?: string;
+  /** Action route only: action name -> owner, for actions in `requiredActions` that dedupe themselves. */
+  readonly handlerDedup?: Readonly<Record<string, string>>;
+}
+//#endregion
+export { RouteIdempotencyConfig as t };

package/dist/resourceRateLimit-Wf6d6FL9.d.mts

@@ -0,0 +1,30 @@
+
+import { i as RequestScope } from "./types-Ddl9OjmE.mjs";
+import { FastifyInstance } from "fastify";
+//#region src/permissions/resourceRateLimit.d.ts
+interface ResourceRateLimitPolicy {
+  max: number;
+  timeWindow: string;
+  /** Explicit route overrides own a separate budget. */
+  bucket?: string;
+}
+interface ResourceRateLimitContext {
+  scope?: RequestScope;
+  ip?: string;
+}
+interface ResourceRateLimitDecision {
+  readonly allowed: boolean;
+  readonly retryAfterSeconds: number;
+  readonly headers: Readonly<Record<string, number>>;
+}
+/** One resource budget across operations and transports, backed by the host's limiter. */
+interface ResourceRateLimiter {
+  readonly durability: "memory" | "shared";
+  consume(resource: string, policy: ResourceRateLimitPolicy, context: ResourceRateLimitContext): Promise<ResourceRateLimitDecision>;
+}
+/** Uses createRateLimit's store factory, preserving Redis/custom-store configuration. */
+declare function resolveResourceRateLimiter(app: FastifyInstance, durability?: ResourceRateLimiter["durability"]): ResourceRateLimiter | undefined;
+/** Standalone tools may use memory; wired distributed apps use the host's shared store. */
+declare function createMemoryResourceRateLimiter(capacity?: number): ResourceRateLimiter;
+//#endregion
+export { createMemoryResourceRateLimiter as a, ResourceRateLimiter as i, ResourceRateLimitDecision as n, resolveResourceRateLimiter as o, ResourceRateLimitPolicy as r, ResourceRateLimitContext as t };