@classytic/arc 2.8.4 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.4",
+  "version": "2.9.1",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -20,6 +20,10 @@
       "types": "./dist/types/index.d.mts",
       "default": "./dist/types/index.mjs"
     },
+    "./types/storage": {
+      "types": "./dist/types/storage.d.mts",
+      "default": "./dist/types/storage.mjs"
+    },
     "./adapters": {
       "types": "./dist/adapters/index.d.mts",
       "default": "./dist/adapters/index.mjs"
@@ -36,6 +40,14 @@
       "types": "./dist/presets/multiTenant.d.mts",
       "default": "./dist/presets/multiTenant.mjs"
     },
+    "./presets/files-upload": {
+      "types": "./dist/presets/filesUpload.d.mts",
+      "default": "./dist/presets/filesUpload.mjs"
+    },
+    "./presets/search": {
+      "types": "./dist/presets/search.d.mts",
+      "default": "./dist/presets/search.mjs"
+    },
     "./auth": {
       "types": "./dist/auth/index.d.mts",
       "default": "./dist/auth/index.mjs"
@@ -76,10 +88,6 @@
       "types": "./dist/audit/index.d.mts",
       "default": "./dist/audit/index.mjs"
     },
-    "./audit/mongodb": {
-      "types": "./dist/audit/mongodb.d.mts",
-      "default": "./dist/audit/mongodb.mjs"
-    },
     "./docs": {
       "types": "./dist/docs/index.d.mts",
       "default": "./dist/docs/index.mjs"
@@ -92,10 +100,6 @@
       "types": "./dist/idempotency/redis.d.mts",
       "default": "./dist/idempotency/redis.mjs"
     },
-    "./idempotency/mongodb": {
-      "types": "./dist/idempotency/mongodb.d.mts",
-      "default": "./dist/idempotency/mongodb.mjs"
-    },
     "./events": {
       "types": "./dist/events/index.d.mts",
       "default": "./dist/events/index.mjs"
@@ -116,6 +120,10 @@
       "types": "./dist/testing/index.d.mts",
       "default": "./dist/testing/index.mjs"
     },
