@classytic/arc 2.20.0 → 2.22.0

package/skills/arc/SKILL.md

@@ -67,7 +67,9 @@ const app = await createApp({
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
-**Boot order (fixed):** `plugins` → `bootstrap[]` → `resources` → `afterResources` → `onReady`.
+**Boot order (fixed):** `beforeBoot` → modules resolve → `plugins` → `bootstrap[]` → `resources` → `afterResources` → `onReady`.
+
+`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[]`:
 
@@ -78,22 +80,19 @@ resources: async (fastify) => {
 }
 ```
 
-`loadResources(import.meta.url)` resolves `src/` in dev and `dist/` in prod. Use `loadResources(import.meta.url, { context: { engine } })` to thread engine handles into `(ctx) => defineResource(...)` default exports.
+`loadResources(import.meta.url)` resolves `src/` in dev and `dist/` in prod. Use `loadResources(import.meta.url, { context: { engine } })` to thread engine handles into `(ctx) => defineResource(...)` default exports. `{ filter: (absPath) => boolean }` (2.21) gates files BEFORE they're imported — feature-flag manifests become one callback.
 
 ## defineResource()
 
 ```typescript
 import { defineResource, allowPublic, requireRoles, requireAuth } from '@classytic/arc';
 import { createMongooseAdapter } from '@classytic/mongokit/adapter';
-import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 
 export default defineResource({
   name: 'product',
-  adapter: createMongooseAdapter({
-    model: ProductModel,
-    repository: productRepo,
-    schemaGenerator: buildCrudSchemasFromModel,
-  }),
+  // mongokit >=3.21 defaults schemaGenerator to buildCrudSchemasFromModel;
+  // pass `schemaGenerator: false` to opt out.
+  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
 
   presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'organizationId' }],
 
@@ -495,6 +494,8 @@ errorHandler: {
 }
 ```
 
+Modules ship their own via `defineModule({ errorMappers })` (2.21) — merged into the app handler at boot; host-level mappers keep priority.
+
 ## Testing
 
 ```typescript
@@ -625,6 +626,7 @@ Out of scope: SAML (use BA SAML plugin), session storage (BA `secondaryStorage`)
 await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
 
 defineResource({ name: 'order',   audit: true });
+defineResource({ name: 'invoice', history: true });   // 2.22: injects GET /:id/history from audit rows; implies audit: true (gate: update→get→requireAuth; override via { permissions, limit })
 defineResource({ name: 'payment', audit: { operations: ['delete'] } });
 defineResource({ name: 'product' });   // not audited
 
@@ -632,6 +634,10 @@ defineResource({ name: 'product' });   // not audited
 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.
+
 ## 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

@@ -6,7 +6,19 @@ Arc ships heavily tree-shaken: every feature has its own subpath. Pay only for w
 
 ```typescript
 import { defineResource, BaseController, BaseCrudController, allowPublic } from '@classytic/arc';
+// createApp rateLimit gains `plan: { resolve, limits, default }` (2.22) — per-plan ceilings, `false` = unlimited, fail-safe fallback.
 import { createApp, loadResources } from '@classytic/arc/factory';
+import { defineModule, getModuleExports, orderModules } from '@classytic/arc/factory';
+// Worker role (2.23) — same options object, headless process (no routes, no auth;
+// events/jobs/schedules run). Primitive: `mountRoutes: false`; preset: 'worker'.
+import { createWorker } from '@classytic/arc/factory';
+import type { ArcWorker, CreateWorkerOptions } from '@classytic/arc/factory';
+
+// Programmatic resource assembly (2.21) — for module authors composing
+// base config + host seams without casts. Arrays concat, plain objects
+// deep-merge, class instances last-win, `undefined` never clobbers.
+import { mergeResourceConfig } from '@classytic/arc';
+import type { ResourceSeams, SeamedResourceConfig, AdapterLike } from '@classytic/arc';
 ```
 
 ## Adapters (kit-owned, never arc)
@@ -52,6 +64,7 @@ import {
   requireAgentScope, requireMandate, requireDPoP,
   type RequireAgentScopeOptions, type RequireMandateOptions,
   allOf, anyOf, when, denyAll,
+  permissionMatrix,                                              // 2.21: { read, write, delete? } → full CRUD map
   createDynamicPermissionMatrix, createRoleHierarchy,
   fields, roles,
 } from '@classytic/arc/permissions';
@@ -101,6 +114,8 @@ import { createEvent, createChildEvent, matchEventPattern } from '@classytic/pri
 import {
   healthPlugin, gracefulShutdownPlugin, ssePlugin,
   metricsPlugin, versioningPlugin,
+  schedulesPlugin,   // 2.21: interval jobs, optional LockAdapter leader lease, no Redis
+  type ScheduleLockLike, type ScheduleDefinition,
 } from '@classytic/arc/plugins';
 import { tracingPlugin } from '@classytic/arc/plugins/tracing';
 import { auditPlugin } from '@classytic/arc/audit';
@@ -151,6 +166,21 @@ import {
 } from '@classytic/arc/presets';
 ```
 
+## Usage (2.22)
+
+```typescript
+// Per-actor, per-period (UTC YYYY-MM) usage counters — the accounting layer for
+// quotas, plan enforcement, and usage-based billing. Decorates `fastify.usage`.
+// requireQuota = the enforcement half: PermissionCheck gating on counters
+// (429 quota.exceeded with { kind, used, limit, period, resetsAt }; limit may
+// be a number, false = unlimited, or a plan-aware resolver; fail-open default).
+import { usagePlugin, MemoryUsageStore, usagePeriod, requireQuota } from '@classytic/arc/usage';
+import type { UsageStore, UsageBucket, UsagePluginOptions, UsageMeter, QuotaOptions } from '@classytic/arc/usage';
+// Canonical store contract + cross-kit conformance: @classytic/repo-core/usage +
+// runUsageStoreContract from @classytic/repo-core/testing; Mongo adapter:
+// createMongoUsageStore from @classytic/mongokit/usage (>=3.22).
+```
+
 ## Testing
 
 ```typescript
@@ -158,6 +188,10 @@ import {
   createTestApp, expectArc, createHttpTestHarness,
   TestAuthSession, TestAuthProvider, TestFixtures,
   runStorageContract,
+  bootModuleApp,     // 2.22: real app around modules ("boots green ⇒ composes");
+                     //   t.exports<T>(name) typed accessor; DB via `database` seam —
+                     //   mongoMemoryDatabase default, any kit injectable
+  mongoMemoryDatabase,
 } from '@classytic/arc/testing';
 ```
 

package/skills/arc/references/auth.md

@@ -71,6 +71,14 @@ const adapter = createBetterAuthAdapter({
 const app = await createApp({
   auth: { type: 'betterAuth', betterAuth: adapter },
 });
+
+// BA-on-Mongo + `beforeBoot` (2.22): BA's mongodbAdapter needs an OPEN
+// connection (`mongoose.connection.getClient()` throws pre-connect), so pass
+// a THUNK — resolved during auth registration, after beforeBoot connects:
+const app2 = await createApp({
+  beforeBoot: () => connectDatabase(),
+  auth: { type: 'betterAuth', betterAuth: () => createBetterAuthAdapter({ auth: getAuth(), orgContext: true }) },
+});
 ```
 
 **Org context flow** (when `orgContext: true`):
@@ -80,6 +88,11 @@ const app = await createApp({
 4. Splits roles: `"admin,recruiter"` → `['admin', 'recruiter']`
 5. Sets `request.scope`: `{ kind: 'member', organizationId, orgRoles: string[], teamId? }`
 
+**Sessions at scale (BA-native knobs — know these before reaching for arc's):**
+- **Redis sessions**: use BA's `secondaryStorage` (sessions land there INSTEAD of the DB unless `session.storeSessionInDatabase: true`). Arc's `@classytic/arc/auth/redis` (`SessionStore`) is the JWT-strategy store — different layer, don't mix them.
+- **Cookie cache gotcha that keeps orgContext correct**: BA's `session.cookieCache` never caches CUSTOM session fields (e.g. `activeOrganizationId`) — they're re-fetched per request, so arc's org scope can't go stale via the cookie. Cost: enabling cookieCache does NOT skip the org lookup.
+- **Rate limiting**: BA ships its own (`rateLimit.storage: 'secondary-storage'`) for auth endpoints; arc's `rateLimit.skipPaths: ['/api/auth/*']` guidance composes — exempt BA routes from arc's bucket, let BA's limiter own its own surface.
+
 > **Arc 2.13+ requires `auth.api.*`** — pass a real `betterAuth()` instance. The pre-2.13 HTTP fallback for org/team lookups was retired.
 
 #### Table-side overlay — read BA's tables as arc resources
@@ -91,7 +104,7 @@ Better Auth writes its own tables (`user`, `organization`, `member`, `invitation
 ```typescript
 import { betterAuth } from 'better-auth';
 import { mongodbAdapter } from '@better-auth/mongo-adapter';
-import { organization } from 'better-auth/plugins';
+import { organization } from 'better-auth/plugins/organization'; // dedicated path — tree-shaking (BA best practice)
 import mongoose from 'mongoose';
 import {
   createBetterAuthOverlay,
@@ -160,7 +173,7 @@ Same parallel structure as mongokit. The factory derives the Drizzle table dynam
 import Database from 'better-sqlite3';
 import { drizzle } from 'drizzle-orm/better-sqlite3';
 import { betterAuth } from 'better-auth';
-import { organization } from 'better-auth/plugins';
+import { organization } from 'better-auth/plugins/organization'; // dedicated path — tree-shaking (BA best practice)
 import { createBetterAuthOverlay } from '@classytic/sqlitekit/better-auth';
 
 const sqlite = new Database('app.db');
@@ -239,7 +252,11 @@ The `auth.api.*` direct in-process API map and `auth.$context.tables` schema int
 ```typescript
 import { betterAuth } from 'better-auth';
 import { mongodbAdapter } from '@better-auth/mongo-adapter';
-import { admin, organization, twoFactor, bearer } from 'better-auth/plugins';
+// Dedicated paths per plugin — tree-shaking (BA best practice; never the barrel)
+import { admin } from 'better-auth/plugins/admin';
+import { organization } from 'better-auth/plugins/organization';
+import { twoFactor } from 'better-auth/plugins/two-factor';
+import { bearer } from 'better-auth/plugins/bearer';
 import { apiKey } from '@better-auth/api-key';
 import { createBetterAuthOverlay, registerBetterAuthStubs } from '@classytic/mongokit/better-auth';
 
@@ -367,7 +384,7 @@ The plugin also adds a required `configId` field on `apikey` rows and uses `refe
 For non-cookie clients (React Native, native mobile, headless SPA), enable `bearer()` so sessions travel as `Authorization: Bearer <session-token>` instead of cookies. Same `auth.api.getSession()` path, just a different transport.
 
 ```typescript
-import { bearer } from 'better-auth/plugins';
+import { bearer } from 'better-auth/plugins/bearer'; // dedicated path — tree-shaking
 const auth = betterAuth({ plugins: [bearer(), organization()] });
 ```
 

package/skills/arc/references/mcp.md

@@ -151,7 +151,7 @@ Full MCP spec-compliant OAuth 2.1: authorization code + PKCE, token exchange, dy
 
 ```typescript
 // auth.config.ts — add mcp() plugin to Better Auth
-import { mcp } from 'better-auth/plugins';
+import { mcp } from 'better-auth/plugins/mcp'; // dedicated path — tree-shaking
 betterAuth({ plugins: [mcp({ loginPage: '/login' })] });
 
 // app.ts

package/skills/arc/references/production.md

@@ -79,7 +79,26 @@ await fastify.register(auditPlugin, {
   enabled: true,
   repository: new Repository(AuditModel),
 });
-// TTL / retention owned by your DB (TTL index on `timestamp`, cron DELETE, etc.)
+// ── Retention (audit rows ARE `history: true` timelines — prune together) ──
+// Option A (zero code, Mongo): TTL index — the DB does it server-side.
+//   AuditSchema.index({ timestamp: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 365 });
+// Option B (built-in, single instance): retention: { maxAgeMs, purgeIntervalMs }.
+// Option C (multi-replica, RECOMMENDED): purgeIntervalMs: 0 + a schedulesPlugin
+//   entry calling fastify.audit.purge(cutoff) — leader-safe, jittered, observable.
+//   (The built-in timer runs on EVERY replica — idempotent but wasteful.)
+//
+// ── Indexes (kit territory — the audit model is yours) ──
+// Mongo: TTL index above + compound for the history timeline:
+//   AuditSchema.index({ resource: 1, documentId: 1, timestamp: -1 });
+// SQL kits: index (resource, document_id, timestamp) + the kit's ttl/sweep plugin.
+//
+// ── Rich search (admin audit-log UI) ──
+// audit.query() is deliberately narrow. For full repo-core filter/sort/keyset
+// power + MCP tools, mount the audit repo AS a read-only resource:
+//   defineResource({ name: 'audit-log', crud: { list: true, get: true },
+//     adapter: { repository: auditRepo },
+//     queryParser: new QueryParser({ allowedFilterFields: ['resource','documentId','userId','action','organizationId'] }),
+//     permissions: { list: requireRoles(['auditor']), get: requireRoles(['auditor']) } });
 
 // Usage
 await fastify.audit.create('product', product._id, product, request.auditContext);
@@ -452,7 +471,30 @@ Production preset: `maxEventLoopDelay: 3000` (avoids false 503s on Render/Railwa
 
 ## CORS
 
-Production warns (not throws) when origin missing. `origin: '*'` from env is allowed. Smart CORS auto-converts `credentials: true` + `origin: '*'` to `origin: true`.
+Production warns (not throws) when origin missing. `origin: '*'` from env is allowed. Smart CORS auto-converts `credentials: true` + `origin: '*'` to `origin: true`, and (2.22) auto-merges arc's protocol headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into any host-declared `allowedHeaders` allow-list — hosts never enumerate framework internals.
+
+### Mobile apps (Capacitor / Ionic / React Native webviews)
+
+Arc needs no special mode — mobile is a CORS + auth-transport recipe:
+
+```typescript
+cors: {
+  // Webview origins alongside your web domains. Also add these to
+  // Better Auth's trustedOrigins when using BA.
+  origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
+  credentials: true,
+  // Optional allow-list — arc's own headers auto-merge (2.22); you only
+  // list YOUR custom ones. Omit entirely to use reflection mode.
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  // BA bearer plugin returns the fresh session token in this RESPONSE
+  // header — without exposing it, cross-origin JS cannot READ it and
+  // app login dies silently. The one mobile knob arc can't infer.
+  exposedHeaders: ['set-auth-token'],
+},
+trustProxy: true,   // webviews arrive through your LB/tunnel
+```
+
+Native (non-webview) HTTP clients send no `Origin` header — CORS doesn't apply to them at all; bearer auth just works.
 
 ## Metrics Plugin
 

package/skills/arc-code-review/SKILL.md

@@ -84,7 +84,7 @@ One `defineResource()` call **replaces all of these** in a typical Fastify servi
 ```markdown
 # Arc Convention Audit — <project-name>
 
-**Arc version:** 2.16.x · **Mongokit:** <version or "not installed"> · **Sqlitekit:** <version or "n/a"> · **Date:** <YYYY-MM-DD>
+**Arc version:** <installed version> · **Mongokit:** <version or "not installed"> · **Sqlitekit:** <version or "n/a"> · **Date:** <YYYY-MM-DD>
 **Files scanned:** <N> · **Findings:** <N critical · <N high · <N medium · <N low>
 
 ## Executive summary

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

@@ -565,6 +565,8 @@ resources: async () => loadResources(import.meta.url, { context: { engine } }),
 // Each *.resource.ts then exports: (ctx) => defineResource({ adapter: ctx.engine.adapter() })
 ```
 
+For the DB **connection** itself (as opposed to engines), arc 2.21 adds `createApp({ beforeBoot: async () => connectDatabase() })` — awaited before Fastify exists, before module thunks resolve, and before any resource file imports. A composition root that connects the DB then dynamic-imports the app to control evaluation order is the pre-2.21 workaround; flag it and move the connect into `beforeBoot`.
+
 ---
 
 ## §21. Field-write denied as silent strip when reject is needed (or vice versa) 🟡
@@ -803,31 +805,19 @@ const userId = requireUserId(scope, 'finalize-checkout');    // hint surfaces in
 
 ---
 
-## §32f. `createMongooseAdapter` without `schemaGenerator` 🟠
+## §32f. Missing / dodged `schemaGenerator` 🟠
 
 **Detection:**
 ```
 pattern: "createMongooseAdapter\\s*\\(\\s*\\{[^}]*\\}\\s*\\)"
 multiline: true
 ```
-Then check whether the object literal includes a `schemaGenerator:` key.
-
-Also: `createDrizzleAdapter` without `schemaGenerator: buildCrudSchemasFromTable`.
+Then check the `schemaGenerator:` key — what to flag depends on the kit version:
 
-**Why high:** Arc 2.12 deleted the built-in mongoose / drizzle schema-gen fallback (~290 LOC). If `schemaGenerator` is omitted, OpenAPI bodies are emitted as `null` rather than silently inferred — the route still serves traffic but the docs / MCP tool input schemas are empty.
+- **mongokit >=3.21**: `schemaGenerator` DEFAULTS to `buildCrudSchemasFromModel` — omitting it is now correct. Flag the opposite: `schemaGenerator: false` used to dodge a wire-vs-model shape mismatch (minor-unit integers vs Money objects, enums, etc.). That opt-out silently kills OpenAPI bodies AND MCP tool input schemas for the whole resource. The right fix is a real wire contract: `customSchemas: { create: { body }, update: { body } }` with the generator ON — in arc 2.21 a custom part REPLACES the generated part wholesale (no `required[]` union), so wire and model shapes can differ cleanly.
+- **mongokit <3.21**: omitted `schemaGenerator` emits `null` OpenAPI bodies (arc 2.12 deleted the built-in fallback). Fix: upgrade the kit, or wire `schemaGenerator: buildCrudSchemasFromModel` explicitly.
 
-**Fix:**
-```typescript
-import { createMongooseAdapter } from '@classytic/mongokit/adapter';   // arc 2.12+
-import { buildCrudSchemasFromModel } from '@classytic/mongokit';
-
-createMongooseAdapter({
-  model: ProductModel,
-  repository: productRepo,
-  schemaGenerator: buildCrudSchemasFromModel,   // required
-});
-```
-For drizzle: `import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter'` + `schemaGenerator: buildCrudSchemasFromTable` from `@classytic/sqlitekit`.
+For drizzle: `createDrizzleAdapter` still wants `schemaGenerator: buildCrudSchemasFromTable` from `@classytic/sqlitekit` — check the kit's own version before flagging.
 
 ---
 
@@ -937,6 +927,68 @@ For backends without `repo.aggregate`, declare a `materialized` hook on the aggr
 
 ---
 
+## §34. `as never` / `as unknown as` casts on engine bags in module packages 🟠
+
+**Detection:**
+```
+pattern: "as never|as unknown as"
+```
+Concentrated hits in `@classytic/arc-*` (or `@scope/arc-*`) module packages — especially around `defineResource(...)` assembly, adapter construction from an engine, or hand-rolled config spread-merges.
+
+**Anti-pattern (pre-2.21 module-author tax):**
+```typescript
+interface EngineLike { models: Record<string, unknown>; repositories: Record<string, unknown> }
+adapter: createMongooseAdapter(engine.models.Party as never, repo as never),
+...(cfg.extraRoutes ? { routes: [...base.routes, ...cfg.extraRoutes] as never } : {}),
+```
+
+**Why high:** every cast is a hole where the kernel's real types (optional sub-module members, role unions, doc shapes) stop flowing — typos compile, wrong repos pair with wrong models, and hand-rolled spread-merges clobber host arrays.
+
+**Fix (arc 2.21):** type the engine port with the KERNEL's own bags and assemble via `mergeResourceConfig`:
+```typescript
+import { mergeResourceConfig, type ResourceSeams, type AdapterLike } from '@classytic/arc';
+
+interface CatalogEngineLike {                    // kernel is already a peer — no new coupling
+  models: CatalogEngine['models'];
+  repositories: CatalogEngine['repositories'];
+}
+defineResource(mergeResourceConfig(
+  { name: 'product', adapter: createMongooseAdapter({ model: models.Product, repository: repositories.product }), ... },
+  hostSeams,                                     // typed ResourceSeams — arrays concat, objects deep-merge,
+));                                              // instances last-win, undefined never clobbers
+```
+Remaining honest boundaries (hydrated-vs-lean id widening at a kernel bridge, wire-body narrowing in action handlers) get a comment, not a blanket `as never`.
+
+---
+
+## §35. Hand-rolled recurring jobs (`setInterval` / cron + DB lock) 🟠
+
+**Detection:**
+```
+pattern: "setInterval\\s*\\(|node-cron|cron\\.schedule|new CronJob"
+```
+Plus home-grown "job registry" / "leader lock" / "acquireLock" modules paired with timers.
+
+**Why high:** every host regrows the same layer — overlap prevention, multi-replica leader lock, shutdown timer cleanup, failure counters — and gets at least one of them wrong (stacking `setInterval` runs, timers holding the process open, no lease recovery after a crashed leader).
+
+**Fix (arc 2.21):** `schedulesPlugin` from `@classytic/arc/plugins` — interval jobs with no-overlap by construction (timeout chain), optional `lock` (any `LockAdapter`: `@classytic/mongokit/lock`, sqlitekit, memory) for multi-replica lease safety, `jitterMs`, `runOnStart`, `getScheduleStats()`, clean `onClose` drain. Calendar cron-expressions / durable retries stay in the BullMQ tier (`@classytic/arc/integrations/jobs`) — don't flag hosts that need real cron semantics for using it.
+
+---
+
+## §36. Wrong tenant config key — `{ field }` instead of `{ tenantField }` 🔴
+
+**Detection:**
+```
+pattern: "tenant:\\s*\\{\\s*field\\s*:"
+```
+Also any object passed as tenant config whose keys aren't in repo-core's `TenantConfig`.
+
+**Why critical:** unknown keys are **silently ignored** — `{ tenant: { field: 'branchId' } }` compiles (loose host types), the resource falls back to the default tenant field, and cross-tenant reads/writes go unscoped for hosts on a custom field name. Found live in published spine packages (arc-assets / arc-pricelist 0.1.x).
+
+**Fix:** the key is `tenantField` (repo-core `TenantConfig`). In arc resources prefer the top-level `tenantField: 'branchId'` shorthand or the `multiTenant` preset; when passing a tenant object through a module seam, type it as `TenantConfig` so unknown keys fail the build.
+
+---
+
 ## Detection checklist (run-order)
 
 Run sweeps in this order — early hits often invalidate later context:
@@ -951,5 +1003,6 @@ Run sweeps in this order — early hits often invalidate later context:
 8. §7, §8, §22, §23 — events/cache/idempotency/audit (silent inconsistency)
 9. §14, §18, §19 — preset adoption + custom controller wiring
 10. §11, §12, §13, §29, §30, §31 — style and edges
-11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
+11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing/dodged `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
 12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`
+13. §36 — tenant config `{ field }` key (security: silent unscoped queries), then §34–§35 — module-package `as never` casts vs 2.21 seams; hand-rolled recurring jobs vs `schedulesPlugin`

package/skills/arc-code-review/references/arc-cheatsheet.md

@@ -23,12 +23,22 @@ A condensed map of what arc provides, so during audit you can spot what the team
 | Custom `withRetry` / `withDLQ` plumbing on events | `RedisStreamTransport` (durable, consumer groups, DLQ) |
 | Hand-rolled idempotency token check | `idempotencyPlugin` (header-based, configurable store) |
 | Manual SCIM provisioning endpoints | `@classytic/arc/scim` — `scimPlugin({ users, groups, bearer })` |
+| `setInterval` sweeps + hand-rolled leader lock / job registry | `schedulesPlugin` from `@classytic/arc/plugins` (2.21 — interval jobs, LockAdapter lease, no Redis) |
+| `as never` casts + spread-merges assembling resources in module packages | `mergeResourceConfig` + `ResourceSeams` (2.21) with kernel-typed engine ports |
+| Same `view`/`manage` gate repeated across 5 CRUD keys | `permissionMatrix({ read, write, delete? })` (2.21) |
+| DB connect + dynamic-import ordering in the composition root | `createApp({ beforeBoot })` (2.21 — runs before Fastify + all imports) |
+| `import { x } from 'better-auth/plugins'` (barrel) | dedicated path `better-auth/plugins/<name>` — tree-shaking (BA best practice) |
+| Hand-rolled per-tenant usage/billing counters | `usagePlugin` from `@classytic/arc/usage` (2.22 — per-actor per-period counters, fail-safe, `UsageStore` backends) |
+| Per-plan rate limits via custom middleware | `rateLimit.plan { resolve, limits, default }` (2.22 — `false` = unlimited, fail-safe fallback, tenant-keyed buckets) |
+| Hand-built audit-timeline endpoints (`GET /:id/history` handlers over audit rows) | `history: true` on `defineResource` (2.22 — implies `audit: true`, stricter-than-read gate) |
 
 ## Boot order (FIXED)
 
 ```
+0. beforeBoot()     ← pre-everything (DB connect; before Fastify + imports) — 2.21
+0.5 module resolve  ← thunk imports + dependsOn topo-sort; module errorMappers merge
 1. Arc core (security, auth, events)
-2. plugins()        ← user infra (DB, docs, webhooks)
+2. plugins()        ← user infra (docs, webhooks)
 3. bootstrap[]      ← domain init (engines, singletons)
 4. resources (factory runs after bootstrap)
 5. resources[]      ← register each
@@ -54,7 +64,7 @@ defineResource({
   rateLimit?, tenantField?, idField?,
   prefix?, skipGlobalPrefix?,
   queryParser?, onFieldWriteDenied?,
-  audit?, mcp?,                                     // mcp: false to exclude from MCP tool gen
+  audit?, history?, mcp?,                           // mcp: false to exclude from MCP tool gen; history: true → GET /:id/history (2.22)
   displayName?, module?,
   onTenantDelete?,                                  // GDPR cascade strategy
 });
@@ -69,6 +79,7 @@ requireRoles(['admin'])                    requireServiceScope('jobs:bulk')
 requireOwnership('userId')                 requireScopeContext('branchId')
 requireOrgMembership()                     requireOrgInScope(targetId)
 allOf(...) · anyOf(...) · not(...) · when(...) · denyAll()
+permissionMatrix({ read, write, delete? })        // 2.21 — expands to the full CRUD map
 createDynamicPermissionMatrix({ resolveRolePermissions, cacheStore })
 ```
 
@@ -159,7 +170,9 @@ import type { DataAdapter, RepositoryLike } from '@classytic/repo-core/adapter';
 
 ```typescript
 import { defineResource, BaseController, allowPublic }    from '@classytic/arc';
+import { mergeResourceConfig, type ResourceSeams }         from '@classytic/arc';         // 2.21
 import { createApp, loadResources }                        from '@classytic/arc/factory';
+import { schedulesPlugin }                                 from '@classytic/arc/plugins'; // 2.21
 import { MemoryCacheStore, RedisCacheStore, QueryCache }   from '@classytic/arc/cache';
 import { eventPlugin, EventOutbox }                        from '@classytic/arc/events';
 import { RedisEventTransport, RedisStreamTransport }       from '@classytic/arc/events/redis-stream';

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

@@ -21,13 +21,13 @@ In arc 2.12:
 
 ### Coordinated versions
 
-| Package | Min |
-|---|---|
-| `@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 |
+| Package | Min (adapter split) | Current best-practice floor |
+|---|---|---|
+| `@classytic/arc` | 2.12.0 | 2.21.0 — seams/`mergeResourceConfig`, `beforeBoot`, `permissionMatrix`, `schedulesPlugin` |
+| `@classytic/repo-core` | 0.4.0 | 0.9.0 — `StandardRepo.getByIds` contract member |
+| `@classytic/mongokit` | 3.13.0 | 3.21.0 — adapter `schemaGenerator` defaults ON |
+| `@classytic/sqlitekit` | 0.3.0 | 0.7.0 |
+| `@classytic/prismakit` | 0.1.0 | 0.1.0 |
 
 ### Import migration table
 

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

@@ -200,13 +200,14 @@ export const userRepo = new Repository<UserDoc>(User, [
 // resources/user/user.resource.ts — arc resource consuming the mongokit repo
 import { defineResource, requireRoles, allowPublic, fields } from '@classytic/arc';
 import { createMongooseAdapter } from '@classytic/mongokit/adapter';   // arc 2.12+: from the kit
-import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 import { User } from '../../models/user.js';
 import { userRepo } from '../../repositories/userRepository.js';
 
 export const userResource = defineResource({
   name: 'user',
-  adapter: createMongooseAdapter({ model: User, repository: userRepo, schemaGenerator: buildCrudSchemasFromModel }),
+  // mongokit >=3.21 defaults schemaGenerator to buildCrudSchemasFromModel
+  // (pre-3.21: wire it explicitly, or OpenAPI/MCP bodies come out null)
+  adapter: createMongooseAdapter({ model: User, repository: userRepo }),
   presets: ['softDelete'],          // multiTenant is at the repo layer (mongokit), so we don't need the arc preset too — pick one
   permissions: {
     list:   requireRoles(['admin']),
@@ -344,7 +345,7 @@ For each Mongoose model in the project:
 
 If consumers see `as unknown as RepositoryLike<T>` casts when wiring a repo into the mongoose adapter, that's drift. Mongokit's `tests/unit/standard-repo-assignment.test-d.ts` proves whole-interface assignment via TypeScript. Run `npm run typecheck:tests` in mongokit; if it fails, the published version drifted from the contract — pin to a known-good version or open a PR.
 
-In the client project, prefer `createMongooseAdapter({ model, repository, schemaGenerator })` from `@classytic/mongokit/adapter` over manual `RepositoryLike` shaping — it accepts mongokit-native repos with no casts.
+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