@classytic/arc 2.11.3 → 2.13.1

package/dist/events/transports/redis-stream-entry.mjs

@@ -13,10 +13,34 @@ var RedisStreamTransport = class {
 	maxLen;
 	maxPayloadBytes;
 	logger;
+	/** Tracks the lifecycle policy — set in constructor, read in close(). */
+	externalLifecycle;
+	closeTimeoutMs;
 	handlers = /* @__PURE__ */ new Map();
 	running = false;
 	pollPromise = null;
+	/**
+	* Monotonic counter bumped every time the poll loop should stop —
+	* `unsubscribe` (last handler removed) and `close()` increment it. Each
+	* `pollLoop` instance captures its generation at start and exits when
+	* `this.generation` no longer matches. Prevents the
+	* subscribe → unsubscribe → fast-resubscribe race where the old loop
+	* would still be in `XREADGROUP BLOCK` while a new loop started, leading
+	* to two concurrent poll loops on the same consumer name.
+	*/
+	generation = 0;
 	groupCreated = false;
+	/**
+	* Last-seen failure context per message id, populated when an in-process
+	* handler throws in {@link processEntry}. Consumed (and cleared) by
+	* {@link moveToDlq} so the dead-letter envelope carries the actual error
+	* message instead of opaque "reclaimed without context". Bounded by
+	* `maxRetries × consumer-throughput` — entries are deleted on ack and
+	* on DLQ write, so the map naturally drains.
+	*/
+	failureContext = /* @__PURE__ */ new Map();
+	/** One-shot guard so the "client lacks xrange" warning fires once per process. */
+	xrangeWarningEmitted = false;
 	constructor(redis, options = {}) {
 		this.redis = redis;
 		this.stream = options.stream ?? "arc:events";
@@ -29,6 +53,8 @@ var RedisStreamTransport = class {
 		this.deadLetterStream = options.deadLetterStream ?? "arc:events:dlq";
 		this.maxLen = options.maxLen ?? 1e4;
 		this.maxPayloadBytes = options.maxPayloadBytes ?? 1e6;
+		this.externalLifecycle = options.externalLifecycle ?? false;
+		this.closeTimeoutMs = options.closeTimeoutMs ?? 1e3;
 		this.logger = options.logger ?? console;
 	}
 	async publish(event) {
@@ -55,9 +81,10 @@ var RedisStreamTransport = class {
 		if (!this.running) {
 			await this.ensureGroup();
 			this.running = true;
-			this.pollPromise = this.pollLoop().catch((err) => {
+			const myGen = ++this.generation;
+			this.pollPromise = this.pollLoop(myGen).catch((err) => {
 				this.logger.error("[RedisStreamTransport] Poll loop crashed:", err);
-				this.running = false;
+				if (this.generation === myGen) this.running = false;
 			});
 		}
 		return () => {
@@ -66,16 +93,59 @@ var RedisStreamTransport = class {
 				set.delete(handler);
 				if (set.size === 0) this.handlers.delete(pattern);
 			}
-			if (this.handlers.size === 0 && this.running) this.running = false;
+			if (this.handlers.size === 0 && this.running) {
+				this.running = false;
+				this.generation++;
+			}
 		};
 	}
+	/**
+	* Stop polling and release transport state.
+	*
+	* **Two close contracts** — pick the one that matches your deployment:
+	*
+	* 1. **Default (`externalLifecycle: false`) — strict bounded close.**
+	*    `close()` waits up to `closeTimeoutMs` for the in-flight
+	*    `XREADGROUP BLOCK` to drain. On timeout it calls `redis.disconnect()`
+	*    (or `quit()` if the client lacks `disconnect`) to break the BLOCK
+	*    immediately, then awaits the loop's exit. After `close()` returns
+	*    the transport is fully closed and the connection is released.
+	*
+	* 2. **`externalLifecycle: true` — bounded RETURN, background drain.**
+	*    Arc must NOT touch a connection it doesn't own. `close()` returns
+	*    within `closeTimeoutMs`, but the poll loop is left to drain on its
+	*    own when its outstanding `XREADGROUP BLOCK` returns (up to
+	*    `blockTimeMs`). Arc silently absorbs the loop's eventual completion
+	*    so the host doesn't see unhandled rejections / log spam against a
+	*    transport it considers closed. The host's own `redis.quit()` /
+	*    process exit is what ultimately tears the connection down.
+	*
+	*    Practical implication: under `externalLifecycle: true`, set
+	*    `blockTimeMs` low (e.g. 500ms) so the background drain window is
+	*    short. The transport is "closed enough" to stop dispatching to
+	*    handlers (handlers map is cleared and generation is bumped) but is
+	*    not "fully closed" in the connection-lifecycle sense until the host
+	*    closes the underlying client.
+	*
+	* In both modes the generation counter is bumped, so a follow-up
+	* `subscribe()` spawns a fresh poll loop with a new generation — the
+	* stale loop exits on its next iteration and never overlaps the new one.
+	*/
 	async close() {
 		this.running = false;
+		this.generation++;
 		this.handlers.clear();
 		if (this.pollPromise) {
-			await this.pollPromise;
+			if (await Promise.race([this.pollPromise.then(() => "drained"), this.sleep(this.closeTimeoutMs).then(() => "timeout")]) === "timeout") if (!this.externalLifecycle) {
+				if (typeof this.redis.disconnect === "function") this.redis.disconnect();
+				else await this.redis.quit().catch((err) => {
+					this.logger.error("[RedisStreamTransport] quit() during close raced:", err);
+				});
+				await this.pollPromise.catch(() => void 0);
+			} else this.pollPromise.catch(() => void 0);
 			this.pollPromise = null;
 		}
+		if (!this.externalLifecycle) await this.redis.quit().catch(() => void 0);
 	}
 	async ensureGroup() {
 		if (this.groupCreated) return;
@@ -86,12 +156,12 @@ var RedisStreamTransport = class {
 		}
 		this.groupCreated = true;
 	}
-	async pollLoop() {
-		while (this.running) try {
+	async pollLoop(myGen) {
+		while (this.running && this.generation === myGen) try {
 			await this.claimPending();
 			await this.readNewMessages();
 		} catch (err) {
-			if (this.running) {
+			if (this.running && this.generation === myGen) {
 				this.logger.error("[RedisStreamTransport] Poll error:", err);
 				await this.sleep(1e3);
 			}
@@ -123,39 +193,38 @@ var RedisStreamTransport = class {
 		}
 	}
 	async processEntry(messageId, fields) {
-		const fieldMap = /* @__PURE__ */ new Map();
-		for (let i = 0; i < fields.length; i += 2) fieldMap.set(fields[i], fields[i + 1]);
-		const eventType = fieldMap.get("type");
-		const rawData = fieldMap.get("data");
-		if (!eventType || !rawData) {
-			await this.redis.xack(this.stream, this.group, messageId);
-			return;
-		}
-		let event;
-		try {
-			const parsed = JSON.parse(rawData, (key, value) => {
-				if (key === "timestamp" && typeof value === "string") return new Date(value);
-				return value;
-			});
-			if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string" || !parsed.meta?.id) {
-				this.logger.warn("[RedisStreamTransport] Malformed event — missing type or meta.id, acking and skipping");
-				await this.redis.xack(this.stream, this.group, messageId);
-				return;
-			}
-			event = parsed;
-		} catch {
+		const event = parseStreamFields(fields);
+		if (!event) {
+			this.logger.warn(`[RedisStreamTransport] Malformed entry ${messageId} — missing type/data or invalid JSON, acking and skipping`);
 			await this.redis.xack(this.stream, this.group, messageId);
 			return;
 		}
 		const matchingHandlers = this.getMatchingHandlers(event.type);
 		let allSucceeded = true;
+		let lastError;
+		let lastHandlerName;
 		for (const handler of matchingHandlers) try {
 			await handler(event);
 		} catch (err) {
 			allSucceeded = false;
+			lastError = err instanceof Error ? err : new Error(String(err));
+			lastHandlerName = handler.name || lastHandlerName;
 			this.logger.error(`[RedisStreamTransport] Handler error for ${event.type}:`, err);
 		}
-		if (allSucceeded) await this.redis.xack(this.stream, this.group, messageId);
+		if (allSucceeded) {
+			await this.redis.xack(this.stream, this.group, messageId);
+			this.failureContext.delete(messageId);
+			return;
+		}
+		const now = /* @__PURE__ */ new Date();
+		const prior = this.failureContext.get(messageId);
+		this.failureContext.set(messageId, {
+			error: lastError ? toErrorRecord(lastError) : { message: "handler returned without acking — no error captured" },
+			firstFailedAt: prior?.firstFailedAt ?? now,
+			lastFailedAt: now,
+			attempts: (prior?.attempts ?? 0) + 1,
+			handlerName: lastHandlerName ?? prior?.handlerName
+		});
 	}
 	getMatchingHandlers(eventType) {
 		const matched = [];
@@ -173,19 +242,123 @@ var RedisStreamTransport = class {
 	}
 	async moveToDlq(ids) {
 		if (this.deadLetterStream === false) {
-			for (const id of ids) await this.redis.xack(this.stream, this.group, id);
+			for (const id of ids) {
+				await this.redis.xack(this.stream, this.group, id);
+				this.failureContext.delete(id);
+			}
 			return;
 		}
 		for (const id of ids) try {
-			await this.redis.xadd(this.deadLetterStream, "*", "originalStream", this.stream, "originalId", id, "group", this.group, "failedAt", (/* @__PURE__ */ new Date()).toISOString());
+			const envelope = await this.buildDlqEnvelope(id);
+			if (!envelope) {
+				this.logger.error(`[RedisStreamTransport] DLQ for ${id}: source entry missing AND no failure context — acking to drop`);
+				await this.redis.xack(this.stream, this.group, id);
+				this.failureContext.delete(id);
+				continue;
+			}
+			await this.redis.xadd(this.deadLetterStream, "*", "type", envelope.event.type, "originalStream", this.stream, "originalId", id, "group", this.group, "data", JSON.stringify(envelope));
 			await this.redis.xack(this.stream, this.group, id);
+			this.failureContext.delete(id);
 		} catch (err) {
 			this.logger.error(`[RedisStreamTransport] DLQ write failed for ${id}:`, err);
 		}
 	}
+	/**
+	* Reconstruct a `DeadLetteredEvent` for a message id. Reads the original
+	* entry via `xrange` (when the client supports it) and merges in any
+	* in-process failure context. Returns `null` only when BOTH sources are
+	* missing — callers ack-and-drop rather than re-queuing a ghost.
+	*
+	* Graceful degradation paths:
+	*   - Client lacks `xrange` (older custom wrappers) → log once, build the
+	*     envelope from `failureContext` alone. Payload is absent but the
+	*     error reason + attempt accounting still survive.
+	*   - `xrange` throws (network blip, ACL) → same fallback.
+	*   - Source entry trimmed before DLQ write → same fallback.
+	*/
+	async buildDlqEnvelope(id) {
+		const ctx = this.failureContext.get(id);
+		let event = null;
+		if (typeof this.redis.xrange === "function") try {
+			const fields = (await this.redis.xrange(this.stream, id, id))[0]?.[1];
+			if (fields) {
+				const parsed = parseStreamFields(fields);
+				if (parsed) event = parsed;
+			}
+		} catch (err) {
+			this.logger.error(`[RedisStreamTransport] xrange for DLQ source ${id} failed:`, err);
+		}
+		else if (!this.xrangeWarningEmitted) {
+			this.xrangeWarningEmitted = true;
+			this.logger.warn("[RedisStreamTransport] Redis client lacks xrange() — DLQ envelopes will not include the original event payload. Upgrade your client (ioredis ≥4 supports it) or use a wrapper that proxies xrange to enable replay.");
+		}
+		if (!event && !ctx) return null;
+		const fallbackTime = /* @__PURE__ */ new Date();
+		return {
+			event: event ?? {
+				type: "<unknown>",
+				payload: null,
+				meta: {
+					id,
+					timestamp: fallbackTime
+				}
+			},
+			error: ctx?.error ?? { message: "exhausted retries — failure occurred on a different consumer; error context not preserved across consumer-group failover" },
+			attempts: ctx?.attempts ?? this.maxRetries,
+			firstFailedAt: ctx?.firstFailedAt ?? fallbackTime,
+			lastFailedAt: ctx?.lastFailedAt ?? fallbackTime,
+			...ctx?.handlerName ? { handlerName: ctx.handlerName } : {}
+		};
+	}
 	sleep(ms) {
 		return new Promise((resolve) => setTimeout(resolve, ms));
 	}
 };
+/**
+* Convert a thrown value into the `DeadLetteredEvent.error` shape — message
+* always present, optional `code` (string only) and `stack`. Centralised so
+* the failure-context tracker and the DLQ envelope writer agree.
+*/
+function toErrorRecord(err) {
+	const e = err instanceof Error ? err : new Error(String(err));
+	const code = e.code;
+	return {
+		message: e.message,
+		...typeof code === "string" ? { code } : {},
+		...e.stack ? { stack: e.stack } : {}
+	};
+}
+/**
+* Parse a Redis Stream entry's flat `[key, value, key, value, ...]` field
+* array into a typed `DomainEvent`, or `null` when the entry is malformed
+* (missing `type` / `data`, unparseable JSON, or missing required event
+* structure).
+*
+* Pure on purpose — used by both `processEntry` (the live consumer path)
+* and `buildDlqEnvelope` (the dead-letter writer). Keeping the parse logic
+* in one place avoids the silent drift class that produced the original
+* "DLQ has no payload" bug.
+*/
+function parseStreamFields(fields) {
+	let eventType;
+	let rawData;
+	for (let i = 0; i < fields.length; i += 2) {
+		const key = fields[i];
+		const value = fields[i + 1];
+		if (key === "type") eventType = value;
+		else if (key === "data") rawData = value;
+	}
+	if (!eventType || !rawData) return null;
+	try {
+		const parsed = JSON.parse(rawData, (key, value) => {
+			if (key === "timestamp" && typeof value === "string") return new Date(value);
+			return value;
+		});
+		if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string" || !parsed.meta?.id) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
 //#endregion
 export { RedisStreamTransport };

package/dist/events/transports/redis.d.mts

@@ -1,4 +1,4 @@
-import { i as EventLogger, n as DomainEvent, o as EventTransport, r as EventHandler } from "../../EventTransport-CfVEGaEl.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-CT_52aWU.mjs";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {

package/dist/factory/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-BH7dEGvU.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-BvqwCCSx.mjs";
 import { FastifyInstance } from "fastify";
 
 //#region src/factory/createApp.d.ts
@@ -14,7 +14,7 @@ import { FastifyInstance } from "fastify";
  * 4. Arc core (fastify.arc, events)
  * 5. Arc plugins (requestId, health, caching, SSE, metrics, versioning)
  * 6. Auth (scope decoration, auth strategy, elevation, error handler)
- * 7. plugins()        — user infra (DB, docs, webhooks)
+ * 7. plugins()        — user infra (DB, data, webhooks)
  * 8. bootstrap[]      — domain init (singletons, event handlers)
  * 9. resources[]      — auto-discovered routes (prefix + skipGlobalPrefix)
  * 10. afterResources() — post-registration wiring

package/dist/factory/index.mjs

@@ -1,5 +1,5 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-BFxtdKy6.mjs";
-import { t as loadResources } from "../loadResources-CPpkyKfM.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-XX2-N0Yd.mjs";
+import { t as loadResources } from "../loadResources-DBMQg_Aj.mjs";
 //#region src/factory/edge.ts
 /**
 * Convert a Fastify app into a Web Standards fetch handler.

package/dist/{fields-C8Y0XLAu.d.mts → fields-COhcH3fk.d.mts}

@@ -1,4 +1,4 @@
-import { r as RequestScope } from "./types-tgR4Pt8F.mjs";
+import { i as RequestScope } from "./types-CTYvcwHe.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/types.d.ts
@@ -134,7 +134,7 @@ interface PermissionResult {
 type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
 /**
  * Optional metadata attached to permission check functions.
- * Used for OpenAPI docs, introspection, and route-level auth decisions.
+ * Used for OpenAPI data, introspection, and route-level auth decisions.
  *
  * Each helper from `permissions/index.ts` writes its own discriminating tag
  * so downstream tooling (OpenAPI generator, MCP resource builder, route
@@ -173,6 +173,27 @@ interface PermissionCheckMeta {
    * (e.g. from route params).
    */
   _orgInScopeTarget?: string | ((ctx: PermissionContext) => string | undefined);
+  /**
+   * Set by requireDPoP() — the inbound credential must be sender-constrained
+   * via DPoP (RFC 9449), with `scope.dpopJkt` set by the authenticate
+   * function after a successful proof verification.
+   */
+  _dpopRequired?: boolean;
+  /**
+   * Set by requireMandate() — the capability string the mandate on
+   * `scope.mandate` must authorize (e.g. `payment.charge`, `data.export`).
+   */
+  _mandateCapability?: string;
+  /**
+   * Set by requireAgentScope() — composite descriptor for AI-agent flows.
+   * Tools (audit, OpenAPI, MCP) can render the full agent-auth requirement
+   * in one read instead of unpacking three separate metadata fields.
+   */
+  _agentScope?: {
+    capability: string;
+    scopes?: readonly string[];
+    dpop: boolean;
+  };
 }
 //#endregion
 //#region src/permissions/fields.d.ts

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as beforeUpdate, Sn as beforeDelete, Tn as defineHook, _n as HookSystemOptions, bn as afterUpdate, dn as HookContext, fn as HookHandler, gn as HookSystem, hn as HookRegistration, mn as HookPhase, pn as HookOperation, un as DefineHookOptions, vn as afterCreate, wn as createHookSystem, xn as beforeCreate, yn as afterDelete } from "../index-6u4_Gg6G.mjs";
+import { An as afterUpdate, Cn as HookOperation, Dn as HookSystemOptions, En as HookSystem, Fn as defineHook, Mn as beforeDelete, Nn as beforeUpdate, On as afterCreate, Pn as createHookSystem, Sn as HookHandler, Tn as HookRegistration, bn as DefineHookOptions, jn as beforeCreate, kn as afterDelete, wn as HookPhase, xn as HookContext } from "../index-BtW7qYwa.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/hooks/index.mjs

@@ -1,2 +1,2 @@
-import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-CGsMd6oK.mjs";
+import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-Iiebom92.mjs";
 export { HookSystem, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,7 +1,7 @@
-import { jn as RepositoryLike } from "../index-6u4_Gg6G.mjs";
-import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-CkkWm5uR.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-Cm1gnRDf.mjs";
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-DfLGcus7.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-DiMkdHEl.mjs";
 import { FastifyPluginAsync } from "fastify";
+import { RepositoryLike } from "@classytic/repo-core/adapter";
 
 //#region src/idempotency/idempotencyPlugin.d.ts
 interface IdempotencyPluginOptions {

package/dist/idempotency/index.mjs

@@ -1,28 +1,9 @@
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-BhrzxvyQ.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-BkIN9-vu.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { update } from "@classytic/repo-core/update";
 //#region src/idempotency/repository-idempotency-adapter.ts
-/**
-* RepositoryLike → IdempotencyStore adapter.
-*
-* Maps the idempotency store's verbs (get / set / tryLock / unlock / delete /
-* deleteByPrefix / findByPrefix) onto arc's canonical repository primitives
-* (`getOne` / `deleteMany` / `findOneAndUpdate`). `idempotencyPlugin` wraps
-* a passed repository with this helper when you use the `{ repository }`
-* option; the function is also re-exported from `@classytic/arc/idempotency`
-* so consumers can build and decorate the store (metrics, tracing, key
-* namespacing) before passing it via `store:`.
-*
-* Portability: filters compose via `@classytic/repo-core/filter` builders
-* (`and` / `or` / `eq` / `gt` / `lt` / `exists` / `startsWith`) and updates
-* via `@classytic/repo-core/update` (`update({ set, unset, setOnInsert })`).
-* Both IRs compile to Mongo operators on mongokit, SQL predicates on
-* sqlitekit / pgkit, and `WhereInput` / `update` on prismakit. The store
-* therefore runs identically on every backend that implements the
-* `StandardRepo.findOneAndUpdate` + `getOne` + `deleteMany` surface.
-*/
 function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	const missing = [];
 	if (typeof repository.getOne !== "function") missing.push("getOne");

package/dist/idempotency/redis.d.mts

@@ -1,2 +1,2 @@
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-Cm1gnRDf.mjs";
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-DiMkdHEl.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/idempotency/redis.mjs

@@ -218,7 +218,7 @@ function upstashAsIdempotencyClient(client) {
 			const keyCount = _numKeys;
 			const keys = args.slice(0, keyCount).map(String);
 			const rest = args.slice(keyCount);
-			return client.eval(script, keys, rest);
+			return client.eval?.(script, keys, rest);
 		} : void 0,
 		async quit() {
 			return "OK";

package/dist/{index-BYCqHCVu.d.mts → index-BTqLEvhu.d.mts}

@@ -1,8 +1,168 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-Da0r7Lna.mjs";
-import { r as RequestScope } from "./types-tgR4Pt8F.mjs";
-import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-C8Y0XLAu.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-beEtJyWM.mjs";
+import { i as RequestScope, n as Mandate } from "./types-CTYvcwHe.mjs";
+import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-COhcH3fk.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
+//#region src/permissions/agent.d.ts
+/**
+ * Require a sender-constrained credential — the inbound token MUST carry a
+ * DPoP proof (RFC 9449) bound to a known key. Arc reads `scope.dpopJkt` (the
+ * JWK SHA-256 thumbprint per RFC 7638); your `authenticate` function performs
+ * the cryptographic `jose.dpop.verify(...)` and sets the field on success.
+ *
+ * **Pass behavior:**
+ * - `service` scope where `dpopJkt` is set → grant
+ * - `elevated` scope → grant (platform admin bypass)
+ * - Anything else → deny with a clear reason
+ *
+ * Use for high-value endpoints where bearer-token replay must be impossible:
+ * payment charges, data exports, account-takeover-class admin actions.
+ *
+ * @example
+ * ```typescript
+ * permissions: { charge: allOf(requireServiceScope('payment.write'), requireDPoP()) }
+ * ```
+ */
+declare function requireDPoP<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
+/**
+ * Options for `requireMandate(capability, opts)`.
+ */
+interface RequireMandateOptions<TDoc = Record<string, unknown>> {
+  /**
+   * Custom validator for the mandate's numeric ceiling against the inbound
+   * request. Arc passes the request body / params; you decide whether the
+   * action stays within the mandate's `cap`.
+   *
+   * Return `true` to accept, `false` (or a string reason) to deny. When
+   * omitted, arc skips amount validation — useful for boolean-capability
+   * mandates where presence of the mandate IS the authorization (no cap).
+   *
+   * @example
+   * ```typescript
+   * validateAmount: (ctx, mandate) => {
+   *   const amount = (ctx.data as { amount?: number })?.amount ?? 0;
+   *   if (amount <= (mandate.cap ?? 0)) return true;
+   *   return `Amount ${amount} exceeds mandate cap ${mandate.cap}`;
+   * }
+   * ```
+   */
+  validateAmount?: (ctx: PermissionContext<TDoc>, mandate: Readonly<Mandate>) => boolean | string;
+  /**
+   * Resource the mandate must be bound to (`Mandate.audience`). Pass a
+   * static value or a function that derives it from the request (typically
+   * `ctx.params.id`). When set and the mandate's `audience` doesn't match,
+   * the request is denied — prevents a payment-mandate for invoice A being
+   * replayed against invoice B.
+   */
+  audience?: string | ((ctx: PermissionContext<TDoc>) => string | undefined);
+  /**
+   * Clock-skew tolerance for `Mandate.expiresAt`, in milliseconds.
+   * Default `30_000` (30s).
+   */
+  ttlGraceMs?: number;
+  /**
+   * When `true`, `elevated` scope is NOT allowed to bypass the mandate check.
+   * Defaults to `false` — platform admins normally bypass everything.
+   * Set when you genuinely want "even an admin needs a mandate" semantics
+   * (audited break-glass actions, regulated payment flows).
+   */
+  noElevatedBypass?: boolean;
+}
+/**
+ * Require a capability mandate (AP2 / x402 / MCP authorization) that
+ * authorizes the action being attempted.
+ *
+ * The mandate is set on `request.scope.mandate` by your authenticate function
+ * after verifying the inbound mandate JWT/VC. This check validates that the
+ * presented mandate covers the requested capability, hasn't expired, is bound
+ * to the right resource (when `audience` opt is set), and respects the
+ * mandate's numeric ceiling (when `validateAmount` opt is set).
+ *
+ * **Pass behavior:**
+ * - `elevated` scope → grant unless `noElevatedBypass: true`
+ * - `service` scope with mandate matching `capability`, not expired, and
+ *   passing `validateAmount` + `audience` checks → grant
+ * - Anything else → deny with a precise reason
+ *
+ * Pair with `requireDPoP()` for replay-resistance, or use the bundled
+ * `requireAgentScope(...)` to declare both at once.
+ *
+ * @example
+ * ```typescript
+ * // Single payment charge — amount must fit the mandate's cap
+ * permissions: {
+ *   pay: requireMandate('payment.charge', {
+ *     validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
+ *     audience: (ctx) => `invoice:${ctx.params?.id}`,
+ *   }),
+ * }
+ *
+ * // Boolean capability — presence of mandate is the gate
+ * permissions: {
+ *   exportData: requireMandate('data.export'),
+ * }
+ * ```
+ */
+declare function requireMandate<TDoc = Record<string, unknown>>(capability: string, opts?: RequireMandateOptions<TDoc>): PermissionCheck<TDoc>;
+/**
+ * Options for `requireAgentScope(opts)`.
+ */
+interface RequireAgentScopeOptions<TDoc = Record<string, unknown>> extends RequireMandateOptions<TDoc> {
+  /**
+   * Capability the mandate must authorize (e.g., `payment.charge`,
+   * `inbox.send`). Required.
+   */
+  capability: string;
+  /**
+   * When `true`, the inbound credential must also be DPoP-bound (RFC 9449).
+   * Defaults to `true` — sender-constrained credentials are the standard
+   * for high-value agent flows. Set `false` only when you intentionally
+   * accept bearer tokens (rare; usually a regression).
+   */
+  requireDPoP?: boolean;
+  /**
+   * Optional OAuth-style scope strings the service identity must hold in
+   * addition to the mandate (e.g., `['payment.write']`). Pairs with the
+   * mandate's narrower per-request authorization — scopes answer "ever
+   * allowed?", mandate answers "right now?".
+   */
+  scopes?: readonly string[];
+}
+/**
+ * Composite gate for AI-agent / M2M flows on protected resources.
+ *
+ * Bundles the three things every high-value agent endpoint needs:
+ * 1. **Service identity** — `scope.kind === 'service'` with `clientId`
+ * 2. **Capability mandate** — narrows what *this request* may do
+ * 3. **DPoP binding** — credential cannot be replayed from a different key
+ *
+ * Use this instead of hand-composing `allOf(requireServiceScope(...),
+ * requireMandate(...), requireDPoP())` — fewer ways to misconfigure, one
+ * meta-tag downstream tools (audit, MCP, OpenAPI) can read.
+ *
+ * @example
+ * ```typescript
+ * import { requireAgentScope } from '@classytic/arc/permissions';
+ *
+ * defineResource({
+ *   name: 'invoice',
+ *   actions: {
+ *     pay: {
+ *       handler: payInvoice,
+ *       permissions: requireAgentScope({
+ *         capability: 'payment.charge',
+ *         scopes: ['payment.write'],
+ *         requireDPoP: true,
+ *         audience: (ctx) => `invoice:${ctx.params?.id}`,
+ *         validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function requireAgentScope<TDoc = Record<string, unknown>>(opts: RequireAgentScopeOptions<TDoc>): PermissionCheck<TDoc>;
+//#endregion
 //#region src/permissions/applyPermissionResult.d.ts
 /**
  * Normalize a permission check return value (`boolean | PermissionResult`)
@@ -512,4 +672,4 @@ declare function fullPublic<TDoc = any>(overrides?: PermissionOverrides<TDoc>):
  */
 declare function readOnly<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { requireRoles as A, allOf as C, not as D, denyAll as E, when as M, applyPermissionResult as N, requireAuth as O, normalizePermissionResult as P, createOrgPermissions as S, anyOf as T, ConnectEventsOptions as _, presets_d_exports as a, PermissionEventBus as b, readOnly as c, requireOrgRole as d, requireScopeContext as f, createRoleHierarchy as g, RoleHierarchy as h, ownerWithAdminBypass as i, roles as j, requireOwnership as k, requireOrgInScope as l, requireTeamMembership as m, authenticated as n, publicRead as o, requireServiceScope as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, requireOrgMembership as u, DynamicPermissionMatrix as v, allowPublic as w, createDynamicPermissionMatrix as x, DynamicPermissionMatrixConfig as y };
+export { requireRoles as A, allOf as C, not as D, denyAll as E, RequireAgentScopeOptions as F, RequireMandateOptions as I, requireAgentScope as L, when as M, applyPermissionResult as N, requireAuth as O, normalizePermissionResult as P, requireDPoP as R, createOrgPermissions as S, anyOf as T, ConnectEventsOptions as _, presets_d_exports as a, PermissionEventBus as b, readOnly as c, requireOrgRole as d, requireScopeContext as f, createRoleHierarchy as g, RoleHierarchy as h, ownerWithAdminBypass as i, roles as j, requireOwnership as k, requireOrgInScope as l, requireTeamMembership as m, authenticated as n, publicRead as o, requireServiceScope as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, requireOrgMembership as u, DynamicPermissionMatrix as v, allowPublic as w, createDynamicPermissionMatrix as x, DynamicPermissionMatrixConfig as y, requireMandate as z };