@classytic/arc 2.19.0 → 2.20.0

package/dist/module-JYH9V0I8.d.mts

@@ -0,0 +1,384 @@
+import { FastifyInstance } from "fastify";
+
+//#region src/factory/loadResources.d.ts
+/**
+ * loadResources — Auto-discover resource files from a directory.
+ *
+ * Scans for `*.resource.{ts,js,mts,mjs}` files, imports each,
+ * and collects their default exports. No barrel file needed.
+ *
+ * @example
+ * ```ts
+ * import { createApp, loadResources } from '@classytic/arc/factory';
+ *
+ * // Recommended: import.meta.url — works in both src/ (dev) and dist/ (prod)
+ * const app = await createApp({
+ *   resources: await loadResources(import.meta.url),
+ *   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+ * });
+ *
+ * // Or explicit path (must match runtime layout)
+ * const app2 = await createApp({
+ *   resources: await loadResources('./src/resources'),
+ * });
+ * ```
+ *
+ * File convention:
+ * ```
+ * src/resources/
+ *   product/product.resource.ts    → export default defineResource({ name: 'product', ... })
+ *   order/order.resource.ts        → export default defineResource({ name: 'order', ... })
+ * ```
+ */
+/**
+ * Resource interface — the contract between `loadResources`/`createApp` and resource definitions.
+ *
+ * Matches the shape of `ResourceDefinition` from `defineResource()` without requiring
+ * the import. All properties except `toPlugin` are optional so plain objects work too:
+ *
+ * ```typescript
+ * // Full resource (from defineResource)
+ * const product = defineResource({ name: 'product', ... }); // satisfies ResourceLike
+ *
+ * // Minimal resource (plain object)
+ * const simple: ResourceLike = { name: 'ping', toPlugin: () => () => {} };
+ * ```
+ *
+ * **DO NOT add an index signature** (`[key: string]: unknown`) to this interface.
+ * Class instances (like `ResourceDefinition`) don't implicitly carry index signatures,
+ * so adding one here makes `ResourceDefinition` *unassignable* to `ResourceLike` —
+ * the exact opposite of the intent. TypeScript's structural typing already allows
+ * classes with extra properties to satisfy this interface without an index signature.
+ */
+interface ResourceLike {
+  /** Plugin factory — called by createApp to register routes */
+  toPlugin: () => unknown;
+  /** Resource name (used for route generation, logging, duplicate detection) */
+  name?: string;
+  /** Route prefix (default: `/${name}s`) */
+  prefix?: string;
+  /** Skip the global `resourcePrefix` from createApp — register at root */
+  skipGlobalPrefix?: boolean;
+  /** Display name for docs/OpenAPI */
+  displayName?: string;
+  /** Applied preset names */
+  _appliedPresets?: string[];
+}
+/**
+ * Resource module — what a `.resource.ts` file's default (or named) export
+ * may resolve to.
+ *
+ * Two shapes accepted:
+ *   1. **Plain `ResourceLike`** — the result of `defineResource({...})`.
+ *      Used as-is; no engine wiring needed.
+ *   2. **Factory `(ctx: TContext) => ResourceLike | Promise<ResourceLike>`**
+ *      — a function arc calls with the `context` from `LoadResourcesOptions`.
+ *      Eliminates the parallel `createXResource(engine)` factory files +
+ *      `exclude: [...]` bookkeeping that engine-bound resources used to need.
+ *
+ * Detection is by `typeof === 'function'`: `ResourceDefinition` instances
+ * (returned by `defineResource()`) are class instances (`typeof === 'object'`),
+ * so the two shapes are unambiguous in practice.
+ */
+type ResourceModule<TContext = unknown> = ResourceLike | ((ctx: TContext) => ResourceLike | Promise<ResourceLike>);
+interface LoadResourcesOptions<TContext = unknown> {
+  /** File pattern suffix (default: '.resource'). Matches `*.resource.{ts,js,mts,mjs}`. */
+  suffix?: string;
+  /** Recurse into subdirectories (default: true) */
+  recursive?: boolean;
+  /**
+   * Context passed to factory-style default exports. Resources whose default
+   * export is a function `(ctx) => ResourceLike` are called with this value;
+   * plain `ResourceLike` exports are returned unchanged.
+   *
+   * Use this to thread engine handles into engine-bound resources without
+   * creating parallel factory files outside `loadResources`'s sweep:
+   *
+   * ```ts
+   * // category.resource.ts
+   * import type { AppContext } from '#core/app/context.js';
+   * export default (ctx: AppContext) =>
+   *   defineResource({
+   *     name: 'category',
+   *     adapter: createMongooseAdapter(
+   *       ctx.catalog.models.Category,
+   *       ctx.catalog.repositories.category,
+   *     ),
+   *   });
+   *
+   * // create-arc-app-options.ts
+   * resources: async () => {
+   *   const [catalog, flow] = await Promise.all([
+   *     ensureCatalogEngine(),
+   *     ensureFlowEngine(),
+   *   ]);
+   *   return loadResources(import.meta.url, { context: { catalog, flow } });
+   * }
+   * ```
+   *
+   * Backwards compatible — pre-2.11.1 callers omit `context`, plain exports
+   * keep working unchanged. Factories that need a context but receive
+   * `undefined` should narrow defensively.
+   */
+  context?: TContext;
+  /**
+   * Resource names to exclude. Matched against the resource's `.name` property
+   * after import, so you use the resource name (not the filename).
+   *
+   * @example
+   * ```ts
+   * await loadResources('./src/resources', { exclude: ['debug', 'legacy-report'] })
+   * ```
+   */
+  exclude?: string[];
+  /**
+   * Resource names to include. When set, only matching resources are returned.
+   * Takes priority over `exclude`.
+   *
+   * @example
+   * ```ts
+   * // Only load these two resources (useful for testing or microservice splits)
+   * await loadResources('./src/resources', { include: ['product', 'order'] })
+   * ```
+   */
+  include?: string[];
+  /**
+   * Optional logger override for diagnostics. When omitted, warnings flow
+   * through arc's standard logger (`arcLog('loadResources')`) — same path
+   * as every other arc-internal warning, controlled by `ARC_SUPPRESS_WARNINGS=1`
+   * and routable via `configureArcLogger({ writer })`.
+   *
+   * Pass any object with `warn(msg)` to override (e.g. `fastify.log` —
+   * which is what `registerResources` passes automatically when arc's
+   * factory triggers auto-discovery via `resourceDir`).
+   *
+   * Pre-2.11.1 had a `silent: boolean` flag and "silent by default" semantics;
+   * both removed. Migration:
+   *
+   * ```ts
+   * // Pre-2.11.1                                // 2.11.1+
+   * loadResources(url, { silent: true });            // ARC_SUPPRESS_WARNINGS=1 (env)
+   *                                                  //   OR configureArcLogger({ writer })
+   * loadResources(url, { silent: !isDev });          // ARC_SUPPRESS_WARNINGS=1 in prod
+   * loadResources(url, { logger: pinoAdapter });     // unchanged — still works
+   * ```
+   */
+  logger?: {
+    warn: (msg: string) => void;
+  };
+}
+/**
+ * Scan a directory for resource files and import their default exports.
+ *
+ * Accepts a directory path OR `import.meta.url` (file:// URL).
+ * When given a URL, resolves to the directory containing that file —
+ * so `loadResources(import.meta.url)` works in both dev (`src/`) and
+ * production (`dist/`) without path gymnastics.
+ *
+ * @param dir - Directory path, or `import.meta.url` (file:// URL resolved to its dirname)
+ * @param options - Pattern and recursion options
+ * @returns Array of resource definitions (anything with `.toPlugin()`)
+ *
+ * @example
+ * ```ts
+ * // Works from both src/ and dist/ — resolves relative to the calling file
+ * await loadResources(import.meta.url);
+ *
+ * // Subdirectory relative to the calling file
+ * await loadResources(import.meta.url, { suffix: '.resource' });
+ *
+ * // Explicit path (must match runtime layout)
+ * await loadResources('./src/resources');
+ * ```
+ */
+declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
+//#endregion
+//#region src/factory/module.d.ts
+interface ArcModule<TExports = unknown> {
+  /** Stable identifier — appears in boot logs and duplicate-module detection. */
+  readonly name: string;
+  /**
+   * Names of modules this one must be composed AFTER. arc topologically orders
+   * the `modules` array from these edges before ANY phase runs, so a
+   * dependency's `bootstrap` (and thus its `fastify.arc.modules[dep]` export)
+   * is always live before this module's bootstrap, resources, or
+   * afterResources. Teardown (`onClose`) runs in the reverse of that order.
+   *
+   * Use this instead of relying on list position when a module reads another's
+   * public export — e.g. `@classytic/arc-reservation` wiring off
+   * `arc.modules.order`:
+   *
+   * ```ts
+   * defineModule({ name: "reservation", dependsOn: ["order"], bootstrap: (f) => {
+   *   const order = getModuleExports<OrderEngine>(f, "order"); // guaranteed live
+   *   …
+   * }});
+   * ```
+   *
+   * The order is a STABLE topological sort: modules with no `dependsOn` (and
+   * any two modules with no edge between them) keep their original list order,
+   * so adding `dependsOn` never silently reorders an unrelated module. All
+   * failure modes are fail-fast at boot: a name not in the composed set, a
+   * self-reference, and dependency CYCLES each throw with the offending path.
+   *
+   * **`dependsOn` is COMPOSITION order, not lazy loading.** Every module input
+   * (including dynamic-import thunks) is resolved — imported — up front via
+   * `Promise.all` BEFORE the sort; `dependsOn` then orders the *composition*
+   * (which module's `plugins`/`bootstrap` runs first), it does NOT delay
+   * *importing* a dependent until its dependency is ready. Use a thunk to gate
+   * whether a module is imported at all (region/tier packs); use `dependsOn`
+   * to order modules that are already selected.
+   */
+  readonly dependsOn?: readonly string[];
+  /**
+   * Fastify plugins / decorators this module needs — the module-level analog
+   * of the app's `plugins()` slot. Runs in the plugins phase: AFTER the app's
+   * own `plugins()` (so module infra can build on app foundations like a DB
+   * connection) and in `dependsOn` order, but BEFORE any module `bootstrap` —
+   * so engines initialised in `bootstrap` can rely on what's registered here.
+   *
+   * Separating this from `bootstrap` keeps lifecycle intent explicit for
+   * published ecosystem packages: `plugins` = "register infra"; `bootstrap` =
+   * "initialise engines (and return the public export)". Registering a plugin
+   * inside `bootstrap` still works — this slot just makes the two distinct.
+   */
+  plugins?: (fastify: FastifyInstance) => void | Promise<void>;
+  /**
+   * Domain init — runs in the `bootstrap` phase (after all `plugins`, before
+   * resources). Initialize engines / singletons / event subscriptions here so
+   * they are live when this module's `resources` factory runs.
+   *
+   * A returned value becomes the module's PUBLIC EXPORT, recorded at
+   * `fastify.arc.modules[name]` (wiki/modules.md — "no container", layer 2).
+   * Later modules' bootstraps can read it (list order = init order), which is
+   * how cross-module ports are wired without a DI container. Declare the
+   * export shape via `defineModule<TExports>` and read it back with the typed
+   * accessor — no cast at the consuming end:
+   *
+   * ```ts
+   * // arc-invoice bootstrap, composed AFTER arc-accounting:
+   * const acct = getModuleExports<AccountingEngine>(fastify, "accounting");
+   * ```
+   */
+  bootstrap?: (fastify: FastifyInstance) => TExports | Promise<TExports>;
+  /**
+   * The module's resources. Array or factory — the factory form runs AFTER all
+   * bootstraps, so `defineResource(...)` receives fully-booted engines. Flows
+   * through arc's normal registration (prefix, dedup, docs), identical to a
+   * top-level `resources` entry.
+   */
+  resources?: ReadonlyArray<ResourceLike> | ((fastify: FastifyInstance) => ReadonlyArray<ResourceLike> | Promise<ReadonlyArray<ResourceLike>>);
+  /**
+   * Post-registration wiring — runs in the `afterResources` phase, once this
+   * module's routes are mounted. Use for cross-resource event subscriptions the
+   * module owns.
+   */
+  afterResources?: (fastify: FastifyInstance) => void | Promise<void>;
+  /**
+   * Teardown — registered as a Fastify `onClose` hook. Destroy engines, stop
+   * timers, flush the module's outbox. Modules close in REVERSE list order
+   * (last composed, first closed), mirroring init.
+   */
+  onClose?: (fastify: FastifyInstance) => void | Promise<void>;
+}
+/**
+ * A module in any of the forms `createApp({ modules })` accepts:
+ *
+ *   - `ArcModule`                      — eager (already imported)
+ *   - `Promise<ArcModule>`             — an in-flight import
+ *   - `() => ArcModule | Promise<…>`   — a thunk, resolved at boot
+ *
+ * The **thunk of a dynamic import** is the point of this union — it lets a host
+ * compose modules *logically* and load them *lazily / conditionally*, the
+ * `next/dynamic` idea applied to backend domains. The module's code (and its
+ * heavy deps) is only pulled in when the thunk runs, so region- or tier-gated
+ * packs never enter the bundle path they aren't selected for:
+ *
+ * ```ts
+ * const taxPack =
+ *   region === "BD"
+ *     ? () => import("@classytic/bd-tax").then((m) => m.createBdTaxModule(deps))
+ *     : () => import("@classytic/us-tax").then((m) => m.createUsTaxModule(deps));
+ *
+ * await createApp({ modules: [coreModule(deps), taxPack] });
+ * // only the selected tax package is imported + composed
+ * ```
+ */
+type ArcModuleInput<TExports = unknown> = ArcModule<TExports> | Promise<ArcModule<TExports>> | (() => ArcModule<TExports> | Promise<ArcModule<TExports>>);
+/**
+ * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+ * (this is where a dynamic `import()` fires); a promise (or plain module) is
+ * awaited. Called once per module at the start of the bootstrap phase.
+ */
+declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
+/**
+ * Order modules for composition by their `dependsOn` edges — a STABLE
+ * topological sort. Called once at the start of the bootstrap phase; every
+ * subsequent phase (bootstrap, resources, afterResources, and reverse-order
+ * onClose) iterates the returned list, so a module's declared dependencies are
+ * always composed before it.
+ *
+ * "Stable" = modules with no edge between them keep their original list order,
+ * so declaring `dependsOn` on one module never silently reorders an unrelated
+ * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+ * returned unchanged.
+ *
+ * Fail-fast — throws (never reorders past a broken contract) on:
+ *   - duplicate module names (the name is the graph key)
+ *   - a `dependsOn` name not present in the composed set
+ *   - a self-reference (`dependsOn` includes the module's own name)
+ *   - a dependency cycle (reports the concrete `a → b → … → a` path)
+ */
+declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
+/**
+ * Typed module registry — hosts augment this via declaration merging so
+ * `getModuleExports(f, "order")` infers the export type without a manual type
+ * argument (the fastify / awilix pattern):
+ *
+ * ```ts
+ * declare module "@classytic/arc/factory" {
+ *   interface ArcModuleRegistry {
+ *     order: OrderEngine;
+ *     accounting: AccountingEngine;
+ *   }
+ * }
+ * ```
+ *
+ * Left empty here so the fallback `getModuleExports<T>(f, name: string)` stays
+ * available for apps that don't augment it.
+ */
+interface ArcModuleRegistry {}
+/**
+ * Identity helper for authoring a typed module — mirrors `defineResource`.
+ * Gives inference + a single obvious construction site; does no work.
+ *
+ * `TExports` is inferred from the `bootstrap` return value, so a module
+ * author gets a typed public export for free:
+ *
+ * ```ts
+ * export const accountingModule = (deps: Deps) =>
+ *   defineModule({
+ *     name: "accounting",
+ *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+ *   });
+ * ```
+ */
+declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
+/**
+ * Typed accessor for a module's public export (its `bootstrap` return value),
+ * recorded at `fastify.arc.modules[name]`.
+ *
+ * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
+ * accessors): a missing entry means the module either isn't composed, is
+ * composed AFTER the caller (list order = init order), or returned nothing —
+ * all wiring bugs that must surface at boot, not as `undefined` downstream.
+ *
+ * The type parameter is an assertion, not a proof. Two ways to type it:
+ *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
+ *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
+ *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
+ */
+declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
+declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
+//#endregion
+export { getModuleExports as a, LoadResourcesOptions as c, loadResources as d, defineModule as i, ResourceLike as l, ArcModuleInput as n, orderModules as o, ArcModuleRegistry as r, resolveModule as s, ArcModule as t, ResourceModule as u };

