@classytic/arc 2.38.0 → 2.41.0

package/skills/arc/SKILL.md

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

package/skills/arc/references/mcp.md

@@ -133,6 +133,26 @@ await app.register(mcpPlugin, { resources: catalogResources, prefix: '/mcp/catal
 await app.register(mcpPlugin, { resources: orderResources, prefix: '/mcp/orders' });
 ```
 
+## DNS-rebinding protection (`Host` / `Origin`)
+
+An MCP endpoint on loopback is reachable from any page the developer visits: if
+an attacker-controlled DNS name resolves to `127.0.0.1`, the browser treats the
+reply as same-origin and can read every tool's output. Validating `Host` breaks
+the chain.
+
+`dnsRebindingProtection` **defaults on when `auth: false`** (the local shape the
+attack targets) and **off when auth is configured** (a real deployment's `Host`
+is its own domain — defaulting on would 403 it; credentials are the gate there).
+
+```typescript
+mcpPlugin({ resources, auth, dnsRebindingProtection: {} });                        // localhost + auth
+mcpPlugin({ resources, dnsRebindingProtection: { allowedHosts: ['mcp.example.com'] } });
+mcpPlugin({ resources, auth: false, dnsRebindingProtection: false });              // deliberately public
+```
+
+An absent `Origin` passes — non-browser MCP clients send none. A present but
+unlisted one is refused. `${prefix}/health` is exempt so probes keep working.
+
 ## Auth — Three Modes
 
 Arc doesn't enforce an auth strategy. You choose what fits.

package/skills/arc/references/production.md

@@ -46,23 +46,50 @@ await fastify.register(requestIdPlugin, {
 
 ## Graceful Shutdown Plugin
 
+Registered by default (`arcPlugins.gracefulShutdown`). Pass an options object to configure it inline from `createApp`.
+
 ```typescript
 import { gracefulShutdownPlugin } from '@classytic/arc/plugins';
 
 await fastify.register(gracefulShutdownPlugin, {
-  timeout: 30000,
+  timeout: 30000,          // hard cap; drainDelayMs counts against it
+  drainDelayMs: 10000,     // lame-duck window — see below
   signals: ['SIGTERM', 'SIGINT'],
   logEvents: true,
   onShutdown: async () => {
     await mongoose.disconnect();
     await redis.quit();
   },
+  onForceExit: () => {},   // tests: stop a timeout from killing the runner
 });
 
-// Sequence: receive signal → stop accepting connections → wait for in-flight
-// → run onShutdown → close Fastify → exit process
+// Sequence: signal → shutdownState.draining = true (/ready starts 503ing)
+//   → wait drainDelayMs (still serving) → fastify.close() (stops accepting,
+//   drains in-flight) → onShutdown() → exit naturally
+```
+
+**`fastify.close()` runs BEFORE `onShutdown`** — so `onShutdown` is where you release what arc doesn't own (DB connections, your own Redis client), and it runs after in-flight requests are done. Don't close anything a request might still need.
+
+### `drainDelayMs` — the rolling-deploy 502
+
+Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives. That is the classic rolling-deploy 502 — a load balancer keeps routing to an instance until its readiness probe has failed **for several intervals**, and by then the instance already stopped accepting.
+
+`drainDelayMs` is the window between "start failing readiness" and "stop accepting":
+
+- `/health/ready` → `503 { status: 'draining' }` immediately on signal
+- `/health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
+- everything already routed here is still served for the whole window
+
+Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
+
+```typescript
+createApp({
+  arcPlugins: { gracefulShutdown: { drainDelayMs: 10_000, timeout: 30_000 } },
+});
 ```
 
+**Do not also write `process.on('SIGTERM', () => app.close())`.** The plugin already owns those signals; a second handler closes the server immediately and skips the drain entirely — you get the 502s back while the config says you fixed them.
+
 ## Audit Plugin
 
 Change tracking. Pass a `RepositoryLike` for persistence, or omit for in-memory dev:
@@ -464,21 +491,79 @@ const app = await createApp({
   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
   cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') ?? [], credentials: true },
   rateLimit: { max: 100, timeWindow: '1 minute' },
-  arcPlugins: { queryCache: true },
+  arcPlugins: {
+    queryCache: true,
+    // Behind a load balancer: fail readiness first, keep serving while it
+    // deregisters, then close. No manual process.on('SIGTERM') — the plugin
+    // owns the signals, and a second handler skips the drain.
+    gracefulShutdown: { drainDelayMs: 10_000 },
+  },
 });
-
-process.on('SIGTERM', () => app.close());
-process.on('SIGINT', () => app.close());
 ```
 
 ## Distributed Runtime
 
-`runtime: 'distributed'` only validates stores you actually enable:
+`runtime: 'distributed'` is the "more than one replica" switch. It refuses to boot when something in the app holds state that only exists in **this** process. Two checks, one policy:
+
+**1. Constructor-time guard** — what `createApp` can see in its own options, checked before any boot cost:
 
 - `stores.events` — always required
 - `stores.cache` — only when `arcPlugins.caching` enabled
 - `stores.queryCache` — only when `arcPlugins.queryCache` enabled
-- `stores.idempotency` — never validated (per-resource opt-in)
+- `stores.idempotency` — warn only (per-resource opt-in)
+- `rateLimit` — needs a shared store: `{ redis: client }` or `{ store: CustomStore }`. Both forms count; `rateLimit: false` opts out.
+- `arcPlugins.schedules` — needs `lock` (a `LockAdapter`, for a fleet where any replica may arm schedules) **or** `singleReplica: true` (exactly one replica arms them — the `role: 'scheduler'` deployment pinned at 1). Without one, boot fails: otherwise every replica fires every tick, and duplicate side effects are two invoices, not a stale cache. `singleReplica` is a claim about your deployment — scale that deployment past one replica and it becomes false.
+
+**2. Capability audit** (end of boot) — everything wired inside `plugins()`, `bootstrap[]`, or a module phase, which the guard above cannot inspect. Subsystems declare via `declareRuntimeCapability`; an undeclared-shared memory default **fails the boot in one error naming every violator**, so you fix them in one pass rather than one restart each.
+
+What declares itself, and what fixes it:
+
+| Subsystem | Default | Shared option |
+|---|---|---|
+| `auth.sessions` | `MemorySessionStore` | `RedisSessionStore` (`@classytic/arc/auth/redis`) |
+| `usage.store` | `MemoryUsageStore` | `RedisUsageStore` (`@classytic/arc/usage`) or `@classytic/mongokit/usage` |
+| `audit.store` | `MemoryAuditStore` | `repository: yourRepo` (any kit) |
+| `cache.query` | `MemoryCacheStore` | `RedisCacheStore` (`@classytic/arc/cache`) |
+| `permissions.dynamic-cache` | internal memory | `cacheStore:` — **and pass `fastify:`**, the matrix has no handle of its own so it is invisible to the audit without it |
+| `websocket.adapter` | `LocalWebSocketAdapter` | Redis adapter (`@classytic/arc/integrations/websocket-redis`) |
+| `websocket.pushref-store` | memory | Redis pushRef store |
+| `webhooks.store` | memory | shared store, or durable mode |
+| `http.response-cache` | memory | **nothing — declared `accepted`.** Per-replica by design; correctness comes from short TTLs. Logged, never a failure. |
+
+### Circuit breakers count per replica unless you say otherwise
+
+`CircuitBreaker` state is in-process. With 50 pods and `failureThreshold: 5`, a dead downstream absorbs **250 real requests** before anything opens — each pod rediscovers the same outage independently. Share the failure window:
+
+```typescript
+import { CircuitBreaker, RedisCircuitBreakerState } from '@classytic/arc/utils';
+
+const shared = new RedisCircuitBreakerState({ redis });   // fixed window, default 60s
+
+const payments = new CircuitBreaker(charge, {
+  name: 'stripe.charges',   // REQUIRED with sharedState — the key every replica counts under
+  failureThreshold: 5,
+  sharedState: shared,
+});
+```
+
+First replica trips at the threshold; every other trips on its **next** failure. It shares the failure *signal*, not the state machine — each replica still owns its own OPEN/HALF_OPEN probing, which avoids needing consensus over who probes. Nothing touches the network on the success path, the failure path never *waits* on the store, and a store that throws degrades to local counting rather than disabling the breaker.
+
+Hosts declare their own too — a replica-local cache you built in `plugins()` belongs in the audit:
+
+```typescript
+import { declareRuntimeCapability } from '@classytic/arc/utils';
+
+declareRuntimeCapability(fastify, {
+  subsystem: 'billing.sequence-cache',
+  durability: 'memory',                  // 'memory' | 'shared'
+  detail: 'invoice numbering cached per process',
+  // accepted: true,                     // only when per-process is INTENDED
+});
+```
+
+Declare from anywhere a registration reaches — `plugins()`, a module phase, or inside your own encapsulated `fastify.register()`; all land in the one audit. `accepted: true` is for state that is per-process **by design**; it must be stated by the declarant, never inferred.
+
+**Migration note:** a distributed app that booted fine before 2.41 can now fail on a default it was silently running replica-local (usage counters and audit trails were the common ones). The boot error names each. That is the bug surfacing, not a new one.
 
 ## Under-Pressure
 

package/skills/arc/references/testing.md

@@ -198,15 +198,3 @@ runStorageContract(async () => {
 3. **Use `ctx.fixtures.clear()` in `afterEach`** — destroyers handle dependency order.
 4. **Test permission denials explicitly** — `expectArc(res).forbidden()` beats status-code assertions.
 5. **Reach for `createHttpTestHarness` first** — 16 tests for one function call.
-
-## Migration from pre-2.11 testing APIs
-
-| Pre-2.11 | 2.11 |
-|---|---|
-| `TestHarness` / `createTestHarness` | `createHttpTestHarness(resource, ctxFn)` |
-| `TestAppResult` | `TestAppContext` |
-| `testApp.mongoUri` | `ctx.dbUri` |
-| `createJwtAuthProvider` / `createBetterAuthProvider` (as `HttpTestHarness` imports) | `ctx.auth` from `createTestApp` (or direct factory import) |
-| `withTestDb()` | `createTestApp({ db: 'in-memory' })` + `ctx.dbUri` |
-| `TestDatabase` / `TestSeeder` / `TestTransaction` | `createTestFixtures` + kit-level cleanup |
-| `setupBetterAuthOrg` | `setupBetterAuthTestApp` + `helpers.signUpWithOrg` |

package/skills/arc-code-review/references/anti-patterns.md

@@ -831,7 +831,7 @@ output_mode: content
 
 Also: adapter contract types imported from arc — `import type { DataAdapter, AdapterRepositoryInput, AdapterFactory, OpenApiSchemas, SchemaMetadata, FieldMetadata, RelationMetadata, AdapterValidationResult, AdapterSchemaContext } from '@classytic/arc'` (any subpath). And: `mergeFieldRuleConstraints` from `@classytic/arc/adapters`. Any `from '@classytic/arc/adapters'` import — the entire subpath was removed in arc 2.12.
 
-**Why critical:** This only worked in arc ≤ 2.x. Arc 2.12 moved every kit-specific adapter (Mongoose, Drizzle, Prisma) into its kit and the cross-framework adapter contract into `@classytic/repo-core/adapter`. The `@classytic/arc/adapters` subpath was removed entirely. Importing these names from arc fails to resolve on 3.x — the build breaks at install time. The new shape is **strict**: kit-specific things MUST come from the kit; the contract MUST come from repo-core.
+**Why critical:** `@classytic/arc/adapters` does not exist. Kit-specific adapters (Mongoose, Drizzle, Prisma) live in their kit; the cross-framework contract lives in `@classytic/repo-core/adapter`. Importing these names from arc fails to resolve — the build breaks at install time. The rule is **strict**: kit-specific things come from the kit, the contract comes from repo-core.
 
 **Fix:**
 ```typescript

package/skills/arc-code-review/references/migration-recipes.md

@@ -4,66 +4,6 @@ Concrete diffs for the most common transformations. Apply in the order listed in
 
 ---
 
-## §0. arc 2.x → 3.0 — every kit-specific adapter moves to its kit
-
-**Why:** Through arc 2.12, kit-specific adapter factories (`createMongooseAdapter`, `createDrizzleAdapter`, `createPrismaAdapter`) shipped from `@classytic/arc` and arc had a peer dep on `@classytic/mongokit`. This coupled arc's release cadence to every kit's, dragged mongoose into every arc consumer's resolution graph (even Drizzle/Prisma users), and double-published the adapter contract types.
-
-In arc 2.12:
-- Adapter contract → `@classytic/repo-core/adapter` (new subpath in repo-core 0.4.0).
-- Mongoose adapter → `@classytic/mongokit/adapter` (3.13.0).
-- Drizzle adapter → `@classytic/sqlitekit/adapter` (0.3.0).
-- Prisma adapter → `@classytic/prismakit/adapter` (0.1.0 — new kit).
-- `mergeFieldRuleConstraints` + `applyNullable` → `@classytic/repo-core/schema`.
-- `@classytic/mongokit`, `@prisma/client`, `mongoose` all dropped from arc's `peerDependencies`. Arc 2.12 has zero kit- or driver-bound peers.
-- The `@classytic/arc/adapters` subpath was removed entirely. The `src/adapters/` directory inside arc is gone.
-- `RepositoryLike` is still re-exported from `@classytic/arc` for convenience.
-- Custom kits implementing `DataAdapter<TDoc>` plug in identically — same contract, no special-casing.
-
-### Coordinated versions
-
-These are the floors the adapter SPLIT requires — fixed history, safe to rely on:
-
-| Package | Min (adapter split) |
-|---|---|
-| `@classytic/arc` | 2.12.0 |
-| `@classytic/repo-core` | 0.4.0 |
-| `@classytic/mongokit` | 3.13.0 |
-| `@classytic/sqlitekit` | 0.3.0 |
-| `@classytic/prismakit` | 0.1.0 (not published to npm — build from source) |
-
-A second "current best-practice floor" column used to sit here and is gone: it named
-arc 2.21.0 while arc shipped 2.37, and sqlitekit 0.7.0 against a published 0.9.0. A
-version restated in a skill is wrong within a release and teaches nothing (CLAUDE.md,
-"no rotting metrics") — worse, it reads as researched. **For current floors read
-`peerDependencies` in arc's `package.json` and each kit's own README**; for what a
-given arc version added, [CHANGELOG.md](../../../CHANGELOG.md) is the index.
-
-### Import migration table
-
-| Old (arc 2.11.x) | New (arc 2.12+) |
-|---|---|
-| `import { createMongooseAdapter } from '@classytic/arc'` | `import { createMongooseAdapter } from '@classytic/mongokit/adapter'` |
-| `import { createMongooseAdapter } from '@classytic/arc/adapters'` | `import { createMongooseAdapter } from '@classytic/mongokit/adapter'` |
-| `import { createDrizzleAdapter } from '@classytic/arc/adapters'` | `import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter'` |
-| `import { createPrismaAdapter } from '@classytic/arc/adapters'` | `import { createPrismaAdapter } from '@classytic/prismakit/adapter'` |
-| `import type { DataAdapter, RepositoryLike, AdapterRepositoryInput } from '@classytic/arc'` | `import type { DataAdapter, RepositoryLike, AdapterRepositoryInput } from '@classytic/repo-core/adapter'` |
-| `import type { ... } from '@classytic/arc/adapters'` (any contract type) | `import type { ... } from '@classytic/repo-core/adapter'` |
-| `import type { InferMongooseDoc } from '@classytic/arc/adapters'` | `import type { InferMongooseDoc } from '@classytic/mongokit/adapter'` |
-| `import { mergeFieldRuleConstraints } from '@classytic/arc/adapters'` | `import { mergeFieldRuleConstraints } from '@classytic/repo-core/schema'` |
-| `MongooseAdapter`, `DrizzleAdapter`, `PrismaAdapter` (classes) | Same path moves: `@classytic/mongokit/adapter` / `@classytic/sqlitekit/adapter` / `@classytic/prismakit/adapter` |
-| Any `from '@classytic/arc/adapters'` import | The subpath was removed in arc 2.12 — re-route to the kit or repo-core per the rows above. |
-
-### Mechanical steps
-
-1. Bump versions in `package.json` to the matrix above. Drop `mongoose` from explicit deps if you only used it for the adapter — mongokit will pull it as its own peer.
-2. Run a project-wide find/replace using the table above. Detection regex: see anti-patterns.md §32g.
-3. `npx tsc --noEmit` — zero errors.
-4. Smoke test the resource OpenAPI endpoint and one MCP tool — confirm the schema is non-empty (still requires `schemaGenerator`).
-
-No runtime behavior change — the symbols are identical, only their package paths moved.
-
----
-
 ## §1. Manual CRUD module → `defineResource()`
 
 **Scope:** typically 5 routes (`GET`, `GET /:id`, `POST`, `PATCH /:id`, `DELETE /:id`) + ~150 LOC of pagination/validation/permission glue per resource.

package/skills/arc-code-review/references/mongokit-migration.md

@@ -347,33 +347,6 @@ If consumers see `as unknown as RepositoryLike<T>` casts when wiring a repo into
 
 In the client project, prefer `createMongooseAdapter({ model, repository })` from `@classytic/mongokit/adapter` over manual `RepositoryLike` shaping — it accepts mongokit-native repos with no casts, and since mongokit 3.21 `schemaGenerator` defaults to `buildCrudSchemasFromModel` (`schemaGenerator: false` opts out — see anti-patterns §32f before recommending that).
 
-## arc 2.12 / mongokit 3.13.0 — adapter split
-
-Through mongokit 3.12 / arc 2.11, `createMongooseAdapter` shipped from `@classytic/arc`. In mongokit 3.13.0 + arc 2.12, the adapter lives in mongokit at `@classytic/mongokit/adapter`. Coordinated minimums:
-
-| Package | Min |
-|---|---|
-| `@classytic/arc` | 2.12.0 |
-| `@classytic/mongokit` | 3.13.0 |
-| `@classytic/repo-core` | 0.4.0 |
-
-Migration shape:
-
-```typescript
-// arc 2.x
-import { createMongooseAdapter } from '@classytic/arc';
-import type { DataAdapter, RepositoryLike, AdapterRepositoryInput } from '@classytic/arc';
-import type { InferMongooseDoc, MongooseAdapterOptions } from '@classytic/arc/adapters';
-
-// arc 2.12+
-import { createMongooseAdapter } from '@classytic/mongokit/adapter';
-import type { DataAdapter, RepositoryLike, AdapterRepositoryInput } from '@classytic/repo-core/adapter';
-import type { InferMongooseDoc, MongooseAdapterOptions } from '@classytic/mongokit/adapter';
-```
-
-The kit owns mongoose as its peer dep; arc dropped both `@classytic/mongokit` and `mongoose` from its `peerDependencies`. Hosts depend on `@classytic/mongokit` directly, which transitively pulls mongoose. Detection regex for stragglers: see `references/anti-patterns.md` §32g.
-
----
 
 ## What mongokit does NOT do
 

package/skills/arc-module-publishing/references/package-manifest.md

@@ -46,7 +46,9 @@ optional-peer typing pattern. Values below are the real shapes shipped by
   },
 
   // Optional peers: declared here AND marked optional below. Host installs only if used.
-  // "peerDependencies": { ..., "zod": ">=3.23.0", "ioredis": ">=5.0.0" },
+  // The floor is the major YOUR suite runs — never one below it. A floor you never test
+  // is a compatibility claim, not a fact (arc shipped seven of those until 2.40).
+  // "peerDependencies": { ..., "zod": ">=4.4.0", "ioredis": ">=6.0.0" },
   // "peerDependenciesMeta": {
   //   "zod": { "optional": true },
   //   "ioredis": { "optional": true }

package/dist/rateLimitKey-CewdR-m6.mjs

@@ -1,15 +0,0 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-//#region src/scope/rateLimitKey.ts
-function createTenantKeyGenerator(opts) {
-	if (opts?.strategy) return opts.strategy;
-	return (ctx) => {
-		const scope = ctx.scope;
-		if (!scope || scope.kind === "public") return ctx.ip;
-		if (scope.kind === "member") return scope.organizationId;
-		if (scope.kind === "service") return scope.organizationId;
-		if (scope.kind === "elevated") return scope.organizationId ?? scope.userId ?? ctx.ip;
-		return scope.userId ?? ctx.ip;
-	};
-}
-//#endregion
-export { createTenantKeyGenerator as t };