+    "./testing/storage": {
+      "types": "./dist/testing/storageContract.d.mts",
+      "default": "./dist/testing/storageContract.mjs"
+    },
     "./policies": {
       "types": "./dist/policies/index.d.mts",
       "default": "./dist/policies/index.mjs"
@@ -227,7 +235,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.6.0",
+    "@classytic/mongokit": ">=3.8.0",
     "@classytic/streamline": ">=2.1.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -346,7 +354,7 @@
   "devDependencies": {
     "@better-auth/mongo-adapter": "^1.6.2",
     "@biomejs/biome": "^2.4.11",
-    "@classytic/mongokit": "file:../../packages/mongokit/classytic-mongokit-3.6.0.tgz",
+    "@classytic/mongokit": "^3.8.0",
     "@classytic/streamline": "^2.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
@@ -364,7 +372,11 @@
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",
     "better-auth": "^1.6.2",
+    "bullmq": "^5.73.5",
+    "dotenv": "^17.4.2",
+    "fast-check": "^4.6.0",
     "fastify-raw-body": "^5.0.0",
+    "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.4.1",
     "mongodb": "^7.1.0",

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.8.1
+version: 2.9.1
 license: MIT
 metadata:
   author: Classytic
-  version: "2.8.0"
+  version: "2.9.1"
 tags:
   - fastify
   - rest-api
@@ -68,6 +68,22 @@ await app.register(productResource.toPlugin());
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
+## v2.9 Security Defaults (breaking)
+
+- **Field-write perms: `reject` (default)** — requests carrying non-writable fields get 403 with denied-field list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **multiTenant injects org on UPDATE** — body-supplied `organizationId` overwritten with caller's scope. Closes tenant-hop vector.
+- **Elevation always emits `arc.scope.elevated` event** — audit via `fastify.events.subscribe(...)`.
+- **`verifySignature(body, ...)` throws on parsed body** — pass `req.rawBody`, not `req.body`.
+- **Upload `sanitizeFilename`** — strict by default (no `/ \ .. \0 >255ch`). Pass `false` / `'*'` / custom fn to relax.
+- **Idempotency `namespace`** option for shared-store prod+canary deployments.
+
+## Removed in v2.9
+
+- `createActionRouter`, `buildActionBodySchema` — use `actions` on `defineResource`
+- `ResourceConfig.onRegister` — use `actions` or resource `hooks`
+- `AdditionalRoute` type + `resource.additionalRoutes` field — use `RouteDefinition` and `resource.routes` (single source of truth; no normalised mirror)
+- `wrapHandler` on route defs — derived from `!route.raw` at use-site (set `raw: true` to opt out of the arc pipeline)
+
 ## defineResource()
 
 Single API to define a full REST resource:
@@ -109,7 +125,7 @@ const productResource = defineResource({
     { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
   ],
 
-  // Actions (replaces onRegister + createActionRouter)
+  // Actions — single POST /:id/action endpoint, discriminated on `action` body field
   actions: {
     approve: async (id, data, req) => service.approve(id, req.user._id),
     cancel: {
@@ -489,6 +505,8 @@ permissions: { list: acl.canAction('product', 'read') }
 | `multiTenant` | none (middleware) | — | `{ tenantField }` OR `{ tenantFields: TenantFieldSpec[] }` (2.7.1+) |
 | `audited` | none (middleware) | — | — |
 | `bulk` | POST/PATCH/DELETE /bulk | — | `{ operations?, maxCreateItems? }` |
+| `filesUpload` | POST /upload, GET /:id, DELETE /:id | — (uses `Storage` adapter) | `{ storage, sanitizeFilename?, allowedMimeTypes?, maxFileSize? }` |
+| `search` | POST /search, /search-similar, /embed (opt-in) | — | `{ repository?, search?, similar?, embed?, routes? }` |
 
 ```typescript
 // Single-field (default, backwards compatible)
@@ -546,7 +564,7 @@ Default is `'_id'`. Override for resources keyed by a business identifier (UUID,
 defineResource({
   name: 'job',
   adapter: createMongooseAdapter(JobModel, jobRepository),
-  idField: 'jobId',     // ← one line
+  idField: 'jobId',     // ← one line (or omit and auto-derive from repository.idField — see below)
 });
 
 // GET /jobs/job-5219f346-a4d  → controller runs { jobId: 'job-5219f346-a4d' }
@@ -559,10 +577,66 @@ Changes all three layers:
 - **OpenAPI docs** — `spec.paths['/jobs/{id}']` emits a plain string `id` with description
 - **MCP tools** — auto-generated CRUD tools use `idField` transparently
 
-URL path segment stays `:id` (not `:jobId`) — clients send the ID value, Arc maps it server-side. User-provided `openApiSchemas.params` still overrides everything.
+**Auto-derive from repository** (2.7.x+). If you don't set `idField` on `defineResource` but your `adapter.repository` exposes one (e.g. `new Repository(Model, [], {}, { idField: 'slug' })`), Arc picks it up automatically. Configure in one place, not two.
+
+**URL path segment is ALWAYS `:id` and `req.params.id` is ALWAYS named `id`** — regardless of what `idField` is set to. `idField` controls the *lookup field*, not the *URL parameter name*. This is the same convention Stripe / GitHub / most REST APIs use:
+
+```typescript
+// idField: 'slug'
+// Client sends:  POST /agents/sadman/action
+// In handler:    req.params.id === 'sadman'       ← always keyed 'id'
+//                repo.update(id, data)             ← mongokit resolves by slug via repo.idField
+```
+
+This applies to CRUD routes (`GET/PATCH/DELETE /:id`), action routes (`POST /:id/action`), and any `routes: [...]` entries that use `:id`.
+
+**Common confusion pattern.** A 404 on `PATCH /agents/sadman` when `GET /agents/sadman` returns 200 looks like an `idField` bug but usually isn't. Check whether your **update permission** returns `filters` — arc merges those into the compound DB lookup (`{ slug: 'sadman', ...filters }`), and a filter that excludes the doc is what's returning null. Fix is in the permission, not `idField`.
+
+User-provided `openApiSchemas.params` still overrides everything.
 
 For custom adapters, honor the new `AdapterSchemaContext` passed to `generateSchemas(options, context?)` to emit the right `params.id` pattern from the start. Legacy adapters still work — Arc's safety net strips mismatched ObjectId patterns automatically.
 
+## searchPreset (text + vector + embed)
+
+Backend-agnostic routes for Elasticsearch / OpenSearch / Algolia / Typesense / Atlas `$vectorSearch` / Pinecone / Qdrant / Milvus. Opt-in per section; `mcp: false` skips per path.
+
+```typescript
+import { searchPreset } from '@classytic/arc/presets/search';
+
+// A — auto-wire from a repo with search/searchSimilar/embed methods
+// (mongokit's elasticSearchPlugin + vectorPlugin register exactly these).
+// Each method's native calling convention is honoured:
+//   search(query, options)          — positional (elasticSearchPlugin)
+//   searchSimilar(VectorSearchParams) — single object (vectorPlugin)
+//   embed(input)                    — single arg (vectorPlugin)
+searchPreset({
+  repository: productRepo,
+  search: true,    // POST /search         → repo.search(body.query, body)
+  similar: true,   // POST /search-similar → repo.searchSimilar(body)
+  // embed omitted → /embed not mounted
+})
+
+// B — external backends + custom path + Zod schema
+searchPreset({
+  search: {
+    path: '/full-text',
+    schema: { body: z.object({ q: z.string().min(1) }) },
+    handler: (req) => elastic.search({ index: 'products', q: req.body.q }),
+  },
+  similar: { handler: (req) => pinecone.query({ vector: req.body.vector, topK: 10 }), mcp: false },
+  routes: [  // bespoke paths
+    { method: 'GET', path: '/autocomplete', permissions: allowPublic(),
+      handler: (req) => algolia.suggest((req.query as { q: string }).q) },
+  ],
+})
+```
+
+**Defaults:** search/similar → POST, permissions fall back to resource `list` → `allowPublic()`. Embed → POST + `requireAuth()`. Every field (`path`, `method`, `schema`, `permissions`, `mcp`, `summary`, `tags`, `operation`) is overridable per section. Zod v4 schemas auto-convert to JSON Schema for both Fastify validation and OpenAPI.
+
+**MCP namespacing:** tool names are `{op}_{resource}` — many resources can register their own searchPreset under one `mcpPlugin` endpoint without colliding (`product_search`, `order_search`, …).
+
+**When to use `routes` directly instead:** one-off search endpoints, or when you want full control without the preset's defaults.
+
 ## QueryCache
 
 TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
@@ -652,7 +726,11 @@ CRUD events auto-emit: `{resource}.created`, `{resource}.updated`, `{resource}.d
 
 **Transports:** Memory (default) | Redis Pub/Sub (fire-and-forget) | Redis Streams (durable, at-least-once, consumer groups, DLQ)
 
-**Event Outbox** — at-least-once delivery via transactional outbox pattern. Arc ships `OutboxStore` interface + `MemoryOutboxStore` (dev). You implement the store for your DB (Mongoose, Drizzle, Knex, etc.). Cleanup via optional `purge()` contract or native DB tools (TTL index, pg_cron, key expiry).
+**Event Outbox** — at-least-once delivery via transactional outbox pattern. Pass `repository: RepositoryLike` (mongokit / prismakit / custom) for production, or `store: MemoryOutboxStore()` for dev. Arc adapts the repo to the `OutboxStore` contract internally — `create` / `findAll` / `deleteMany` / `findOneAndUpdate` cover save, claim, ack, fail, DLQ.
+
+**Event contract (v2.9):** `EventMeta` = `id`, `timestamp`, optional `schemaVersion`, `correlationId`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `resource`, `resourceId`, `userId`, `organizationId`, `aggregate: { type, id }`. `createChildEvent(parent, ...)` inherits correlation/causation/source/idempotencyKey; aggregate stays explicit. `DeadLetteredEvent<T>` + optional `transport.deadLetter()` for typed DLQ. `withRetry({ transport })` auto-routes exhausted events — no custom plumbing for Kafka/SQS. `@classytic/primitives` mirrors these shapes — arc is source of truth.
+
+**Outbox (v2.9):** `EventOutbox.store()` auto-maps `meta.idempotencyKey` → `dedupeKey`. `new EventOutbox({ failurePolicy: ({ attempts }) => ({ retryAt, deadLetter }) })` centralises retry/DLQ. `outbox.getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`. `RelayResult.deadLettered` for per-batch DLQ count. Durable store: `new EventOutbox({ repository: new Repository(OutboxModel), transport })` (v2.9.1) — multi-worker claim, session-threaded writes, and dedupe semantics come from the repo's backing kit.
 
 ## Factory — createApp()
 
@@ -948,7 +1026,7 @@ defineResource({ name: 'order', audit: true });
 defineResource({ name: 'payment', audit: { operations: ['delete'] } });
 defineResource({ name: 'product' }); // not audited
 
-// Manual custom() for MCP/additionalRoutes/read auditing
+// Manual custom() for MCP tools / custom routes / read auditing
 app.post('/orders/:id/refund', async (req) => {
   await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
 });
@@ -980,7 +1058,6 @@ permissions: {
 
 ```typescript
 // Typed request for raw routes — no more (req as any).user
-// v2.8: `raw: true` replaces `wrapHandler: false` (wrapHandler still works but is deprecated)
 import type { ArcRequest } from '@classytic/arc';
 handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
 
@@ -996,15 +1073,16 @@ const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
 import { createDomainError } from '@classytic/arc';
 throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
 
-// Resource lifecycle hook — wire singletons during registration
-// v2.8: for action routes, use `actions` config instead of onRegister + createActionRouter
-defineResource({ name: 'notification', onRegister: (f) => setSseManager(f.sseManager) });
+// Custom routes — always `routes: [...]` with optional `raw: true` for non-JSON
+defineResource({
+  routes: [{ method: 'GET', path: '/stats', handler: 'getStats', permissions: allowPublic() }],
+});
 
 // SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
-additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+routes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
 
-// SSE streaming — auto headers + bypasses response wrapper
-additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
+// SSE streaming — raw: true + stream the response
+routes: [{ method: 'GET', path: '/stream', raw: true, handler: async (req, reply) => reply.send(stream) }]
 ```
 
 ## DX Helpers (v2.7.3+)

package/skills/arc/references/auth.md

@@ -225,6 +225,100 @@ auth: {
 }
 ```
 
+## Service Identity (Machine Principals)
+
+Arc distinguishes **machine callers** (API clients, spawned agents, cron workers) from **human users** via `RequestScope.service` — a first-class scope kind with `clientId` + OAuth-style `scopes`. Any auth mechanism (arc JWT, API keys, Better Auth client credentials, mTLS, gateway headers) can install it; arc does not ship a "service token" issuer — the app picks its credential flow and maps the result to scope.
+
+Install service scope from your `authenticate` callback — arc's default JWT verify installs `member` scope by design, so custom authenticators are the extension point:
+
+```typescript
+await createApp({
+  auth: {
+    type: 'jwt',
+    jwt: { secret: process.env.JWT_SECRET! },
+    authenticate: async (request, { jwt }) => {
+      const token = request.headers.authorization?.slice(7);
+      if (!token) return null;
+      const decoded = jwt.verify(token) as {
+        clientId?: string; userId?: string;
+        organizationId?: string; scopes?: string[];
+      };
+      // Machine principal — clientId present, no human user record.
+      if (decoded.clientId) {
+        request.scope = {
+          kind: 'service',
+          clientId: decoded.clientId,
+          organizationId: decoded.organizationId ?? '',
+          scopes: decoded.scopes ?? [],
+        };
+        return { clientId: decoded.clientId };   // returned value → request.user
+      }
+      // Human principal — fall through to user lookup.
+      return await User.findById(decoded.userId);
+    },
+  },
+});
+```
+
+Gate routes on service identity using the scope helpers + a permission builder:
+
+```typescript
+import { isService, getClientId, getServiceScopes } from '@classytic/arc/scope';
+import type { PermissionCheck } from '@classytic/arc/permissions';
+
+const requireScope = (scope: string): PermissionCheck => (ctx) => {
+  if (!isService(ctx.request.scope)) return { granted: false, reason: 'service only' };
+  const has = getServiceScopes(ctx.request.scope).includes(scope);
+  return has ? { granted: true } : { granted: false, reason: `missing scope: ${scope}` };
+};
+
+defineResource({
+  name: 'order',
+  permissions: { create: requireScope('orders:write') },
+});
+```
+
+**Mixing humans and services on the same route** — compose arc's builders:
+
+```typescript
+// Humans with 'editor' role OR services with 'orders:write' scope
+permissions: {
+  create: anyOf(requireOrgRole('editor'), requireScope('orders:write')),
+}
+```
+
+**Audit differentiation** — because `scope.kind === 'service'` carries `clientId` instead of `userId`, your audit plugin's `actor` resolver can tag machine actions distinctly:
+
+```typescript
+auditPlugin({
+  actor: (request) =>
+    isService(request.scope)
+      ? { kind: 'service', clientId: getClientId(request.scope) }
+      : { kind: 'user', userId: getUserId(request.scope) },
+});
+```
+
+**Rate-limit separation** — gate a separate bucket per `clientId` so one noisy agent can't starve humans in the same org:
+
+```typescript
+rateLimit: {
+  keyGenerator: (req) =>
+    isService(req.scope) ? `svc:${getClientId(req.scope)}` : `org:${getOrgId(req.scope)}`,
+}
+```
+
+**Credential-flow choice is the app's** — arc does not pick for you:
+
+| Flow | Wire via `authenticate` callback |
+|---|---|
+| Arc JWT with `clientId` claim | example above |
+| API key in header (DB lookup) | read `x-api-key`, look up client, set `scope` to service |
+| Better Auth client credentials | `auth.api.getSession({ headers })`, detect client-credential grant |
+| mTLS cert DN → client | read cert from terminator header, map DN → `clientId` |
+| OAuth2 client-credentials | verify token via introspection endpoint |
+
+All five produce the same downstream primitive: `RequestScope.service`. Permission builders, audit hooks, and rate-limit keys compose the same way regardless.
+
 ## Microservice Gateway Pattern
 
 ```

package/skills/arc/references/events.md

@@ -116,22 +116,73 @@ const unsub = await fastify.events.subscribe('order.created', handler);
 unsub();
 ```
 
-## Event Structure
+## Event Structure (v2.9)
 
 ```typescript
+interface EventMeta {
+  id: string;              // UUID v4 (fresh per emit; a retry gets a new id)
+  timestamp: Date;
+  schemaVersion?: number;  // bump on payload breaking change
+  correlationId?: string;  // stable across causal chain
+  causationId?: string;    // direct parent event id
+  partitionKey?: string;   // ordering hint (Kafka/Kinesis/Streams)
+  source?: string;         // originating service/package ('commerce', 'billing')
+  idempotencyKey?: string; // cross-transport dedupe hint — stable per operation
+  resource?: string;
+  resourceId?: string;
+  userId?: string;
+  organizationId?: string;
+  aggregate?: { type: string; id: string }; // DDD aggregate marker
+}
+
 interface DomainEvent<T> {
-  type: string;          // e.g., 'order.created'
+  type: string;            // e.g., 'order.created'
   payload: T;
-  meta: {
-    id: string;          // Unique event ID
-    timestamp: Date;
-    source?: string;
-    resource?: string;
-    resourceId?: string;
-    userId?: string;
-    organizationId?: string;
-    correlationId?: string;
-  };
+  meta: EventMeta;
+}
+```
+
+**Arc is source of truth** — `@classytic/primitives/events` mirrors these shapes. Downstream packages import from primitives; arc owns evolution.
+
+### DDD aggregate narrowing
+
+`aggregate.type` is `string` in arc's base contract so it stays framework-neutral. Domain packages narrow it to a closed union via interface extension:
+
+```typescript
+// @classytic/cart
+type CartAggregateType = 'cart' | 'cart-item';
+
+interface CartEventMeta extends EventMeta {
+  aggregate?: { type: CartAggregateType; id: string };
+}
+```
+
+Unlike `correlationId` / `causationId`, `aggregate` is **not inherited** by `createChildEvent`. Child events usually belong to a different aggregate (e.g. an `order.placed` event emitted by the order aggregate spawns `inventory.reserved` owned by the inventory aggregate). Each event names its own aggregate explicitly.
+
+### Causation chains
+
+```typescript
+import { createEvent, createChildEvent } from '@classytic/arc/events';
+
+const placed = createEvent('order.placed', { orderId: 'o1' }, {
+  correlationId: req.id, userId: user.id,
+});
+
+// Downstream handler emits child — causation linked, correlation inherited:
+const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
+// reserved.meta.causationId   === placed.meta.id
+// reserved.meta.correlationId === placed.meta.correlationId
+```
+
+### Dead-letter contract
+
+```typescript
+import type { DeadLetteredEvent, EventTransport } from '@classytic/arc/events';
+
+class KafkaTransport implements EventTransport {
+  async deadLetter(dlq: DeadLetteredEvent) {
+    await producer.send({ topic: `${dlq.event.type}.DLQ`, messages: [{ value: JSON.stringify(dlq) }] });
+  }
 }
 ```
 
@@ -168,6 +219,35 @@ class KafkaTransport implements EventTransport {
 | Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
 | Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
 
+### Streams vs Pub/Sub — pick the right one
+
+Choosing wrong loses messages silently. Default to **Streams** for anything business-critical.
+
+| Requirement | Use |
+|---|---|
+| Message MUST NOT be lost (billing, payments, audit) | **Streams** |
+| Real-time notifications, OK to miss when no subscriber is up | Pub/Sub |
+| Need to replay/reprocess past events | **Streams** |
+| Multiple workers processing the same queue | **Streams** (consumer groups) |
+| Simple broadcast to live WebSocket clients | Pub/Sub |
+| Event sourcing or audit trail | **Streams** |
+| Single-instance dev | Memory |
+| At-least-once delivery with durable WAL | **Streams** + outbox pattern |
+
+**Why it matters:** Pub/Sub is fire-and-forget. If no subscriber is connected when you publish, the message is gone. Streams persist until every consumer group acknowledges them — crashes, restarts, and network blips are survivable.
+
+**Defense-in-depth:** pair `eventPlugin` with the transactional outbox (`EventOutbox` + `MemoryOutboxStore` or your own persistent store) for guaranteed delivery even if Redis is unreachable at publish time.
+
+### Redis eviction policy — required for queues and idempotency
+
+When you back events (Streams), jobs (BullMQ), idempotency, or cache with Redis, your Redis instance **must** be configured with `maxmemory-policy: noeviction`. Any other policy can silently evict in-flight stream entries or pending jobs.
+
+- **Self-hosted Redis:** `redis-cli CONFIG SET maxmemory-policy noeviction` (or set in `redis.conf`).
+- **Upstash:** free/paid DBs default to `optimistic-volatile`. You'll see `IMPORTANT! Eviction policy is optimistic-volatile. It should be "noeviction"` in BullMQ logs. **Do one of:** open a support ticket to request `noeviction`, use a dedicated DB for queues, or accept that long-idle jobs may be evicted.
+- **ElastiCache / Redis Cloud:** set the parameter group's `maxmemory-policy` to `noeviction` before pointing arc at it.
+
+For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and what you want.
+
 ## Injectable Logger
 
 All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:
@@ -270,3 +350,140 @@ const retriedHandler = withRetry(async (event) => {
 
 await fastify.events.subscribe('order.created', retriedHandler);
 ```
+
+### Auto-route exhausted events to transport.deadLetter() (v2.9)
+
+For transports with a native DLQ (Kafka DLQ topic, SQS DLQ queue, etc.), pass
+`transport` to skip custom `$deadLetter` plumbing:
+
+```typescript
+await fastify.events.subscribe(
+  'order.created',
+  withRetry(handler, {
+    maxRetries: 3,
+    transport: fastify.events.transport,  // any EventTransport with deadLetter()
+    name: 'emailProcessor',                // populates DeadLetteredEvent.handlerName
+  }),
+);
+```
+
+On exhaustion, a typed `DeadLetteredEvent` envelope (original event + error +
+attempts + first/last failure timestamps) is handed to `transport.deadLetter()`.
+`onDead` still works — both fire when both are configured.
+
+## Transactional Outbox (v2.9)
+
+**Why the outbox exists:** you write a row + publish an event in the same user
+request. If the transport (Redis/Kafka) is down at that moment, the row
+commits but the event vanishes — silent data divergence. The outbox persists
+the event in the **same DB transaction** as the row, then a background relayer
+guarantees at-least-once delivery to the transport. Multi-worker claim +
+retry/DLQ policy + dedupe make it scale.
+
+`EventOutbox` now offers centralised retry/DLQ and typed DLQ query:
+
+```typescript
+import { EventOutbox, MemoryOutboxStore, exponentialBackoff } from '@classytic/arc/events';
+
+const outbox = new EventOutbox({
+  store: new MemoryOutboxStore(),   // swap for durable store in prod
+  transport: fastify.events.transport,
+
+  // Centralised retry/DLQ — no more hand-rolled exponentialBackoff at every fail site
+  failurePolicy: ({ attempts, error }) => {
+    if (attempts >= 5) return { deadLetter: true };
+    return { retryAt: exponentialBackoff({ attempt: attempts }) };
+  },
+});
+
+// meta.idempotencyKey auto-maps to OutboxWriteOptions.dedupeKey — duplicate
+// saves with the same key are silently absorbed.
+await outbox.store(
+  createEvent('order.placed', payload, { idempotencyKey: `order:${id}:placed` }),
+);
+
+// Rich per-batch outcome — deadLettered is new in v2.9
+const result = await outbox.relayBatch();
+// { relayed, attempted, publishFailed, ackFailed, ownershipMismatches,
+//   malformed, failHookErrors, deadLettered, usedPublishMany }
+
+// Read DLQ state as typed DeadLetteredEvent[]
+const dlq = await outbox.getDeadLettered(100);
+for (const envelope of dlq) {
+  await alertOps(envelope);  // event, error, attempts, firstFailedAt, lastFailedAt
+}
+```
+
+**Store capability tiers:**
+
+| Method | Required | What you lose without it |
+|---|---|---|
+| `save`, `getPending`, `acknowledge` | ✅ | — |
+| `claimPending` | — | Multi-worker relay safety |
+| `fail` | — | Retry / DLQ / per-event failure reporting |
+| `getDeadLettered` | — | `outbox.getDeadLettered()` returns `[]` |
+| `purge` | — | App owns retention (TTL index, cron DELETE, etc.) |
+
+`MemoryOutboxStore` implements all capabilities — use it as a reference when
+writing a durable store for Postgres / DynamoDB / your DB of choice.
+
+### Durable store — pass a `RepositoryLike`
+
+Arc adapts any `Repository` (mongokit / prismakit / your own kit) to the
+`OutboxStore` contract — no dedicated subpath, no store class to
+instantiate:
+
+```typescript
+import mongoose from 'mongoose';
+import { Repository } from '@classytic/mongokit';
+import { EventOutbox, exponentialBackoff, createEvent } from '@classytic/arc/events';
+
+const OutboxModel = mongoose.model('ArcOutbox', OutboxSchema, 'arc_outbox_events');
+
+const outbox = new EventOutbox({
+  repository: new Repository(OutboxModel),
+  transport: redisTransport,
+  failurePolicy: ({ attempts }) =>
+    attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
+});
+
+// Persist event in the same DB transaction as the row
+await mongoose.connection.transaction(async (session) => {
+  await Order.create([orderDoc], { session });
+  await outbox.store(
+    createEvent('order.placed', { orderId }, { idempotencyKey: `order:${orderId}:placed` }),
+    { session },
+  );
+});
+
+// Background relayer
+setInterval(async () => {
+  const r = await outbox.relayBatch();
+  metrics.gauge('outbox.deadLettered', r.deadLettered);
+}, 1000);
+
+// Ops: read dead-letter envelopes for alerting / replay
+const dlq = await outbox.getDeadLettered(100);
+```
+
+**What you get:**
+
+- **Atomic multi-worker claim** — arc's adapter uses `findOneAndUpdate`
+  on `{ status: 'pending', visibleAt ≤ now, lease free }`. Two racing
+  relayers never see the same event; expired leases auto-recover.
+- **Session threading** — `outbox.store(event, { session })` flows
+  through `Repository.create(doc, { session })` so the event commits
+  with your business write.
+- **Dedupe** — `meta.idempotencyKey` maps to `dedupeKey`; your kit's
+  unique index (or equivalent) enforces idempotency.
+- **DLQ** — `getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`.
+  `RelayResult.deadLettered` counts per-batch transitions.
+- **Purge** — `outbox.purge(olderThanMs)` deletes delivered rows; define
+  retention via a TTL index (`deliveredAt`), a cron, or a scheduler —
+  your kit's choice.
+
+You own the schema and indexes. Recommended shape:
+`{ eventId (unique), type, payload, meta, status, attempts, leaseOwner,
+leaseExpiresAt, visibleAt, dedupeKey (unique sparse), lastError,
+createdAt, deliveredAt }` with indexes on `{ status, visibleAt }` and
+`{ deliveredAt }` (TTL).