@classytic/arc 2.10.8 → 2.11.1

package/dist/websocket-CyJ1VIFI.d.mts

@@ -0,0 +1,186 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/websocket/adapter.d.ts
+/**
+ * WebSocket cross-instance adapter contract.
+ *
+ * The adapter is NOT used for local broadcasts — `RoomManager` handles those.
+ * The adapter only handles the cross-instance relay (Redis pub/sub, NATS, etc.)
+ * so a message broadcast on instance A is also delivered to clients connected
+ * to instance B.
+ *
+ * Implementations:
+ *   - `LocalWebSocketAdapter` (here) — no-op, single-instance only
+ *   - `RedisWebSocketAdapter` (@classytic/arc/integrations/websocket-redis)
+ *
+ * Custom adapters just need to satisfy the interface.
+ */
+/**
+ * Adapter interface for cross-instance WebSocket broadcast.
+ *
+ * - `publish()`: Send a message to all instances (via Redis, NATS, etc.)
+ * - `subscribe()`: Receive messages from other instances
+ * - `close()`: Clean up connections
+ */
+interface WebSocketAdapter {
+  /** Adapter name for logging */
+  readonly name: string;
+  /** Publish a room broadcast to all other instances */
+  publish(room: string, message: string): Promise<void>;
+  /** Subscribe to broadcasts from other instances */
+  subscribe(callback: (room: string, message: string) => void): Promise<void>;
+  /** Close adapter connections */
+  close(): Promise<void>;
+}
+/**
+ * Default adapter — no cross-instance broadcast (single-instance only).
+ * All methods are no-ops. Used when no adapter is configured.
+ */
+declare class LocalWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "local";
+  publish(): Promise<void>;
+  subscribe(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/integrations/websocket/types.d.ts
+/**
+ * A connected WebSocket client — one entry per TCP socket.
+ *
+ * `subscriptions` is mutated by `RoomManager`; other fields are set once at
+ * handshake time and treated as effectively immutable for the lifetime of
+ * the connection.
+ */
+interface WebSocketClient {
+  id: string;
+  socket: {
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+  };
+  subscriptions: Set<string>;
+  userId?: string;
+  organizationId?: string;
+  /** OAuth client ID — present for service/machine-to-machine connections */
+  clientId?: string;
+  /** OAuth scopes — present for service/machine-to-machine connections */
+  scopes?: readonly string[];
+  metadata?: Record<string, unknown>;
+}
+interface WebSocketMessage {
+  type: string;
+  resource?: string;
+  channel?: string;
+  data?: unknown;
+}
+/**
+ * Result of a successful authentication. The plugin's handshake and the
+ * optional re-auth loop both return this shape so the downstream code
+ * doesn't branch on auth mode. `null` means rejected.
+ */
+interface AuthResult {
+  userId?: string;
+  organizationId?: string;
+  /** Set for machine-to-machine / service account auth */
+  clientId?: string;
+  /** OAuth scopes for service accounts */
+  scopes?: readonly string[];
+}
+interface WebSocketPluginOptions {
+  /** WebSocket endpoint path (default: '/ws') */
+  path?: string;
+  /** Require authentication for WebSocket connections (default: true) */
+  auth?: boolean;
+  /** Resources to auto-broadcast CRUD events for */
+  resources?: string[];
+  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */
+  heartbeatInterval?: number;
+  /** Custom authentication function for WebSocket upgrade */
+  authenticate?: (request: unknown) => Promise<AuthResult | null>;
+  /** Max clients per resource subscription (default: 10000) */
+  maxClientsPerRoom?: number;
+  /**
+   * Expose a stats endpoint at `{path}/stats`.
+   * - `false` (default): stats endpoint is not registered
+   * - `true`: registered without auth
+   * - `'authenticated'`: guarded by `fastify.authenticate` if available
+   */
+  exposeStats?: boolean | "authenticated";
+  /**
+   * Authorize room subscriptions. Return true to allow, false to deny.
+   * Called before every subscribe. If not provided, all rooms are allowed.
+   */
+  roomPolicy?: (client: WebSocketClient, room: string) => boolean | Promise<boolean>;
+  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */
+  maxMessageBytes?: number;
+  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
+  maxSubscriptionsPerClient?: number;
+  /**
+   * Periodic re-authentication interval in ms (default: 0 = disabled).
+   * When set, the server periodically re-validates the client's auth token.
+   * If the token is expired/revoked, the client is disconnected with code 4003.
+   *
+   * Recommended: 300000 (5 minutes) for production.
+   *
+   * @example
+   * ```typescript
+   * websocketPlugin({ reauthInterval: 5 * 60 * 1000 }) // re-check every 5 min
+   * ```
+   */
+  reauthInterval?: number;
+  /** Custom message handler */
+  onMessage?: (client: WebSocketClient, message: WebSocketMessage) => void | Promise<void>;
+  /** Called when a client connects */
+  onConnect?: (client: WebSocketClient) => void | Promise<void>;
+  /** Called when a client disconnects */
+  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;
+  /**
+   * Cross-instance broadcast adapter (default: LocalWebSocketAdapter — single-instance only).
+   * Provide a RedisWebSocketAdapter for multi-instance deployments.
+   *
+   * @example
+   * ```typescript
+   * import { RedisWebSocketAdapter } from '@classytic/arc/integrations/websocket-redis';
+   * adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })
+   * ```
+   */
+  adapter?: WebSocketAdapter;
+}
+//#endregion
+//#region src/integrations/websocket/plugin.d.ts
+/** Pluggable WebSocket integration for Arc */
+declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
+//#endregion
+//#region src/integrations/websocket/room-manager.d.ts
+declare class RoomManager {
+  private rooms;
+  private clients;
+  private maxPerRoom;
+  private adapter?;
+  constructor(maxPerRoom?: number, adapter?: WebSocketAdapter);
+  addClient(client: WebSocketClient): void;
+  removeClient(clientId: string): void;
+  subscribe(clientId: string, room: string): boolean;
+  unsubscribe(clientId: string, room: string): void;
+  broadcast(room: string, message: string, excludeClientId?: string): void;
+  broadcastToOrg(organizationId: string, room: string, message: string): void;
+  /**
+   * Broadcast locally AND through adapter (for cross-instance delivery).
+   * Use this instead of broadcast() when multi-instance is possible.
+   */
+  broadcastWithAdapter(room: string, message: string, excludeClientId?: string): Promise<void>;
+  /**
+   * Org-scoped broadcast locally AND through adapter.
+   * Uses a namespaced room key for the adapter so other instances
+   * can filter by org when delivering locally.
+   */
+  broadcastToOrgWithAdapter(organizationId: string, room: string, message: string): Promise<void>;
+  getClient(clientId: string): WebSocketClient | undefined;
+  getStats(): {
+    clients: number;
+    rooms: number;
+    subscriptions: Record<string, number>;
+  };
+}
+//#endregion
+export { WebSocketMessage as a, WebSocketAdapter as c, WebSocketClient as i, websocketPlugin as n, WebSocketPluginOptions as o, AuthResult as r, LocalWebSocketAdapter as s, RoomManager as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.10.8",
+  "version": "2.11.1",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -233,15 +233,16 @@
     "test:e2e": "vitest run tests/e2e",
     "test:unit": "vitest run tests/core tests/hooks tests/utils tests/plugins",
     "smoke": "node scripts/smoke-test.mjs",
+    "push": "classytic-push",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.11.0",
+    "@classytic/mongokit": ">=3.11.1",
     "@classytic/repo-core": ">=0.2.0",
-    "@classytic/streamline": ">=2.1.0",
+    "@classytic/streamline": ">=2.2.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
     "@fastify/jwt": ">=10.0.0",
@@ -363,10 +364,11 @@
     "@better-auth/drizzle-adapter": "^1.6.2",
     "@better-auth/mongo-adapter": "^1.6.2",
     "@biomejs/biome": "^2.4.11",
-    "@classytic/mongokit": "^3.11.0",
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/mongokit": "^3.11.1",
     "@classytic/repo-core": "^0.2.0",
     "@classytic/sqlitekit": "^0.2.0",
-    "@classytic/streamline": "^2.1.0",
+    "@classytic/streamline": "^2.2.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.10.3
+version: 2.11.1
 license: MIT
 metadata:
   author: Classytic
-  version: "2.10.3"
+  version: "2.11.1"
 tags:
   - fastify
   - rest-api
@@ -62,27 +62,34 @@ const app = await createApp({
   preset: 'production',
   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
   cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') },
+  resources: [productResource, orderResource],   // canonical path — factory registers in the right lifecycle slot
 });
 
-await app.register(productResource.toPlugin());
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
-## v2.9 Security Defaults (breaking)
+For async-booted engines (repository wired in `bootstrap[]`), use the factory form:
 
-- **Field-write perms: `reject` (default)** — requests carrying non-writable fields get 403 with denied-field list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+```typescript
+resources: async (fastify) => {
+  const engine = await ensureCatalogEngine();
+  return [buildProductResource(engine), buildCategoryResource(engine)];
+}
+```
+
+Advanced escape hatch: `await app.register(productResource.toPlugin())` registers a single resource directly. Use only when you need manual control over the scope/prefix — the `resources` factory option is preferred.
+
+## Security defaults (active in 2.11)
+
+- **Field-write perms: `reject`** — requests carrying non-writable fields get 403 with denied-field list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
 - **multiTenant injects org on UPDATE** — body-supplied `organizationId` overwritten with caller's scope. Closes tenant-hop vector.
-- **Elevation always emits `arc.scope.elevated` event** — audit via `fastify.events.subscribe(...)`.
-- **`verifySignature(body, ...)` throws on parsed body** — pass `req.rawBody`, not `req.body`.
-- **Upload `sanitizeFilename`** — strict by default (no `/ \ .. \0 >255ch`). Pass `false` / `'*'` / custom fn to relax.
+- **Elevation emits `arc.scope.elevated`** — audit via `fastify.events.subscribe(...)`.
+- **`verifySignature(body, ...)`** throws on parsed body — pass `req.rawBody`.
+- **Upload `sanitizeFilename`** strict by default. Pass `false` / `'*'` / custom fn to relax.
 - **Idempotency `namespace`** option for shared-store prod+canary deployments.
+- **`systemManaged` fields auto-strip from `required[]`** — framework-injected fields (tenant, audit) removed from create/update `required[]` so Fastify preValidation doesn't reject before arc's injection runs.
 
-## Removed in v2.9
-
-- `createActionRouter`, `buildActionBodySchema` — use `actions` on `defineResource`
-- `ResourceConfig.onRegister` — use `actions` or resource `hooks`
-- `AdditionalRoute` type + `resource.additionalRoutes` field — use `RouteDefinition` and `resource.routes` (single source of truth; no normalised mirror)
-- `wrapHandler` on route defs — derived from `!route.raw` at use-site (set `raw: true` to opt out of the arc pipeline)
+For removed APIs and version-by-version breaking changes, see [CHANGELOG.md](../../CHANGELOG.md). For the full tenant-pipeline walkthrough, see [docs/production-ops/tenant-pipeline.mdx](../../docs/production-ops/tenant-pipeline.mdx).
 
 ## defineResource()
 
@@ -105,24 +112,25 @@ const productResource = defineResource({
   },
   cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
 
-  // v2.8.1: routeGuards — auto-apply to ALL routes (CRUD + custom + preset)
+  // routeGuards — auto-apply to ALL routes (CRUD + custom + preset)
   routeGuards: [modeGuard, orgGuard.preHandler],
 
-  // v2.8.1: fieldRules constraints → auto-map to OpenAPI + AJV validation
+  // fieldRules — portable constraints + framework-injection hints
   schemaOptions: {
     fieldRules: {
       name: { minLength: 2, maxLength: 200, description: 'Product name' },
       price: { min: 0, max: 100000 },
       sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
       status: { enum: ['draft', 'active', 'archived'] },
-      deletedAt: { systemManaged: true },
+      deletedAt: { systemManaged: true },                 // arc stamps it — strip from body + required[]
+      priceMode: { nullable: true },                      // Zod .nullable() lost through Mongoose — widen to accept null
     },
   },
 
   // Custom routes (compose with presets — softDelete adds /deleted, /:id/restore)
   routes: [
-    { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
-    { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
+    { method: 'GET', path: '/stats', handler: 'getStats', permissions: requireAuth() },
+    { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: requireAuth() },
   ],
 
   // Actions — single POST /:id/action endpoint, discriminated on `action` body field
@@ -130,19 +138,20 @@ const productResource = defineResource({
     approve: async (id, data, req) => service.approve(id, req.user._id),
     cancel: {
       handler: async (id, data, req) => service.cancel(id, data.reason, req.user._id),
-      permissions: roles('admin'),
+      permissions: requireRoles('admin'),
       schema: { reason: { type: 'string' } },
     },
   },
-  actionPermissions: auth(),
+  actionPermissions: requireAuth(),
 });
 
-await fastify.register(productResource.toPlugin());
+// Register via createApp — canonical path:
+//   createApp({ resources: [productResource] })
 // Auto-generates: GET /, GET /:id, POST /, PATCH /:id, DELETE /:id
 // + softDelete preset adds: GET /deleted, POST /:id/restore
 ```
 
-## routeGuards + defineGuard (v2.8.1)
+## routeGuards + defineGuard
 
 Resource-level guards that apply to **every** route (CRUD + custom + preset):
 
@@ -171,7 +180,7 @@ defineResource({
   name: 'procurement',
   routeGuards: [modeGuard, orgGuard.preHandler],  // all routes protected
   routes: [{
-    method: 'GET', path: '/summary', raw: true, permissions: auth(),
+    method: 'GET', path: '/summary', raw: true, permissions: requireAuth(),
     handler: async (req, reply) => {
       const { orgId } = orgGuard.from(req);  // typed, no re-computation
       reply.send({ orgId, count: await Model.countDocuments() });
@@ -183,9 +192,9 @@ defineResource({
 
 **Execution order:** auth → permissions → cache/idempotency → `routeGuards` → per-route `preHandler`
 
-## fieldRules → OpenAPI + AJV (v2.8.1)
+## fieldRules → OpenAPI + AJV
 
-One definition, two outputs — constraints auto-map to OpenAPI schema + Fastify AJV validation:
+One definition, two outputs — constraints auto-map to OpenAPI schema + Fastify AJV validation. Extends repo-core's `FieldRule` floor with arc extensions.
 
 ```typescript
 schemaOptions: {
@@ -194,14 +203,29 @@ schemaOptions: {
     price: { min: 0, max: 100000 },
     sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
     status: { enum: ['draft', 'active', 'archived'] },
-    password: { hidden: true },           // blocked from select + OpenAPI
-    deletedAt: { systemManaged: true },   // blocked from input schemas
-    slug: { immutable: true },            // excluded from update body
+    password: { hidden: true },                   // blocked from select + OpenAPI
+    deletedAt: { systemManaged: true },           // blocked from input schemas; framework stamps it
+    slug: { immutable: true },                    // excluded from update body
+    priceMode: { nullable: true },                // widen JSON-Schema type to include null
+    organizationId: { systemManaged: true, preserveForElevated: true }, // tenant field (auto-injected)
   },
 },
 ```
 
-Mongoose model-level constraints (`minlength`, `maxlength`, `min`, `max`, `enum`) take precedence. `fieldRules` supplements what the model doesn't declare.
+| Flag | Effect |
+|---|---|
+| `systemManaged` | Strip from body on ingest, drop from `required[]`. Framework stamps the value (tenant, audit, engine-derived slug). |
+| `preserveForElevated` | Elevated admins keep the field on ingest (platform-level cross-tenant writes). |
+| `immutable` / `immutableAfterCreate` | Omit from update body. Inheritance: repo-core floor. |
+| `optional` | Strip from `required[]` without touching `properties`. |
+| `nullable` | Widen JSON-Schema `type` to include null (+ appends `null` to `enum` if present). |
+| `hidden` | Block from response projection + OpenAPI. |
+| `minLength` / `maxLength` / `min` / `max` / `pattern` / `enum` | Map to AJV validators + OpenAPI constraints. |
+| `description` | Maps to OpenAPI `description`. |
+
+Mongoose model-level constraints (`minlength`, `maxlength`, `min`, `max`, `enum`) take precedence. `fieldRules` supplements what the model doesn't declare. Kit schema generators see only the repo-core floor; arc's extensions apply post-kit via `mergeFieldRuleConstraints`.
+
+See [docs/framework-extension/custom-adapters.mdx — Field Rules](../../docs/framework-extension/custom-adapters.mdx#field-rules--shaping-kit-generated-schemas) for the `systemManaged` decision table.
 
 ## Authentication
 
@@ -665,22 +689,44 @@ defineResource({
 
 **Response header:** `x-cache: HIT | STALE | MISS`
 
-## BaseController
+## Controllers (v2.11 mixin split)
+
+`BaseController` was split in 2.11 from a 1,589-LOC god class into a mixin composition. `extends BaseController<Product>` still works exactly the same — a declaration-merged interface threads `TDoc` through every CRUD + preset method.
 
 ```typescript
 import { BaseController } from '@classytic/arc';
 import type { IRequestContext, IControllerResponse } from '@classytic/arc';
 
+// Full surface: CRUD + SoftDelete + Tree + Slug + Bulk
 class ProductController extends BaseController<Product> {
   constructor() { super(productRepo); }
 
-  async getFeatured(req: IRequestContext): Promise<IControllerResponse> {
+  async getFeatured(req: IRequestContext): Promise<IControllerResponse<Product[]>> {
     const products = await this.repository.getAll({ filters: { isFeatured: true } });
     return { success: true, data: products };
   }
 }
 ```
 
+**Slim CRUD-only surface** (869 LOC instead of 1,650):
+
+```typescript
+import { BaseCrudController } from '@classytic/arc';
+class ReportController extends BaseCrudController<Report> {}
+```
+
+**Pick specific mixins:**
+
+```typescript
+import { BaseCrudController, SoftDeleteMixin, BulkMixin } from '@classytic/arc';
+class OrderController extends SoftDeleteMixin(BulkMixin(BaseCrudController)) {}
+// → list/get/create/update/delete + getDeleted/restore + bulkCreate/bulkUpdate/bulkDelete
+```
+
+**Mixin surface:** `SoftDeleteMixin` (`getDeleted`, `restore`) · `TreeMixin` (`getTree`, `getChildren`) · `SlugMixin` (`getBySlug`) · `BulkMixin` (`bulkCreate`, `bulkUpdate`, `bulkDelete`). Each exported from `@classytic/arc` and `@classytic/arc/core`.
+
+**Shared helpers** (protected on `BaseCrudController` so mixins can extend): `meta(req)`, `getHooks(req)`, `tenantRepoOptions(req)`, `resolveRepoId(id, existing)`, `notFoundResponse(reason)`, `resolveCacheConfig(op)`, `cacheScope(req)`.
+
 **IRequestContext:** `{ params, query, body, user, headers, context, metadata, server }` — `user` is `Record<string, unknown> | undefined` (guard with `if (req.user)` on public routes)
 
 **IControllerResponse:** `{ success, data?, error?, status?, meta?, headers? }`
@@ -688,9 +734,15 @@ class ProductController extends BaseController<Product> {
 ## Adapters (Database-Agnostic)
 
 ```typescript
-// Mongoose
+// Mongoose — canonical arc factory
 import { createMongooseAdapter } from '@classytic/arc';
-const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
+import { buildCrudSchemasFromModel } from '@classytic/mongokit';
+
+const adapter = createMongooseAdapter({
+  model: ProductModel,
+  repository: productRepo,
+  schemaGenerator: buildCrudSchemasFromModel,   // ← no cast; RouteSchemaOptions extends SchemaBuilderOptions
+});
 
 // Custom adapter — implement MinimalRepo from @classytic/repo-core/repository:
 import type { MinimalRepo } from '@classytic/repo-core/repository';
@@ -699,6 +751,10 @@ import type { MinimalRepo } from '@classytic/repo-core/repository';
 // Arc feature-detects optional methods at call sites.
 ```
 
+- `createMongooseAdapter` is the **canonical arc export**. Use directly — no cast on `schemaGenerator` (arc's `RouteSchemaOptions extends SchemaBuilderOptions`; `ArcFieldRule extends FieldRule`).
+- `createAdapter` is a **CLI-scaffolded host wrapper** (`src/lib/adapter.ts`). Keep for scaffolded apps; hand-built apps should import `createMongooseAdapter` directly.
+- Built-in mongoose fallback detects `{ default: null }` on schema paths and widens the emitted JSON-Schema type automatically — no `fieldRules` entry needed for that case.
+
 ## Events
 
 The factory auto-registers `eventPlugin` — no manual setup needed:
@@ -873,6 +929,36 @@ const result = await withCompensation('checkout', [
 // result: { success, completedSteps, results, failedStep?, error?, compensationErrors? }
 ```
 
+## Testing
+
+Three entry points — pick by what you're testing. Full details in [references/testing.md](references/testing.md).
+
+```typescript
+import {
+  createTestApp,                 // turnkey Fastify + in-memory Mongo + auth + fixtures
+  createHttpTestHarness,         // auto-generates ~16 CRUD/permission/validation tests
+  expectArc,                     // fluent envelope matchers
+  createTestFixtures,            // DB-agnostic seeding with per-record destroyers
+} from '@classytic/arc/testing';
+
+const ctx = await createTestApp({
+  resources: [productResource],
+  authMode: 'jwt',                    // 'jwt' | 'better-auth' | 'none'
+  db: 'in-memory',                    // default
+  connectMongoose: true,              // one-liner for Mongoose-backed resources
+});
+ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
+
+const res = await ctx.app.inject({
+  method: 'POST', url: '/products',
+  headers: ctx.auth.as('admin').headers,
+  payload: { name: 'Widget' },
+});
+expectArc(res).ok().hidesField('password');
+```
+
+`TestAppContext` = `{ app, auth, fixtures, dbUri, close }`. `authMode: 'better-auth'` requires the caller to also pass `auth: { type: 'better-auth', ... }`.
+
 ## CLI
 
 ```bash
@@ -993,7 +1079,7 @@ const app = await createApp({
 
 `loadResources()` discovers files matching `*.resource.{ts,js,mts,mjs}`, recursively. Pass `import.meta.url` for dev/prod parity (resolves to `src/` in dev, `dist/` in prod automatically). Discovers `default` export, `export const resource`, OR any named export with `toPlugin()` (e.g., `export const userResource`).
 
-Options: `exclude`, `include`, `suffix`, `recursive`, `silent`.
+Options: `exclude`, `include`, `suffix`, `recursive`, `context`, `logger`. Silent by default — pass `logger: { warn(msg) {...} }` to receive skip / factory-failure diagnostics.
 
 **Per-resource opt-out of `resourcePrefix`** — for webhooks, admin routes:
 ```typescript
@@ -1138,9 +1224,8 @@ import { defineResource, BaseController, allowPublic } from '@classytic/arc';
 import { createApp } from '@classytic/arc/factory';
 import { MemoryCacheStore, RedisCacheStore, QueryCache } from '@classytic/arc/cache';
 import { createBetterAuthAdapter, extractBetterAuthOpenApi } from '@classytic/arc/auth';
-// 2.7.1+: optional Mongoose stub-models bridge for `populate()` against
-// Better Auth collections — only loaded if you import it (subpath gate
-// keeps Mongoose out of Prisma/Drizzle/Kysely bundles).
+// Optional Mongoose stub-models bridge for `populate()` against Better Auth
+// collections — subpath gate keeps Mongoose out of Prisma/Drizzle/Kysely bundles.
 import { registerBetterAuthMongooseModels } from '@classytic/arc/auth/mongoose';
 import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
 import { eventPlugin } from '@classytic/arc/events';
@@ -1158,7 +1243,7 @@ import { createTestApp } from '@classytic/arc/testing';
 import { Type, ArcListResponse } from '@classytic/arc/schemas';
 import { createStateMachine, CircuitBreaker, withCompensation, defineCompensation } from '@classytic/arc/utils';
 import { defineMigration } from '@classytic/arc/migrations';
-// Scope accessors — full surface as of 2.7.1
+// Scope accessors
 import {
   // Type guards
   isMember, isService, isElevated, isAuthenticated, hasOrgAccess,