package/dist/{openapi-DZ-5a5Op.mjs → openapi-Dq6RbEGK.mjs}

@@ -1,8 +1,8 @@
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
 import { n as convertRouteSchema } from "./schemaConverter-U0MnO9vd.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-D7NGwcAR.mjs";
-import { t as pluralize } from "./pluralize-DccFV9R7.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-B_WzBFyf.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-C9RMiIpc.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-HlQso0jO.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/permissions/index.d.mts

@@ -1,3 +1,3 @@
 import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, f as getUserRoles, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, p as normalizeRoles, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission, u as PermissionResult } from "../fields-C7ahdGYf.mjs";
-import { A as requireRoles, C as allOf, D as not, E as denyAll, F as RequireAgentScopeOptions, I as RequireMandateOptions, L as requireAgentScope, M as when, N as applyPermissionResult, O as requireAuth, P as normalizePermissionResult, R as requireDPoP, S as createOrgPermissions, T as anyOf, _ as ConnectEventsOptions, a as presets_d_exports, b as PermissionEventBus, c as readOnly, d as requireOrgRole, f as requireScopeContext, g as createRoleHierarchy, h as RoleHierarchy, i as ownerWithAdminBypass, j as roles, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig, z as requireMandate } from "../index-CRKiiP5o.mjs";
+import { A as requireRoles, C as allOf, D as not, E as denyAll, F as RequireAgentScopeOptions, I as RequireMandateOptions, L as requireAgentScope, M as when, N as applyPermissionResult, O as requireAuth, P as normalizePermissionResult, R as requireDPoP, S as createOrgPermissions, T as anyOf, _ as ConnectEventsOptions, a as presets_d_exports, b as PermissionEventBus, c as readOnly, d as requireOrgRole, f as requireScopeContext, g as createRoleHierarchy, h as RoleHierarchy, i as ownerWithAdminBypass, j as roles, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig, z as requireMandate } from "../index-CdFkIMEd.mjs";
 export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,3 +1,3 @@
