@classytic/arc 2.19.0 → 2.21.0

package/dist/module-WeuU5jfd.d.mts

@@ -0,0 +1,429 @@
+import { n as ErrorMapper } from "./errorHandler-B0e-bq-O.mjs";
+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[];
+  /**
+   * Path-level gate, called for every discovered file BEFORE it is imported.
+   * Return `false` to skip the file entirely — its module never evaluates,
+   * so top-level side effects (engine construction, model registration) of
+   * gated-off features never fire. That's the difference from
+   * `include`/`exclude`, which match resource NAMES after import.
+   *
+   * The feature-flag → resource-dir manifest every tiered SaaS host carries
+   * becomes one callback:
+   *
+   * ```ts
+   * await loadResources(import.meta.url, {
+   *   filter: (path) => {
+   *     if (path.includes(`${sep}loyalty${sep}`)) return isFeatureEnabled('loyalty');
+   *     if (path.includes(`${sep}pos${sep}`)) return isFeatureEnabled('pos');
+   *     return true;
+   *   },
+   * });
+   * ```
+   *
+   * Receives the ABSOLUTE file path. Gating everything is legitimate — the
+   * result is an empty array (interacts with `strictResourceDir` like any
+   * other empty discovery).
+   */
+  filter?: (absolutePath: string) => boolean;
+  /**
+   * 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 error mappers this module ships (see `defineErrorMapper`). Merged
+   * into the app's error handler at boot, AFTER any host-declared mappers —
+   * host config keeps priority; module mappers follow in composition order.
+   *
+   * Closes the "composition root must know every domain's error classes"
+   * coupling: before this slot, adding `@classytic/arc-shipping` meant
+   * remembering to also register its `ShippingError` mapper in the host's
+   * `errorHandler.errorMappers` — forget it and the domain error crossed the
+   * wire as an opaque 500. Now the module carries its own mapper:
+   *
+   * ```ts
+   * defineModule({
+   *   name: 'shipping',
+   *   errorMappers: [shippingErrorMapper],
+   *   ...
+   * })
+   * ```
+   */
+  readonly errorMappers?: readonly ErrorMapper[];
+  /**
+   * 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-Kyod_di6.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-ze70xXJi.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-BWMDW-dL.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";
-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 };
+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-BGqrAa_u.mjs";
+import { A as requireOwnership, B as requireMandate, C as createOrgPermissions, D as denyAll, E as anyOf, F as normalizePermissionResult, I as RequireAgentScopeOptions, L as RequireMandateOptions, M as roles, N as when, O as not, P as applyPermissionResult, R as requireAgentScope, S as createDynamicPermissionMatrix, T as allowPublic, _ as createRoleHierarchy, a as permissionMatrix, b as DynamicPermissionMatrixConfig, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as requireRoles, k as requireAuth, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as ConnectEventsOptions, w as allOf, x as PermissionEventBus, y as DynamicPermissionMatrix, z as requireDPoP } from "../index-B5PoNbfu.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, permissionMatrix, 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 requireDPoP, C as not, D as roles, E as requireRoles, F as applyFieldReadPermissions, I as applyFieldWritePermissions, L as fields, M as applyPermissionResult, O as when, P as normalizePermissionResult, R as resolveEffectiveRoles, S as denyAll, T as requireOwnership, _ as requireServiceScope, a as permissionMatrix, b as allowPublic, c as publicReadAdminWrite, d as createDynamicPermissionMatrix, f as createOrgPermissions, g as requireScopeContext, h as requireOrgRole, i as ownerWithAdminBypass, j as requireMandate, k as requireAgentScope, l as readOnly, m as requireOrgMembership, n as authenticated, o as presets_exports, p as requireOrgInScope, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireTeamMembership, w as requireAuth, x as anyOf, y as allOf } from "../permissions-BJMuKMl7.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 };
+export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, 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-BJMuKMl7.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
@@ -1382,6 +1382,7 @@ var presets_exports = /* @__PURE__ */ __exportAll({
 	authenticated: () => authenticated,
 	fullPublic: () => fullPublic,
 	ownerWithAdminBypass: () => ownerWithAdminBypass,
+	permissionMatrix: () => permissionMatrix,
 	publicRead: () => publicRead,
 	publicReadAdminWrite: () => publicReadAdminWrite,
 	readOnly: () => readOnly
@@ -1450,6 +1451,37 @@ function adminOnly(roles = ["admin"], overrides) {
 	}, overrides);
 }
 /**
+* Arbitrary-gate CRUD matrix — the generalization every host and arc-*
+* module hand-rolls as `{ list: view, get: view, create: manage, ... }`.
+*
+* Unlike the fixed presets above, the gates are caller-supplied
+* `PermissionCheck`s, so ANY combinator plugs in — org roles, ownership,
+* `anyOf(...)`, service scopes, custom async checks. `delete` defaults to
+* the `write` gate.
+*
+* @example
+* ```typescript
+* // Two-gate (view/manage) — the arc-* module convention:
+* permissionMatrix({ read: requireAuth(), write: requireOrgRole('manager') })
+*
+* // Three-gate with a stricter delete:
+* permissionMatrix({
+*   read: allowPublic(),
+*   write: requireOrgRole('manager'),
+*   delete: requireOrgRole('owner'),
+* })
+* ```
+*/
+function permissionMatrix(gates, overrides) {
+	return withOverrides({
+		list: gates.read,
+		get: gates.read,
+		create: gates.write,
+		update: gates.write,
+		delete: gates.delete ?? gates.write
+	}, overrides);
+}
+/**
 * Owner-scoped with admin bypass.
 * list = auth (scoped to owner), get = auth, create = auth,
 * update + delete = ownership check with admin bypass.
@@ -1482,12 +1514,20 @@ 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
-export { requireMandate as A, requireAuth as C, when as D, roles as E, applyFieldWritePermissions as F, fields as I, resolveEffectiveRoles as L, evaluateAndApplyPermission as M, normalizePermissionResult as N, requireAgentScope as O, applyFieldReadPermissions as P, not as S, requireRoles as T, requireTeamMembership as _, presets_exports as a, anyOf as b, readOnly as c, createOrgPermissions as d, requireOrgInScope as f, requireServiceScope as g, requireScopeContext as h, ownerWithAdminBypass as i, applyPermissionResult as j, requireDPoP as k, createRoleHierarchy as l, requireOrgRole as m, authenticated as n, publicRead as o, requireOrgMembership as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, createDynamicPermissionMatrix as u, allOf as v, requireOwnership as w, denyAll as x, allowPublic as y };
+export { requireDPoP as A, not as C, roles as D, requireRoles as E, applyFieldReadPermissions as F, applyFieldWritePermissions as I, fields as L, applyPermissionResult as M, evaluateAndApplyPermission as N, when as O, normalizePermissionResult as P, resolveEffectiveRoles as R, denyAll as S, requireOwnership as T, requireServiceScope as _, permissionMatrix as a, allowPublic as b, publicReadAdminWrite as c, createDynamicPermissionMatrix as d, createOrgPermissions as f, requireScopeContext as g, requireOrgRole as h, ownerWithAdminBypass as i, requireMandate as j, requireAgentScope as k, readOnly as l, requireOrgMembership as m, authenticated as n, presets_exports as o, requireOrgInScope as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, requireTeamMembership as v, requireAuth as w, anyOf as x, allOf as y };

package/dist/pipeline/index.d.mts

@@ -1,5 +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-Dtrj6XZk.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;