@classytic/arc 2.31.0 → 2.33.0

package/dist/{utils-vL8BrDE2.mjs → utils-h1V_sT-t.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { m as RESERVED_QUERY_PARAMS } from "./constants-D3Dv4LAV.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { m as RESERVED_QUERY_PARAMS } from "./constants-BxCoxmiN.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError } from "./errors-Cj42AntO.mjs";
+import { t as ArcError, u as ValidationError } from "./errors-Cd_yy7aW.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 import { scheduleBackground } from "@classytic/repo-core/cache";
 //#region src/utils/circuitBreaker.ts
@@ -591,6 +591,11 @@ const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\
 * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
 */
 var ArcQueryParser = class {
+	/**
+	* PUBLIC, deliberately: `QueryResolver` reads it so it does not apply a second cap
+	* on top of this one. Three layers capping independently, lowest winning silently,
+	* is what made a 696-row chart of accounts render as 100.
+	*/
 	maxLimit;
 	defaultLimit;
 	maxRegexLength;
@@ -599,6 +604,7 @@ var ArcQueryParser = class {
 	_allowedFilterFields;
 	_allowedSortFields;
 	_allowedOperators;
+	strictFilterFields;
 	/** Allowed filter fields (used by MCP for auto-derive) */
 	allowedFilterFields;
 	/** Allowed sort fields (used by MCP for sort descriptions) */
@@ -621,6 +627,7 @@ var ArcQueryParser = class {
 		this.maxRegexLength = options.maxRegexLength ?? 200;
 		this.maxSearchLength = options.maxSearchLength ?? 200;
 		this.maxFilterDepth = options.maxFilterDepth ?? 10;
+		this.strictFilterFields = options.strictFilterFields ?? process.env.ARC_STRICT_QUERY_PARAMS === "true";
 		if (options.allowedFilterFields) {
 			this._allowedFilterFields = new Set(options.allowedFilterFields);
 			this.allowedFilterFields = options.allowedFilterFields;
@@ -787,7 +794,10 @@ var ArcQueryParser = class {
 		if (value === void 0 || value === null) return;
 		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*(?:\[[a-z]+\])?$/.test(key)) return;
 		const bareKey = key.replace(/\[[a-z]+\]$/, "");
-		if (this._allowedFilterFields && !this._allowedFilterFields.has(bareKey)) return;
+		if (this._allowedFilterFields && !this._allowedFilterFields.has(bareKey)) {
+			if (this.strictFilterFields) throw new ValidationError(`Unknown filter field: ${bareKey}. Allowed: ${[...this._allowedFilterFields].sort().join(", ")}`);
+			return;
+		}
 		if (this.exceedsDepth(value)) return;
 		if (typeof value === "object" && value !== null && !Array.isArray(value)) {
 			const operatorObj = value;
@@ -879,10 +889,31 @@ var ArcQueryParser = class {
 				},
 				limit: {
 					type: "integer",
-					description: "Number of items per page",
+					/**
+					* The cap is DOCUMENTED here, not enforced — deliberately.
+					*
+					* Both layers that handle `limit` CLAMP it: this parser
+					* (`Math.min(…, this.maxLimit)`) and `QueryResolver`. Emitting
+					* `maximum` contradicted them, because arc layers this schema as the
+					* route's `listQuery` and Fastify validates the querystring BEFORE
+					* either runs — so the clamp was unreachable and `?limit=200` became a
+					* hard 400.
+					*
+					* That combination is worse than either policy alone. Asking for more
+					* rows than allowed is a benign over-ask with an obvious right answer
+					* (give the maximum); turning it into a validation failure means a UI
+					* passing a generous page size gets NOTHING, and a caller that does not
+					* inspect the error body renders it as an empty list — a 400 disguised
+					* as "no results", which is the hardest kind to find.
+					*
+					* A deployment wanting refusal instead of clamping should say so in the
+					* parser's policy, where both halves can agree, not in a schema that
+					* silently outranks them. Mirrors the same fix in mongokit's
+					* `buildQuerySchema`.
+					*/
+					description: `Number of items per page (values above ${this.maxLimit} are capped to ${this.maxLimit})`,
 					default: this.defaultLimit,
-					minimum: 1,
-					maximum: this.maxLimit
+					minimum: 1
 				},
 				sort: {
 					type: "string",

package/dist/{validate-_KbifpHF.mjs → validate-CdQlz52F.mjs}

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

package/dist/{versioning-D_rhHfZm.d.mts → versioning-DEs-_hFi.d.mts}

@@ -1,5 +1,5 @@
 
-import { n as DomainEvent } from "./EventTransport-2uVV34WU.mjs";
+import { n as DomainEvent } from "./EventTransport-BEVP50ka.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/plugins/caching.d.ts
 interface CachingRule {

package/dist/{versioning-CHDTor3P.mjs → versioning-rZbyLVD-.mjs}

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
-import { d as createDomainError } from "./errors-Cj42AntO.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
+import { d as createDomainError } from "./errors-Cd_yy7aW.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({
@@ -31,7 +31,7 @@ const versioningPlugin = async (fastify, opts) => {
 		reply.header(responseHeader, version);
 		if (deprecatedSet.has(version)) {
 			reply.header("deprecation", "true");
-			reply.header("sunset", sunset ?? new Date(Date.now() + 2160 * 60 * 60 * 1e3).toISOString());
+			reply.header("sunset", sunset ?? new Date(Date.now() + 7776e6).toISOString());
 		}
 	});
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.31.0",
+  "version": "2.33.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -220,6 +220,10 @@
       "types": "./dist/cleanup/index.d.mts",
       "default": "./dist/cleanup/index.mjs"
     },
+    "./outbox-admin": {
+      "types": "./dist/outbox-admin/index.d.mts",
+      "default": "./dist/outbox-admin/index.mjs"
+    },
     "./testing/outbox": {
       "types": "./dist/testing/outboxStoreContract.d.mts",
       "default": "./dist/testing/outboxStoreContract.mjs"
@@ -290,7 +294,8 @@
       "./auth/audit": "stable",
       "./sync": "experimental",
       "./usage": "experimental",
-      "./testing/outbox": "stable"
+      "./testing/outbox": "stable",
+      "./outbox-admin": "experimental"
     }
   },
   "files": [
@@ -331,21 +336,23 @@
     "test:smoke:redis": "node scripts/smoke-ws-redis.mjs",
     "smoke": "node scripts/smoke-test.mjs",
     "smoke:consumer": "node scripts/smoke-test.mjs --consumer",
+    "smoke:mcp": "node scripts/mcp-e2e.mjs",
     "push": "classytic-push",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
     "release": "npm run push -- main && npm run release:tag && npm publish",
     "check:peer-skew": "node scripts/check-peer-skew.mjs",
     "check:docs-drift": "node scripts/check-docs-drift.mjs",
     "check:boundaries": "node scripts/check-boundaries.mjs",
-    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run check:route-api && npm run check:boundaries && npm run typecheck && npm run lint && npm run build && npm run check:api-surface && npm run check:package && npm run test:ci && npm run smoke:consumer",
-    "check:route-api": "node scripts/check-removed-route-api.mjs"
+    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run check:route-api && npm run check:boundaries && npm run typecheck && npm run lint && npm run build && npm run check:api-surface && npm run check:forgotten-exports && npm run check:package && npm run test:ci && npm run smoke:consumer && npm run smoke:mcp",
+    "check:route-api": "node scripts/check-removed-route-api.mjs",
+    "check:forgotten-exports": "node scripts/check-forgotten-exports.mjs"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.18.0",
-    "@classytic/repo-core": ">=0.17.0",
+    "@classytic/primitives": ">=0.23.0",
+    "@classytic/repo-core": ">=0.24.0",
     "@classytic/streamline": ">=2.8.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -353,6 +360,7 @@
     "@fastify/multipart": ">=9.0.0",
     "@fastify/rate-limit": ">=10.0.0",
     "@fastify/sensible": ">=6.0.0",
+    "@fastify/static": ">=8.0.0",
     "@fastify/type-provider-typebox": ">=6.0.0",
     "@fastify/under-pressure": ">=9.0.0",
     "@fastify/websocket": ">=11.0.0",
@@ -372,8 +380,8 @@
     "jose": ">=5.0.0",
     "pino-pretty": ">=13.0.0",
     "typebox": ">=1.0.0",
-    "zod": ">=4.4.0",
-    "@fastify/static": ">=8.0.0"
+    "vitest": ">=3.0.0",
+    "zod": ">=4.4.0"
   },
   "peerDependenciesMeta": {
     "better-auth": {
@@ -456,6 +464,9 @@
     },
     "@fastify/static": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -467,14 +478,14 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@better-auth/drizzle-adapter": "^1.6.19",
     "@better-auth/mongo-adapter": "^1.6.19",
-    "@biomejs/biome": "^2.5.5",
+    "@biomejs/biome": "^2.5.7",
     "@classytic/dev-tools": "^0.2.0",
     "@classytic/gitkit": ">=0.1.0",
-    "@classytic/mongokit": "^3.28.0",
+    "@classytic/mongokit": "^3.33.0",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.18.0",
-    "@classytic/repo-core": "^0.17.0",
-    "@classytic/sqlitekit": "^0.6.0",
+    "@classytic/primitives": "^0.23.0",
+    "@classytic/repo-core": "^0.24.0",
+    "@classytic/sqlitekit": "^0.9.0",
     "@classytic/streamline": "^2.8.2",
     "@electric-sql/pglite": "^0.5.4",
     "@fastify/cors": "^11.2.0",
@@ -494,21 +505,21 @@
     "@vitest/coverage-v8": "^4.1.9",
     "ajv": "^8.20.0",
     "better-auth": "^1.6.25",
-    "better-sqlite3": "^12.11.1",
-    "bullmq": "^5.81.2",
+    "better-sqlite3": "^13.0.3",
+    "bullmq": "^6.1.2",
     "dotenv": "^17.4.2",
     "drizzle-orm": "^0.45.2",
     "fast-check": "^4.8.0",
-    "fastify": "^5.10.0",
-    "fastify-raw-body": "^5.0.0",
+    "fastify": "^5.12.0",
+    "fastify-raw-body": "^6.0.1",
     "h3-js": "^4.4.0",
-    "ioredis": "^5.11.1",
+    "ioredis": "^6.0.0",
     "jose": "^6.2.3",
     "jsonwebtoken": "^9.0.3",
-    "knip": "^6.17.1",
+    "knip": "^6.31.0",
     "mongodb": "^7.3.0",
     "mongodb-memory-server": "^11.2.0",
-    "mongoose": "^9.7.1",
+    "mongoose": "^9.9.1",
     "publint": "^0.3.21",
     "tsdown": "^0.22.14",
     "typebox": "^1.3.6",

package/skills/arc/SKILL.md

@@ -69,6 +69,14 @@ await app.listen({ port: 8040, host: '0.0.0.0' });
 
 **Boot order (fixed):** `beforeBoot` → modules resolve → `plugins` → `bootstrap[]` → `resources` → `afterResources` → `onReady`.
 
+**`role` — one image, N deployments (2.34).** `createApp({ role })` declares what a process is FOR, so the same codebase ships as api / worker / relay / scheduler without per-deployment builds:
+
+```typescript
+createApp({ role: process.env.ARC_ROLE as 'api' | 'worker' | 'relay' | 'scheduler' | 'all' })
+```
+
+`api` and `worker` mount NO module schedule arms; `relay` mounts only `kind: 'relay'` arms (the outbox relay, durable webhook delivery); `scheduler` mounts all of them. Declaring `relay`/`scheduler` together with `resources`/`resourceDir` is BOOT-FATAL — a relay process must not serve routes. Default `all` is the pre-2.34 behaviour, unchanged. `createWorker()` forwards `role`; without one it still runs everything non-HTTP.
+
 `beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks.
 
 For async-booted engines, pass `resources` as a factory so it runs after `bootstrap[]`:
@@ -162,7 +170,7 @@ defineResource({ name: 'health', customRoutesOnly: true, routes: [...] });
 defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
 ```
 
-400s on `?limit=` violations include the cap: `message: "Query parameter 'limit' must be <= 500 (got 800) (cap is 500)"` + `meta: { field: 'limit', cap: 500 }`.
+A `?limit=` above the cap is **clamped to it**, not rejected (2.33 — see Query parsing). The effective cap rides in the OpenAPI parameter description.
 
 ## fieldRules
 
@@ -304,12 +312,18 @@ Decorates `app.authenticate` / `app.optionalAuthenticate` / `app.authorize`.
 ## Authoritative gotchas
 
 - **Field-write reject (default).** Requests carrying non-writable fields → 403 with denied list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **Immutable writes are STRIPPED, not refused (default).** `PATCH {"type":"rent"}` on an `immutable` field returns 200 with the value unchanged. Opt into 403: `defineResource({ onImmutableWrite: 'reject' })`, or `ARC_STRICT_IMMUTABLE_WRITES=true`. Separate from `onFieldWriteDenied` because a full-object PATCH echoing an immutable field back UNCHANGED is legitimate, and the sanitizer has no stored document to tell that from a real change — turn it on if you send partial patches.
+- **Log redaction is REPLACED, not merged.** Setting `logger.redact` makes yours the whole policy; arc's defaults stop applying. Superset them: `import { DEFAULT_LOGGER_REDACT_PATHS } from '@classytic/arc/factory'` and spread it into your list, rather than hand-copying (a copy drifts — one host's had lost `*.passwordHash`).
+- **Error disclosure derives from `preset`, falling back to the environment.** `includeStack` and `exposeInternalMessages` are both derived, and host keys MERGE over them — stating one no longer resets the other. Direct `errorHandlerPlugin` registration skips the preset derivation entirely.
 - **multiTenant injects org on UPDATE.** Body `organizationId` is overwritten with caller's scope (closes tenant-hop).
 - **`request.user`** is `Record<string, unknown> | undefined`. Guard with `if (req.user)` on public routes.
 - **Arc reads singular `user.role`** (string, comma-separated, or array). Don't put a plural `roles` field on the model.
 - **`verifySignature(body, …)`** throws on parsed body — pass `req.rawBody`.
 - **MCP tools fail-closed.** A resource action without per-action perm + no `actionPermissions` + no `permissions.update` fallback → throws at tool generation. Declare `allowPublic()` to opt into unauthenticated.
 - **Better Auth roles.** BA stores `member.role = "admin,recruiter"` (comma-separated). Arc splits into `scope.orgRoles = ['admin', 'recruiter']`; `?role=admin` won't match — use `role[like]=admin`.
+- **Read-only repositories refuse write ROUTES at boot (2.34).** Kits' Better Auth overlays are sealed by default (`capabilities.readOnly`) — BA owns hashing, session revocation, org cascades. Mounting `create`/`update`/`delete` over one is boot-fatal: disable those routes, or pass the kit's `unsafeWritable: true` for administrative repair only. Normal identity mutations go through `auth.api`.
+- **Arc closes only stores/transports it BUILT (2.34).** One you hand to `idempotencyPlugin` / `eventPlugin` / `queryCachePlugin` stays yours to close — arc used to close every one, which wiped a co-resident app's live idempotency records.
+- **Idempotency self-checks its store at boot (2.34).** A probe write must read back under its own key and NOT under another; registration throws otherwise. Catches a filter-stripping repository (a pathless Mongoose schema under `strictQuery: true` strips filters to `{}`), which otherwise replays cached responses across keys AND users. `selfCheck: false` to disable; the adapter's per-read identity checks remain.
 
 ## routeGuards + defineGuard
 
@@ -369,6 +383,28 @@ defineResource({
 });
 ```
 
+**An unknown filter key is DROPPED by default, and dropping WIDENS.** `?filters[status]=pending`
+against a parser that does not whitelist `status` returns 200 with every row unfiltered — the
+caller asked to narrow and got a broader set. Refuse instead:
+
+```typescript
+new QueryParser({ allowedFilterFields: [...], strictFilterFields: true })  // 400 ValidationError
+```
+
+Off by default (an unconditional throw would reject requests that work today). Fleet-wide via
+`ARC_STRICT_QUERY_PARAMS=true`; an explicit `false` beats the env. Only the FILTER whitelist —
+a dropped sort or operator degrades ordering, it does not widen the row set.
+
+**`?limit` above the cap CLAMPS, it does not 400** (2.33). The parser and `QueryResolver` both
+clamp, and the querystring schema no longer emits `maximum` — it used to reject first, making the
+documented clamp unreachable and turning a benign over-ask into a 400 that callers render as an
+empty list. The cap is in the parameter description instead, so OpenAPI still shows it.
+
+**One cap, one owner.** Page size is capped by the parser, the repository's pagination engine and
+arc — lowest wins silently. Arc defers to the parser's `maxLimit` when the host states none, and
+WARNS at boot when the parser allows more than the repository (`pagination-cap-mismatch`).
+Configure both to the same number.
+
 ## Aggregations
 
 `GET /:prefix/aggregations/:name` per entry. Portable `$match → $group → $project → $sort → $limit` against `repo.aggregate(req, options)` — same shape across kits.
@@ -453,6 +489,31 @@ defineResource({
 
 POST/PATCH/DELETE bumps resource version. Response header: `x-cache: HIT | STALE | MISS`. `runtime: 'distributed'` requires `stores.queryCache: RedisCacheStore`.
 
+## Transactional writes (2.34)
+
+`transactional: true` runs the PERSISTENCE step inside `withTransaction`. Write verbs receive the tx-bound repository plus `ctx.uow` — the join point for work outside the repository:
+
+```typescript
+defineResource({
+  name: 'order',
+  adapter,
+  transactional: true,
+  writes: {
+    create: async (data, ctx) => {
+      const order = await ctx.repository.create(data);          // tx-bound
+      await outbox.store(event, { session: ctx.uow?.session });  // SAME transaction
+      return order;
+    },
+  },
+});
+```
+
+- Hooks stay OUTSIDE the retry — before/after run once; only persistence re-runs.
+- Transient conflicts re-run with jittered backoff; `VersionConflictError` surfaces (409), never retried.
+- **Retry authority is the KIT's.** mongokit declares `transactionRetry: 'managed'` (its driver already retries internally) and is called exactly once; sqlitekit declares `'caller'` and gets the envelope's loop. Arc never stacks a second policy.
+- **BOOT-FATAL** without `withTransaction`, and at REGISTRATION when the repository reports `capabilities.transactions !== true` (standalone Mongo, D1, unconfirmed topology). The capability is checked at registration, not at `defineResource()`, because that usually runs at module import — before `beforeBoot()` connects.
+- `ctx.uow.session` is empty on connection-bound backends (SQLite); the tx-bound repo is the join point there.
+
 ## Events
 
 CRUD events auto-emit: `{resource}.created` / `{resource}.updated` / `{resource}.deleted`. Manual publish:
@@ -464,13 +525,27 @@ await app.events.subscribe('order.*', async (event) => { … });
 
 Transports: Memory · Redis Pub/Sub (fire-and-forget) · Redis Streams (durable, consumer groups, DLQ). Event types live in `@classytic/primitives/events` (`createEvent`, `createChildEvent`, `matchEventPattern`, …); arc re-exports the runtime `MemoryEventTransport` only.
 
-**Outbox** (at-least-once via transactional outbox):
+**Outbox** (at-least-once via transactional outbox) — prefer the MODULE, so the store is a slot other modules depend on rather than a value threaded by hand:
+
+```typescript
+createApp({ modules: [createOutboxModule({ store: repositoryAsOutboxStore(outboxRepo) })] });
+// Dev: createOutboxModule({ store: new MemoryOutboxStore() })
+```
+
+The relay arm is `kind: 'relay'`, so `role: 'relay'` deployments drain it. It resolves the RAW transport, never the `fastify.events` facade (the facade fails open, which would acknowledge rows whose publish failed) — no transport is boot-fatal. **Fencing (2.34):** stores that support `claimPendingFenced` mint a token in the claim CAS; a relay that lost its lease mid-batch cannot ack or re-schedule a row a successor already owns. Feature-detected end to end.
+
+**Durable webhooks (2.34)** — delivery survives crash and deploy, using the outbox machinery rather than a second queue:
 
 ```typescript
-const outbox = new EventOutbox({ repository: outboxRepo, transport });
-// Dev: { store: new MemoryOutboxStore(), transport }
+const store = repositoryAsOutboxStore(deliveryRepo);
+createApp({
+  modules: [createDurableWebhookModule({ store })],       // relay does the signed POST
+  plugins: async (f) => f.register(webhookPlugin, { durable: { store } }), // enqueue, don't POST
+});
 ```
 
+One row per (event × subscription), deterministic id so an at-least-once upstream enqueues each delivery exactly once. Transient failures (network/timeout/429/5xx) retry with backoff; 4xx dead-letters on the FIRST attempt. `durable` + `retry` together is a registration error.
+
 Full event recipes (retry, DLQ, dual-publish warnings, idempotency keys) → [references/events.md](references/events.md).
 
 ## Hooks
@@ -652,6 +727,23 @@ await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
 
 `@classytic/arc/usage` — `usagePlugin` decorates `fastify.usage` with per-actor, per-UTC-month counters (`record`/`summary`/`period`/`actorOf`; actor chain org → user → client → ip). Auto-tracks `api.requests` (default on) + `api.egress.bytes` (opt-in); recording is fail-safe (a throwing `UsageStore` never fails a request; `MemoryUsageStore` built in, Redis/kit backends are ~5 lines). Pair with `createApp({ rateLimit: { plan: { resolve, limits: { free: { max: 60 }, enterprise: false }, default: 'free' } } })` for per-plan ceilings — `false` = unlimited, unknown/throwing resolvers fall back to `default` then global `max`, and buckets follow the tenant key chain by default. Caveat: the limiter runs before route auth, so `resolve` sees the raw request.
 
+## Runtime capability registry (2.34)
+
+Under `runtime: 'distributed'`, subsystems holding process-local state must declare it — the end-of-boot audit FAILS the app on undeclared memory state, naming every violator:
+
+```typescript
+import { declareRuntimeCapability } from '@classytic/arc/utils';
+
+declareRuntimeCapability(fastify, {
+  subsystem: 'billing.sequence-cache',
+  durability: 'memory',        // 'memory' | 'shared'
+  accepted: true,              // per-process BY DESIGN (logged, never fatal)
+  detail: 'short-TTL cache; correctness from TTL, not shared state',
+});
+```
+
+`createApp`'s constructor-time guard only sees what it is passed; state a host wires inside `plugins()` was invisible to it and lived on a checklist. This makes the checklist enforcement. Arc's webhooks plugin declares its default in-memory store.
+
 ## Adapters
 
 Cross-framework adapter contract lives in `@classytic/repo-core/adapter`. Every kit-specific adapter ships from its kit's `/adapter` subpath; arc itself has zero kit-bound adapters.

package/skills/arc/references/api-reference.md

@@ -126,8 +126,27 @@ import {
 import { tracingPlugin } from '@classytic/arc/plugins/tracing';
 import { auditPlugin } from '@classytic/arc/audit';
 import { idempotencyPlugin } from '@classytic/arc/idempotency';
+// Runtime capability registry (2.34) — declare process-local state so a
+// `runtime: 'distributed'` boot fails on undeclared memory state:
+import { declareRuntimeCapability } from '@classytic/arc/utils';
 ```
 
+**Idempotency store — the one schema mistake that matters.** Backing the store
+with a repository requires the key path to survive the filter. A Mongoose
+schema with NO declared paths under a global `strictQuery: true` has EVERY
+filter key stripped, so `getOne({ _id: key })` becomes `getOne({})`: one row
+absorbs every key and responses replay across keys AND users. Declare the path
+and pin the option on the schema:
+
+```typescript
+new Schema({ _id: String }, { strict: false, strictQuery: false, timestamps: false })
+// NOT `new Schema({}, { _id: false, strict: false })`
+```
+
+The plugin's boot self-check (default on, `selfCheck: false` to disable) probes
+for exactly this and refuses to register; the adapter also throws
+`IdempotencyStoreMisconfiguredError` on any cross-key read at runtime.
+
 ## Integrations
 
 ```typescript

package/skills/arc/references/production.md

@@ -292,7 +292,7 @@ field masking. Client = plain `EventSource` with `?token=`. No replay — reconn
 refetches the list. Choosing: per-user resource views → realtime; bidirectional/geo
 → `integrations/websocket` (its CRUD bridge is org-coarse — never expose
 row-permissioned resources through it); event firehose → sse. Massive fan-out
-(viral feeds, live scores) → publish once to an edge layer (Ably/Centrifugo/CF)
+(viral feeds, live scores) → publish once to a dedicated edge fan-out layer
 via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
 
 ```typescript
@@ -618,7 +618,7 @@ presets: [bulkPreset({ operations: ['createMany', 'updateMany'], maxCreateItems:
 ## Compensating Transaction
 
 In-process rollback primitive — runs steps in order, compensates in reverse on failure.
-For distributed sagas across services, use Temporal, Inngest, or Streamline.
+For distributed sagas across services, use `@classytic/streamline` or a dedicated workflow orchestrator.
 
 ```typescript
 import { withCompensation } from '@classytic/arc/utils';

package/dist/fastify-augmentation-zh0_AYHa.d.mts

@@ -1,85 +0,0 @@
-
-import { hn as HookSystem, z as ResourceRegistry } from "./index-CpzxqePp.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
-import { h as HealthCheck, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-CBgvkp8O.mjs";
-import { s as ModuleState } from "./index-CFThn1K9.mjs";
-import { FastifyPluginAsync } from "fastify";
-//#region src/core/arcCorePlugin.d.ts
-interface ArcCorePluginOptions {
-  /** Enable event emission for CRUD operations (requires eventPlugin) */
-  emitEvents?: boolean;
-  /** Hook system instance (for testing/custom setup) */
-  hookSystem?: HookSystem;
-  /** Resource registry instance (for testing/custom setup) */
-  registry?: ResourceRegistry;
-}
-interface PluginMeta {
-  name: string;
-  version?: string;
-  options?: Record<string, unknown>;
-  registeredAt: string;
-}
-interface ArcCore {
-  /** Instance-scoped hook system */
-  hooks: HookSystem;
-  /** Instance-scoped resource registry */
-  registry: ResourceRegistry;
-  /** Whether event emission is enabled */
-  emitEvents: boolean;
-  /** External OpenAPI paths contributed by auth adapters or third-party integrations */
-  externalOpenApiPaths: ExternalOpenApiPaths[];
-  /** Registered plugins for introspection */
-  plugins: Map<string, PluginMeta>;
-  /**
-   * Module public exports — `bootstrap()` return values keyed by module name
-   * (see `src/factory/module.ts`). Read via `getModuleExports(fastify, name)`:
-   * augment `ArcModuleRegistry` once and the name infers the export type;
-   * otherwise pass it inline. `Partial<ArcModuleRegistry>` gives augmented
-   * apps typed direct access (`fastify.arc.modules.order`), while the
-   * `Record<string, unknown>` intersection keeps un-augmented reads open.
-   * Populated lazily by `registerResources` — absent until a module exports.
-   */
-  modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
-  /**
-   * Lifecycle state per composed module (null-proto map, populated by
-   * `registerResources` the moment the graph is validated — so it answers
-   * "is this module composed?" even for resource-only modules that never
-   * record an export). Read via `hasModule(fastify, name)` /
-   * `getModuleState(fastify, name)`; the map itself is internal.
-   */
-  moduleStates?: Record<string, ModuleState>;
-  /**
-   * Module-contributed readiness checks, collected in dependency order and
-   * frozen by `createApp`. The API role merges these into its `healthPlugin`;
-   * `createWorker` reads this to give its probe listener the identical union
-   * (the worker preset disables the main health plugin, so this is how module
-   * checks reach the probe without a double registration). Empty until
-   * `createApp` populates it.
-   */
-  healthChecks?: readonly HealthCheck[];
-  /**
-   * The resolved, dependency-ordered module definitions (frozen by createApp).
-   * Integrations that collect a module arm at their OWN init time — e.g. the
-   * streamline integration calling `collectModuleWorkflows(fastify, defs)` after
-   * it has created + decorated its container — read the list from here. Empty
-   * until createApp populates it.
-   */
-  moduleDefinitions?: readonly ArcModule[];
-  /**
-   * Module-contributed recurring schedules, resolved once in dependency order
-   * and frozen after bootstraps. The same definitions are executed by Arc's
-   * schedules plugin and exposed here for introspection. Empty until collection.
-   */
-  scheduledJobs?: readonly Readonly<ScheduleDefinition>[];
-}
-declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
-declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;
-//#endregion
-//#region src/types/fastify-augmentation.d.ts
-declare module "fastify" {
-  interface FastifyInstance {
-    arc?: ArcCore;
-  }
-}
-//#endregion
-export { arcCorePlugin as a, _default as i, ArcCorePluginOptions as n, PluginMeta as r, ArcCore as t };

package/dist/projection-BHw6xlOQ.mjs

@@ -1,18 +0,0 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { c as getOrgId, g as getUserId, x as isMember } from "./types-Cys0ko9Z.mjs";
-//#region src/scope/projection.ts
-/**
-* Compute the request-scope projection. Returns `undefined` when no
-* scope is attached (public / unscoped routes) so hosts can idiomatically
-* write `ctx.scope?.organizationId` without a double-null check.
-*/
-function buildRequestScopeProjection(scope) {
-	if (!scope) return void 0;
-	return {
-		organizationId: getOrgId(scope),
-		userId: getUserId(scope),
-		orgRoles: isMember(scope) ? scope.orgRoles : void 0
-	};
-}
-//#endregion
-export { buildRequestScopeProjection as t };