-import { A as requireMandate, C as requireAuth, D as when, E as roles, F as applyFieldWritePermissions, I as fields, L as resolveEffectiveRoles, N as normalizePermissionResult, O as requireAgentScope, P as applyFieldReadPermissions, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyPermissionResult, k as requireDPoP, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-BPB1xqGf.mjs";
+import { A as requireMandate, C as requireAuth, D as when, E as roles, F as applyFieldWritePermissions, I as fields, L as resolveEffectiveRoles, N as normalizePermissionResult, O as requireAgentScope, P as applyFieldReadPermissions, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyPermissionResult, k as requireDPoP, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-CgbOLJZG.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
 export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/{permissions-BPB1xqGf.mjs → permissions-CgbOLJZG.mjs}

@@ -167,7 +167,7 @@ function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
 function resolveEffectiveRoles(userRoles, orgRoles) {
 	if (orgRoles.length === 0) return [...userRoles];
 	if (userRoles.length === 0) return [...orgRoles];
-	return [...new Set([...userRoles, ...orgRoles])];
+	return [.../* @__PURE__ */ new Set([...userRoles, ...orgRoles])];
 }
 //#endregion
 //#region src/permissions/applyPermissionResult.ts
@@ -1482,11 +1482,19 @@ function fullPublic(overrides) {
 /**
 * Read-only: list + get authenticated, write operations denied.
 * Useful for computed/derived resources.
+*
+* Writes carry an explicit `denyAll` check — an omitted CRUD permission
+* mounts the route with NO gate (public-by-omission), so leaving
+* create/update/delete undefined here would expose unauthenticated writes.
+* Hosts that disable write routes entirely (`disabledRoutes`) are unaffected.
 */
 function readOnly(overrides) {
 	return withOverrides({
 		list: requireAuth(),
-		get: requireAuth()
+		get: requireAuth(),
+		create: denyAll("Write operations are disabled on this read-only resource"),
+		update: denyAll("Write operations are disabled on this read-only resource"),
+		delete: denyAll("Write operations are disabled on this read-only resource")
 	}, overrides);
 }
 //#endregion

package/dist/pipeline/index.d.mts

@@ -1,4 +1,4 @@
-import { Bt as Transform, Ft as NextFunction, It as OperationFilter, Lt as PipelineConfig, Nt as Guard, Pt as Interceptor, Rt as PipelineContext, bt as IControllerResponse, zt as PipelineStep } from "../index-CUTG2Cuo.mjs";
+import { Bt as Transform, Ft as NextFunction, It as OperationFilter, Lt as PipelineConfig, Nt as Guard, Pt as Interceptor, Rt as PipelineContext, bt as IControllerResponse, zt as PipelineStep } from "../index-_--GyzcO.mjs";
 
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {

package/dist/plugins/index.d.mts

@@ -1,5 +1,5 @@
-import { Q as MiddlewareConfig, ft as RouteDefinition, ht as RouteSchemaOptions, nt as PresetHook, qt as AnyRecord } from "../index-CUTG2Cuo.mjs";
-import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-D-5_yQJi.mjs";
+import { Q as MiddlewareConfig, ft as RouteDefinition, ht as RouteSchemaOptions, nt as PresetHook, qt as AnyRecord } from "../index-_--GyzcO.mjs";
+import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-CCQJEDgh.mjs";
 import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6, v as _default$3, y as healthPlugin } from "../versioning-D_eBCfNr.mjs";
 import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-BtUUDPEa.mjs";
 import { t as TracingOptions } from "../tracing-D8jlGXP7.mjs";
@@ -24,10 +24,15 @@ interface CreatePluginDefinition<TRootOpts extends AnyRecord = AnyRecord, TResou
    */
   forRoot?: (fastify: FastifyInstance, opts: TRootOpts) => void | Promise<void>;
   /**
-   * Per-resource configuration function. Called for each resource that uses this plugin.
-   * Returns hooks, routes, middlewares, etc. to merge into the resource config.
+   * Per-resource configuration function. Called (via `plugin.forResource(opts)`)
+   * to PRODUCE a partial resource config — hooks, routes, middlewares — that the
+   * host spreads into `defineResource(...)`. It receives only the plugin's own
+   * `opts`: the resource does not exist yet at this call site, so it cannot be
+   * inspected here (that was a false promise pre-2.20; the unused `resourceConfig`
+   * parameter is removed). For behavior that must vary by resource, key off the
+   * plugin's `opts` the host passes per resource.
    */
-  forResource?: (resourceConfig: AnyRecord, opts: TResourceOpts) => PluginResourceResult;
+  forResource?: (opts: TResourceOpts) => PluginResourceResult;
 }
 interface ArcPlugin<TRootOpts extends AnyRecord = AnyRecord, TResourceOpts extends AnyRecord = AnyRecord> {
   /** Plugin name */

package/dist/plugins/index.mjs

@@ -1,9 +1,9 @@
-import { p as MUTATION_OPERATIONS } from "../constants-gaEeMlz-.mjs";
+import { p as MUTATION_OPERATIONS } from "../constants-DNre0wRg.mjs";
 import { c as getOrgId } from "../types-bHblZ9YN.mjs";
 import { n as requestContext } from "../requestContext-BZKOr13H.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
 import { t as HookSystem } from "../HookSystem-C1vB_Gc9.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-5fKZwhK_.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-7RnrEWNP.mjs";
 import { n as caching_default, t as cachingPlugin } from "../caching-_NJeDd1_.mjs";
 import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-Dxf6P_kV.mjs";
 import { n as metrics_default, t as metricsPlugin } from "../metrics-fdxI5mn_.mjs";
@@ -131,7 +131,7 @@ function createPlugin(name, definition) {
 		},
 		forResource(opts) {
 			if (!definition.forResource) return {};
-			return definition.forResource({}, opts ?? {});
+			return definition.forResource(opts ?? {});
 		}
 	};
 }

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.19.0";
+	const resolvedVersion = serviceVersion ?? "2.20.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-DccFV9R7.mjs → pluralize-BhrgwZb9.mjs}

@@ -34,7 +34,7 @@ const IRREGULARS = {
 	vertex: "vertices",
 	criterion: "criteria"
 };
-const UNCOUNTABLES = new Set([
+const UNCOUNTABLES = /* @__PURE__ */ new Set([
 	"sheep",
 	"fish",
 	"deer",
@@ -65,7 +65,7 @@ function pluralize(word) {
 	if (lower.endsWith("f") && !lower.endsWith("ff") && !lower.endsWith("roof") && !lower.endsWith("chief") && !lower.endsWith("belief")) return `${word.slice(0, -1)}ves`;
 	if (lower.endsWith("y") && !/[aeiou]y$/i.test(lower)) return `${word.slice(0, -1)}ies`;
 	if (lower.endsWith("is")) return `${word.slice(0, -2)}es`;
-	if (new Set([
+	if ((/* @__PURE__ */ new Set([
 		"cactus",
 		"stimulus",
 		"focus",
@@ -76,7 +76,7 @@ function pluralize(word) {
 		"alumnus",
 		"terminus",
 		"bacillus"
-	]).has(lower)) return `${word.slice(0, -2)}i`;
+	])).has(lower)) return `${word.slice(0, -2)}i`;
 	if (lower.endsWith("z") && !lower.endsWith("zz")) return `${word}zes`;
 	if (/(?:s|sh|ch|x|zz)$/i.test(lower)) return `${word}es`;
 	if (lower.endsWith("o") && !/[aeiou]o$/i.test(lower)) return `${word}es`;

package/dist/presets/filesUpload.d.mts

@@ -1,4 +1,4 @@
-import { rt as PresetResult } from "../index-CUTG2Cuo.mjs";
+import { rt as PresetResult } from "../index-_--GyzcO.mjs";
 import { i as RequestScope } from "../types-LNebCoJx.mjs";
 import { c as PermissionCheck } from "../fields-C7ahdGYf.mjs";
 import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Co_PQpeQ.mjs";

package/dist/presets/filesUpload.mjs

@@ -1,6 +1,6 @@
 import { i as NotFoundError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
 import { c as getOrgId, g as getUserId } from "../types-bHblZ9YN.mjs";
-import { C as requireAuth, y as allowPublic } from "../permissions-BPB1xqGf.mjs";
+import { C as requireAuth, y as allowPublic } from "../permissions-CgbOLJZG.mjs";
 import { t as multipartBody } from "../multipartBody-CHEQSZ6G.mjs";
 //#region src/presets/filesUpload.ts
 const DEFAULT_FIELD_NAME = "file";

package/dist/presets/index.d.mts

@@ -1,4 +1,4 @@
-import { bt as IControllerResponse, d as PaginationResult, qt as AnyRecord, rt as PresetResult, st as ResourceConfig, xt as IRequestContext } from "../index-CUTG2Cuo.mjs";
+import { bt as IControllerResponse, d as PaginationResult, qt as AnyRecord, rt as PresetResult, st as ResourceConfig, xt as IRequestContext } from "../index-_--GyzcO.mjs";
 import { FilesUploadPresetOptions, FilesUploadPresetPermissions, FilesUploadPresetRoutes, filesUploadPreset } from "./filesUpload.mjs";
 import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 import { SearchHandler, SearchPresetOptions, SearchRouteConfig, searchPreset } from "./search.mjs";
@@ -237,7 +237,21 @@ type IAuditedPreset = never;
  * }
  * ```
  */
-type IPresetController<TDoc = unknown, TPresets extends "softDelete" | "slugLookup" | "tree" | never = never> = TPresets extends "softDelete" ? ISoftDeleteController<TDoc> : TPresets extends "slugLookup" ? ISlugLookupController<TDoc> : TPresets extends "tree" ? ITreeController<TDoc> : unknown;
+/** Preset name → controller contract. Lookup table for {@link IPresetController}. */
+interface PresetControllerContracts<TDoc> {
+  softDelete: ISoftDeleteController<TDoc>;
+  slugLookup: ISlugLookupController<TDoc>;
+  tree: ITreeController<TDoc>;
+}
+/**
+ * Collapse a union into an intersection. The pre-2.20 implementation used a
+ * distributive conditional, so `IPresetController<T, 'softDelete' | 'tree'>`
+ * produced a UNION of contracts — which a class cannot `implements`; the
+ * documented multi-preset example didn't compile. An indexed lookup over the
+ * union followed by this fold yields the intersection the example promises.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type IPresetController<TDoc = unknown, TPresets extends keyof PresetControllerContracts<TDoc> = never> = UnionToIntersection<PresetControllerContracts<TDoc>[TPresets]>;
 //#endregion
 //#region src/presets/index.d.ts
 /**

package/dist/presets/index.mjs

@@ -1,5 +1,5 @@
 import { multiTenantPreset } from "./multiTenant.mjs";
-import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-BtyFwTO4.mjs";
+import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-DWsYQdbV.mjs";
 import { filesUploadPreset } from "./filesUpload.mjs";
 import { searchPreset } from "./search.mjs";
 export { applyPresets, auditedPreset, bulkPreset, filesUploadPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, searchPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/multiTenant.d.mts

@@ -1,4 +1,4 @@
-import { J as CrudRouteKey, rt as PresetResult } from "../index-CUTG2Cuo.mjs";
+import { J as CrudRouteKey, rt as PresetResult } from "../index-_--GyzcO.mjs";
 
 //#region src/presets/multiTenant.d.ts
 /**

package/dist/presets/multiTenant.mjs

@@ -1,4 +1,4 @@
-import "../constants-gaEeMlz-.mjs";
+import "../constants-DNre0wRg.mjs";
 import { b as isElevated, c as getOrgId, d as getScopeContext, m as getTeamId, u as getRequestScope, v as hasOrgAccess } from "../types-bHblZ9YN.mjs";
 //#region src/presets/multiTenant.ts
 /**

package/dist/presets/search.d.mts

@@ -1,4 +1,4 @@
-import { ft as RouteDefinition, gt as ControllerHandler, pt as RouteMcpConfig, rt as PresetResult } from "../index-CUTG2Cuo.mjs";
+import { ft as RouteDefinition, gt as ControllerHandler, pt as RouteMcpConfig, rt as PresetResult } from "../index-_--GyzcO.mjs";
 import { c as PermissionCheck } from "../fields-C7ahdGYf.mjs";
 
 //#region src/presets/search.d.ts

package/dist/presets/search.mjs

@@ -1,4 +1,4 @@
-import { C as requireAuth, y as allowPublic } from "../permissions-BPB1xqGf.mjs";
+import { C as requireAuth, y as allowPublic } from "../permissions-CgbOLJZG.mjs";
 //#region src/presets/search.ts
 const BUILTINS = [
 	{
@@ -84,7 +84,8 @@ function autoHandlerFor(repo, method) {
 		return fn(body.input ?? body);
 	};
 	if (method === "searchSimilar") return async (req) => {
-		return fn(req.body ?? {});
+		const body = req.body ?? {};
+		return fn(body);
 	};
 	return async (req) => {
 		const body = req.body ?? {};

package/dist/{presets-BtyFwTO4.mjs → presets-DWsYQdbV.mjs}

@@ -1,5 +1,5 @@
 import { b as isElevated, n as PUBLIC_SCOPE } from "./types-bHblZ9YN.mjs";
-import { C as requireAuth, T as requireRoles, y as allowPublic } from "./permissions-BPB1xqGf.mjs";
+import { C as requireAuth, T as requireRoles, y as allowPublic } from "./permissions-CgbOLJZG.mjs";
 import { multiTenantPreset } from "./presets/multiTenant.mjs";
 //#region src/presets/ownedByUser.ts
 /**