@classytic/arc 2.21.0 → 2.23.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