@classytic/arc 2.32.0 → 2.33.0

package/dist/outbox-module-D-VFq37T.d.mts

@@ -0,0 +1,368 @@
+
+import { a as EventTransport, n as DomainEvent, t as DeadLetteredEvent } from "./EventTransport-BEVP50ka.mjs";
+import { t as ArcModule } from "./types-BcTumAz_.mjs";
+import { FastifyInstance } from "fastify";
+import { MemoryOutboxStore } from "@classytic/primitives/memory-outbox";
+import { OutboxFailurePolicy, OutboxStore, OutboxWriteOptions } from "@classytic/primitives/outbox";
+import { RepositoryLike } from "@classytic/repo-core/adapter";
+//#region src/events/outbox/relay.d.ts
+/** Reason codes passed to {@link EventOutboxOptions.onError}. */
+type OutboxRelayErrorKind = "publish_failed" | "acknowledge_failed" | "fail_failed" | "ownership_mismatch" | "malformed_event";
+/**
+ * Rich per-batch outcome returned by {@link EventOutbox.relayBatch}.
+ *
+ * Useful for operational dashboards, alerting thresholds, and test assertions.
+ * The simpler {@link EventOutbox.relay} returns just the `relayed` count for
+ * backward compatibility.
+ */
+interface RelayResult {
+  /** Number of events successfully published AND acknowledged */
+  readonly relayed: number;
+  /** Number of events claimed and attempted in this batch */
+  readonly attempted: number;
+  /** Number of publish failures (transport rejected the event) */
+  readonly publishFailed: number;
+  /** Number of acknowledge failures after successful publish (at-least-once replay risk) */
+  readonly ackFailed: number;
+  /** Number of ownership mismatches (our lease expired mid-flight) */
+  readonly ownershipMismatches: number;
+  /** Number of malformed events encountered (aborts the batch) */
+  readonly malformed: number;
+  /** Number of fail() calls that themselves threw (store bugs / contention) */
+  readonly failHookErrors: number;
+  /**
+   * Number of events moved to dead-letter state this batch via the configured
+   * {@link OutboxFailurePolicy}. Zero when no policy is set or no failure
+   * tripped the `deadLetter` branch.
+   */
+  readonly deadLettered: number;
+  /** Whether `publishMany` was used (true) or per-event `publish` (false) */
+  readonly usedPublishMany: boolean;
+  /**
+   * Wall-clock ms spent claiming this batch from the store. With the
+   * portable repository adapter this is ~2 DB round trips; a persistently
+   * high value under low batch sizes points at store latency, not volume.
+   */
+  readonly claimMs?: number;
+  /** Wall-clock ms spent publishing + acknowledging the batch. */
+  readonly publishMs?: number;
+}
+/**
+ * Called by {@link EventOutbox.relay} when a non-fatal error occurs during
+ * a batch. Used for logging and metrics. Must not throw.
+ */
+type OutboxRelayErrorHandler = (info: {
+  readonly kind: OutboxRelayErrorKind;
+  readonly event?: DomainEvent;
+  readonly error: Error;
+}) => void;
+interface EventOutboxOptions {
+  /**
+   * Repository managing the outbox collection. Arc consumes it directly —
+   * no wrapper classes. Requires `create`, `getOne`, `findAll`,
+   * `deleteMany`, and `findOneAndUpdate` from `RepositoryLike` (mongokit
+   * ≥3.8 satisfies all of these). Takes precedence over `store` when both
+   * are passed.
+   *
+   * Use this for the common path where the outbox lives in your primary
+   * database. Use `store` for non-repository backends (memory / custom).
+   */
+  readonly repository?: RepositoryLike;
+  /**
+   * Non-repository outbox store. Use when your backend isn't a repository
+   * (memory for tests, Kafka, DynamoDB, custom). Ignored if `repository`
+   * is also passed.
+   */
+  readonly store?: OutboxStore;
+  /** Transport to relay events to (optional — can relay later) */
+  readonly transport?: EventTransport;
+  /** Max events per relay batch (default: 100) */
+  readonly batchSize?: number;
+  /**
+   * Unique identifier for this relay worker. Used when the store supports
+   * `claimPending`/`fail` to enforce lease ownership. Defaults to a random ID.
+   */
+  readonly consumerId?: string;
+  /**
+   * Lease duration in ms for claimed events. Only used when the store
+   * supports `claimPending`. Default: 30 seconds.
+   */
+  readonly leaseMs?: number;
+  /**
+   * Callback for non-fatal errors during relay: publish failures,
+   * ownership mismatches, ack/fail errors, malformed events. Use this for
+   * logging and metrics. Must not throw — exceptions are swallowed.
+   */
+  readonly onError?: OutboxRelayErrorHandler;
+  /**
+   * Enable {@link EventTransport.publishMany} when the transport implements it.
+   * Default: `true`. Set to `false` to force per-event `publish()` — useful
+   * for transports where strict event-order observability matters more than
+   * throughput, or to debug batch-specific issues.
+   */
+  readonly usePublishMany?: boolean;
+  /**
+   * Retry/DLQ decision policy. When set, {@link EventOutbox.relayBatch}
+   * invokes this on every failure and uses the returned options for
+   * `store.fail()`. Centralises the "after N fails, dead-letter" rule so
+   * apps don't recompute `exponentialBackoff` + escalation thresholds on
+   * every failure site.
+   *
+   * Without a policy, `fail()` is called with `{}` (immediate re-visibility
+   * on next poll) — legacy behaviour, unchanged.
+   */
+  readonly failurePolicy?: OutboxFailurePolicy;
+  /**
+   * Unit-of-Work session provider (AsyncLocalStorage integration).
+   *
+   * When set, `store()` calls this to get the active DB session and uses
+   * it as `OutboxWriteOptions.session` — **only when the caller has not
+   * already passed an explicit `options.session`**. This eliminates the
+   * boilerplate of threading the transaction handle from the controller
+   * through every service layer down to the outbox call site.
+   *
+   * Wire up with arc's `transactionContext`:
+   * ```typescript
+   * import { transactionContext } from '@classytic/arc/context';
+   *
+   * const outbox = new EventOutbox({
+   *   store: myOutboxStore,
+   *   sessionProvider: () => transactionContext.get(),
+   * });
+   *
+   * // In your service layer — session is auto-picked up:
+   * await transactionContext.run(mongooseSession, async () => {
+   *   await orders.insertOne(order, { session: mongooseSession });
+   *   await outbox.store(orderCreatedEvent); // no session arg needed
+   * });
+   * ```
+   */
+  readonly sessionProvider?: () => unknown;
+  /**
+   * W3C Trace Context provider.
+   *
+   * When set, `store()` calls this and merges the returned headers into
+   * `OutboxWriteOptions.headers` — only when `traceparent` is not already
+   * present in the caller-supplied headers. Downstream relay workers can
+   * then forward the headers to the transport, preserving the distributed
+   * trace tree across service boundaries.
+   *
+   * Wire up with arc's `getTraceHeaders`:
+   * ```typescript
+   * import { getTraceHeaders } from '@classytic/arc/context';
+   *
+   * const outbox = new EventOutbox({
+   *   store: myOutboxStore,
+   *   traceContextProvider: getTraceHeaders,
+   * });
+   * ```
+   */
+  readonly traceContextProvider?: () => Record<string, string> | undefined;
+}
+declare class EventOutbox {
+  private readonly _store;
+  private readonly _transport?;
+  private readonly _batchSize;
+  private readonly _consumerId;
+  private readonly _leaseMs;
+  private readonly _onError?;
+  private readonly _usePublishMany;
+  private readonly _sessionProvider?;
+  private readonly _traceContextProvider?;
+  private readonly _failurePolicy?;
+  /**
+   * In-process attempt counter per event id. Accurate within this relay
+   * process; resets on restart. Populated as failures occur and cleared on
+   * successful ack or dead-letter transition; additionally hard-capped at
+   * {@link MAX_TRACKED_ATTEMPTS} (oldest-write evicted first) so events
+   * resolved by another relay worker can't accumulate forever. For durable
+   * authoritative counts, apps can query the store directly inside
+   * {@link OutboxFailurePolicy}.
+   */
+  private readonly _attempts;
+  constructor(opts: EventOutboxOptions);
+  /** Unique consumer ID used for lease ownership when the store supports claims */
+  get consumerId(): string;
+  /**
+   * Store event in outbox.
+   *
+   * Validates that `event.type` and `event.meta.id` are present — throws
+   * {@link InvalidOutboxEventError} otherwise, so corrupt rows can never
+   * be persisted via this API.
+   *
+   * Pass `options.session` to participate in a host-managed DB transaction
+   * (store must support session-aware writes). Other options (`visibleAt`,
+   * `dedupeKey`, `partitionKey`, `headers`) are forwarded to stores that
+   * implement them and ignored otherwise.
+   */
+  store(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
+  private _reportError;
+  /**
+   * Relay pending events to transport and return the number of successful
+   * publish+acknowledge pairs.
+   *
+   * For richer observability (per-kind counts, publishMany detection, etc.)
+   * use {@link relayBatch} which returns a {@link RelayResult}. This method
+   * is the backward-compatible shortcut that returns just the count.
+   *
+   * @returns Number of successfully published AND acknowledged events
+   */
+  relay(): Promise<number>;
+  /**
+   * Relay a batch of pending events to the transport and return a rich
+   * {@link RelayResult} describing the outcome of each event.
+   *
+   * Behavior summary:
+   *
+   * - **Claim path**: uses {@link OutboxStore.claimPending} when the store
+   *   supports it (safe for multi-worker relay) or falls back to
+   *   {@link OutboxStore.getPending} (single-worker only).
+   *
+   * - **Publish path**: if the transport implements
+   *   {@link EventTransport.publishMany} and `usePublishMany` is not disabled,
+   *   the entire batch is sent in one call. Otherwise each event is published
+   *   individually. Either way, per-event outcomes are tracked.
+   *
+   * - **Failure path**: if the store implements `fail`, per-event failures
+   *   are reported via `store.fail(...)` and the batch continues. Without
+   *   `fail`, the batch stops on the first failure (legacy behavior).
+   *
+   * - **Malformed events**: events missing `type` or `meta.id` abort the
+   *   batch — a well-behaved store must never return them (see
+   *   {@link OutboxStore} semantics #6). The error is reported via `onError`.
+   *
+   * - **Ownership mismatches**: if `acknowledge`/`fail` throws
+   *   {@link OutboxOwnershipError} (our lease expired and another worker
+   *   claimed the event), the event is NOT counted as relayed. The other
+   *   worker will re-publish — at-least-once semantics preserved.
+   *
+   * @returns Per-kind outcome counts for the batch
+   */
+  relayBatch(): Promise<RelayResult>;
+  /**
+   * Fetch current dead-lettered events as typed {@link DeadLetteredEvent}
+   * envelopes. Delegates to {@link OutboxStore.getDeadLettered} — returns
+   * `[]` when the store doesn't implement it.
+   *
+   * Pairs with {@link OutboxFailurePolicy}: apps set a policy that routes to
+   * `deadLetter: true` after N attempts, then read back with this to alert,
+   * replay, or archive.
+   */
+  getDeadLettered(limit?: number): Promise<DeadLetteredEvent[]>;
+  /**
+   * Purge old **delivered** events from the outbox store.
+   * Delegates to `store.purge()` if implemented; no-op otherwise.
+   * @param olderThanMs - Remove events delivered more than this many ms ago (default: 7 days)
+   * @returns Number of purged events, or 0 if store doesn't support purge
+   */
+  purge(olderThanMs?: number): Promise<number>;
+}
+//#endregion
+//#region src/events/outbox-module.d.ts
+interface OutboxModuleOptions {
+  /**
+   * The durable store. Supply it directly, or as a factory when it needs the booted app
+   * (a mongoose connection decorated by an earlier plugin, for instance).
+   */
+  store: OutboxStore | ((fastify: FastifyInstance) => OutboxStore);
+  /**
+   * Where relayed events are published. Omit to use the app's OWN transport — the ordinary case;
+   * pass one only when the outbox must publish somewhere else.
+   *
+   * The default resolves the RAW `EventTransport` the events plugin registered, never the
+   * `fastify.events` facade. The facade takes `(type, payload, meta?)` and swallows publish
+   * errors under `failOpen` — both fatal here: the first makes every relayed event fail its
+   * non-empty-string type guard, the second makes a failure read as success and acknowledges
+   * the row. See `ARC_EVENT_TRANSPORT`.
+   */
+  transport?: EventTransport | ((fastify: FastifyInstance) => EventTransport);
+  /** Module name, and therefore the `dependsOn` key. Default `'outbox'`. */
+  name?: string;
+  /** Relay interval in ms. Default 5000. */
+  relayEveryMs?: number;
+  /**
+   * Rows per relay tick. Left to the store's own default when omitted — a batch size is a
+   * throughput tuning decision, not something this module should invent.
+   */
+  batchSize?: number;
+  /** Lease duration for a claimed batch, in ms. */
+  leaseMs?: number;
+  /**
+   * Consumer id recorded on the lease. Default:
+   * `<name>:<hostname>:<pid>:<random>` — UNIQUE PER RELAY INSTANCE.
+   *
+   * The lease is what stops two relays publishing the same event, and it can
+   * only do that if they are distinguishable. The pre-2.34 default was the
+   * shared literal `'arc-outbox-relay'`, which QUIETLY violated the rule the
+   * doc stated: every process — and every co-resident module — was the same
+   * logical owner, so a lease that expired and was re-claimed elsewhere looked
+   * to the store's ownership check like the original owner never lost it. The
+   * stale-owner protection was pinned open.
+   *
+   * Set this explicitly only to make lease ownership legible in ops tooling
+   * (e.g. `billing-relay:pod-7`); whatever you set MUST stay distinct per
+   * relay, not merely per deployment.
+   */
+  consumerId?: string;
+  /**
+   * Called for every non-fatal relay problem — publish failures, ownership mismatches,
+   * acknowledge failures.
+   *
+   * **Wire this.** Silence here is the failure mode that matters: the relay keeps ticking, rows
+   * keep failing, and the only symptom is revenue that never posted.
+   */
+  onError?: OutboxRelayErrorHandler;
+  /**
+   * Retry / dead-letter policy for a failed publish — `({ attempts }) => { retryAt } |
+   * { deadLetter: true }`.
+   *
+   * Omitting it takes `EventOutbox`'s default. Exposed because a real host had one and losing it
+   * on adoption would be a silent downgrade: without a policy a permanently-failing row either
+   * retries forever or dead-letters on the first blip, and both are wrong for money. A typical
+   * shape is exponential backoff up to N attempts, then dead-letter.
+   */
+  failurePolicy?: OutboxFailurePolicy;
+  /**
+   * Run one relay pass at boot. Default `true` — a process that restarts with a backlog should
+   * drain it immediately rather than waiting a full interval, because that backlog is precisely
+   * the events the previous process failed to publish.
+   */
+  runOnStart?: boolean;
+}
+/** What the module exports at `fastify.arc.modules.<name>`. */
+interface OutboxModuleExports {
+  /** The store, for consumers that write events transactionally. */
+  store: OutboxStore;
+  /** The relay, for a host that wants to drain on demand (tests, admin actions). */
+  relay: EventOutbox;
+}
+/**
+ * Compose the outbox as a module.
+ *
+ * ```ts
+ * // host
+ * const model = createOutboxModel(connection, { visibleAtField: 'nextVisibleAt' });
+ * createApp({ modules: [
+ *   createOutboxModule({
+ *     store: repositoryAsOutboxStore(new Repository(model), { visibleAtField: 'nextVisibleAt' }),
+ *     onError: (err, ctx) => app.log.error({ err, ...ctx }, 'outbox relay'),
+ *   }),
+ *   …
+ * ]});
+ *
+ * // consumer module
+ * defineModule({
+ *   name: 'order',
+ *   dependsOn: ['outbox'],
+ *   bootstrap: (f) => createOrder({
+ *     outbox: getModuleExports<OutboxModuleExports>(f, 'outbox').store,
+ *   }),
+ * });
+ * ```
+ *
+ * `dependsOn` is doing real work there: it both orders the bootstraps and makes a missing outbox a
+ * boot error naming the module that needed it.
+ */
+declare function createOutboxModule(options: OutboxModuleOptions): ArcModule<OutboxModuleExports>;
+//#endregion
+export { EventOutbox as a, OutboxRelayErrorKind as c, MemoryOutboxStore as i, RelayResult as l, OutboxModuleOptions as n, EventOutboxOptions as o, createOutboxModule as r, OutboxRelayErrorHandler as s, OutboxModuleExports as t };

package/dist/permissions/index.d.mts

@@ -1,5 +1,5 @@
 
-import { a as UserBase, c as normalizeRoles, i as PermissionContext, n as DataPolicy, r as PermissionCheck, s as getUserRoles, t as AuthorizationDecision } from "../types-B7XeLEgK.mjs";
+import { c as DataPolicy, d as UserBase, l as PermissionCheck, m as normalizeRoles, p as getUserRoles, s as AuthorizationDecision, u as PermissionContext } from "../base-Csjc2oF-.mjs";
 import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-I_EeRWND.mjs";
-import { $ as requireAuth, A as RequireGrantOptions, B as ConnectEventsOptions, C as requireServiceScope, D as GRANT_MODES, E as createRoleHierarchy, F as PermissionRequirement, G as createOrgPermissions, H as DynamicPermissionMatrixConfig, I as collectPublicSurface, J as allowPublic, K as allOf, L as describePermission, M as requireGrant, N as conjoinPolicyFilters, O as GrantMode, P as AccessExplanation, Q as not, R as describePermissionMap, S as requireScopeContext, T as RoleHierarchy, U as PermissionEventBus, V as DynamicPermissionMatrix, W as createDynamicPermissionMatrix, X as deny, Y as anyOf, Z as denyAll, _ as publicReadAdminWrite, a as PermissionMatrixRegistry, at as scopeOf, b as requireOrgMembership, c as introspectModule, ct as evaluatePermissionDecision, d as authenticated, dt as RequireMandateOptions, et as requireOwnership, f as fullPublic, ft as requireAgentScope, g as publicRead, h as presets_d_exports, i as PermissionMatrixOptions, it as when, j as modeSatisfies, k as GrantResolution, l as introspectRegistry, lt as normalizeToDecision, m as permissionMatrix, mt as requireMandate, n as PermissionEntryType, nt as requireRoles, o as buildPermissionMatrix, ot as PermissionCheckReturn, p as ownerWithAdminBypass, pt as requireDPoP, q as allow, r as PermissionMatrix, rt as roles, s as introspectCheck, st as applyAuthorizationDecision, t as PermissionEntry, tt as requirePlatformRole, u as adminOnly, ut as RequireAgentScopeOptions, v as readOnly, w as requireTeamMembership, x as requireOrgRole, y as requireOrgInScope, z as explainAccess } from "../index-zq6VrjaB.mjs";
+import { $ as requireAuth, A as RequireGrantOptions, B as ConnectEventsOptions, C as requireServiceScope, D as GRANT_MODES, E as createRoleHierarchy, F as PermissionRequirement, G as createOrgPermissions, H as DynamicPermissionMatrixConfig, I as collectPublicSurface, J as allowPublic, K as allOf, L as describePermission, M as requireGrant, N as conjoinPolicyFilters, O as GrantMode, P as AccessExplanation, Q as not, R as describePermissionMap, S as requireScopeContext, T as RoleHierarchy, U as PermissionEventBus, V as DynamicPermissionMatrix, W as createDynamicPermissionMatrix, X as deny, Y as anyOf, Z as denyAll, _ as publicReadAdminWrite, a as PermissionMatrixRegistry, at as scopeOf, b as requireOrgMembership, c as introspectModule, ct as evaluatePermissionDecision, d as authenticated, dt as RequireMandateOptions, et as requireOwnership, f as fullPublic, ft as requireAgentScope, g as publicRead, h as presets_d_exports, i as PermissionMatrixOptions, it as when, j as modeSatisfies, k as GrantResolution, l as introspectRegistry, lt as normalizeToDecision, m as permissionMatrix, mt as requireMandate, n as PermissionEntryType, nt as requireRoles, o as buildPermissionMatrix, ot as PermissionCheckReturn, p as ownerWithAdminBypass, pt as requireDPoP, q as allow, r as PermissionMatrix, rt as roles, s as introspectCheck, st as applyAuthorizationDecision, t as PermissionEntry, tt as requirePlatformRole, u as adminOnly, ut as RequireAgentScopeOptions, v as readOnly, w as requireTeamMembership, x as requireOrgRole, y as requireOrgInScope, z as explainAccess } from "../index-B-DvUzsr.mjs";
 export { type AccessExplanation, type AuthorizationDecision, type ConnectEventsOptions, type DataPolicy, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, GRANT_MODES, type GrantMode, type GrantResolution, type PermissionCheck, type PermissionCheckReturn, type PermissionContext, type PermissionEntry, type PermissionEntryType, type PermissionEventBus, type PermissionMatrix, type PermissionMatrixOptions, type PermissionMatrixRegistry, type PermissionRequirement, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, buildPermissionMatrix, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, introspectCheck, introspectModule, introspectRegistry, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requirePlatformRole, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };

package/dist/permissions/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { a as conjoinPolicyFilters, i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-__T3EJDA.mjs";
-import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-BNsOXzOd.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-DEi65pGj.mjs";
-import { A as requireAgentScope, B as requireAuth, C as createOrgPermissions, D as requireScopeContext, E as requireOrgRole, F as allowPublic, G as when, H as requirePlatformRole, I as anyOf, K as scopeOf, L as deny, M as requireMandate, N as allOf, O as requireServiceScope, P as allow, R as denyAll, S as createDynamicPermissionMatrix, T as requireOrgMembership, U as requireRoles, V as requireOwnership, W as roles, _ as requireGrant, a as adminOnly, b as describePermissionMap, c as ownerWithAdminBypass, d as publicRead, f as publicReadAdminWrite, g as modeSatisfies, h as GRANT_MODES, i as introspectRegistry, j as requireDPoP, k as requireTeamMembership, l as permissionMatrix, m as createRoleHierarchy, n as introspectCheck, o as authenticated, p as readOnly, r as introspectModule, s as fullPublic, t as buildPermissionMatrix, u as presets_exports, v as collectPublicSurface, w as requireOrgInScope, x as explainAccess, y as describePermission, z as not } from "../permissions-Dl_m0NCe.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { a as conjoinPolicyFilters, i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-B3mP_QTy.mjs";
+import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-CWF5pbZD.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-CojeUkS4.mjs";
+import { A as requireAgentScope, B as requireAuth, C as createOrgPermissions, D as requireScopeContext, E as requireOrgRole, F as allowPublic, G as when, H as requirePlatformRole, I as anyOf, K as scopeOf, L as deny, M as requireMandate, N as allOf, O as requireServiceScope, P as allow, R as denyAll, S as createDynamicPermissionMatrix, T as requireOrgMembership, U as requireRoles, V as requireOwnership, W as roles, _ as requireGrant, a as adminOnly, b as describePermissionMap, c as ownerWithAdminBypass, d as publicRead, f as publicReadAdminWrite, g as modeSatisfies, h as GRANT_MODES, i as introspectRegistry, j as requireDPoP, k as requireTeamMembership, l as permissionMatrix, m as createRoleHierarchy, n as introspectCheck, o as authenticated, p as readOnly, r as introspectModule, s as fullPublic, t as buildPermissionMatrix, u as presets_exports, v as collectPublicSurface, w as requireOrgInScope, x as explainAccess, y as describePermission, z as not } from "../permissions-BAfwgBxc.mjs";
 export { GRANT_MODES, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, buildPermissionMatrix, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, introspectCheck, introspectModule, introspectRegistry, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requirePlatformRole, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };

package/dist/{permissions-Dl_m0NCe.mjs → permissions-BAfwgBxc.mjs}

@@ -1,10 +1,10 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-BhflRrBs.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { a as conjoinPolicyFilters, i as normalizeToDecision } from "./authorizationDecision-__T3EJDA.mjs";
-import { n as getUserRoles } from "./userHelpers-BNsOXzOd.mjs";
-import { C as isService, S as isOrgInScope, a as getDPoPJkt, b as isElevated, d as getScopeContext, f as getScopeContextMap, g as getUserId, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-DXYX7dIR.mjs";
-import { t as MemoryCacheStore } from "./memory-DsuWnj4T.mjs";
+import { a as conjoinPolicyFilters, i as normalizeToDecision } from "./authorizationDecision-B3mP_QTy.mjs";
+import { n as getUserRoles } from "./userHelpers-CWF5pbZD.mjs";
+import { C as isService, S as isOrgInScope, a as getDPoPJkt, b as isElevated, d as getScopeContext, f as getScopeContextMap, g as getUserId, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-CoqIRrkY.mjs";
+import { t as MemoryCacheStore } from "./memory-qYSB7rMQ.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/permissions/context.ts
 /**
@@ -1614,6 +1614,25 @@ function introspectRegistry(registry) {
 		for (const [action, check] of Object.entries(entry.permissions ?? {})) if (typeof check === "function") map[action] = introspectCheck(check);
 		for (const a of entry.actions ?? []) if (typeof a.permissions === "function") map[`action:${a.name}`] = introspectCheck(a.permissions);
 		for (const agg of entry.aggregations ?? []) if (typeof agg.permissions === "function") map[`agg:${agg.name}`] = introspectCheck(agg.permissions);
+		/**
+		* Custom routes that OPTED IN via `capability`.
+		*
+		* A route has no inherent name — only a method and a path — so it cannot be
+		* keyed automatically, and a path is not an identity. Without this, a
+		* resource whose gates live entirely on `routes[]` published nothing, was
+		* absent from the matrix, and every `can()` against it answered `false`:
+		* a UI gating on it hid the feature from everyone, admins included, and that
+		* reads as broken permissions rather than an unpublished key.
+		*
+		* The key is BARE, alongside `list`/`get`/`create`, so a consumer never has
+		* to know whether a verb is a route, an action or a CRUD slot.
+		*/
+		for (const route of entry.customRoutes ?? []) {
+			const key = route.capability;
+			if (key === void 0 || typeof route.permissions !== "function") continue;
+			if (map[key] !== void 0) throw new Error(`[arc] permission-matrix collision on resource "${entry.name}": route ${route.method} ${route.path} declares capability "${key}", which is already published by a CRUD slot, action or another route. Rename the route's \`capability\`.`);
+			map[key] = introspectCheck(route.permissions);
+		}
 		if (Object.keys(map).length > 0) modules[entry.name] = map;
 	}
 	return modules;

package/dist/{pipe-ELHCP3zj.mjs → pipe-BzzoEhHj.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { r as ForbiddenError } from "./errors-Bh1KK5ps.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { r as ForbiddenError } from "./errors-Cd_yy7aW.mjs";
 //#region src/pipeline/pipe.ts
 /**
 * Compose pipeline steps into an ordered array.

package/dist/pipeline/index.d.mts

@@ -1,5 +1,5 @@
 
-import { Ct as PipelineStep, Rt as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-CpzxqePp.mjs";
+import { Ct as PipelineStep, Fn as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-BcR2bFZQ.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;

package/dist/pipeline/index.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { n as pipe, t as executePipeline } from "../pipe-ELHCP3zj.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { n as pipe, t as executePipeline } from "../pipe-BzzoEhHj.mjs";
 //#region src/pipeline/guard.ts
 /**
 * Create a named guard.

package/dist/{pipeline-CPA-jx0M.mjs → pipeline-q69DZzgG.mjs}

@@ -1,9 +1,9 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { n as getUserRoles } from "./userHelpers-BNsOXzOd.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-DXYX7dIR.mjs";
-import { i as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-DEi65pGj.mjs";
-import { t as executePipeline } from "./pipe-ELHCP3zj.mjs";
-import { t as buildRequestScopeProjection } from "./projection-CjHhM5W1.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "./userHelpers-CWF5pbZD.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CoqIRrkY.mjs";
+import { i as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-CojeUkS4.mjs";
+import { t as executePipeline } from "./pipe-BzzoEhHj.mjs";
+import { t as buildRequestScopeProjection } from "./projection-BKM0Ui-s.mjs";
 import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
 //#region src/core/fastifyAdapter.ts
 /** Type guard for Mongoose-like documents with toObject() */

package/dist/plugins/index.d.mts

@@ -1,10 +1,10 @@
 
-import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-CpzxqePp.mjs";
-import { l as AnyRecord } from "../types-B7XeLEgK.mjs";
-import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-CpYUJmPA.mjs";
-import { _ as HealthCheck, b as healthPlugin, f as ScheduleDefinition, g as schedulesPlugin, h as _default$7, m as SchedulesPluginOptions, p as ScheduleStats, v as HealthOptions, y as _default$3 } from "../types-CT5vu6M0.mjs";
-import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-BppG5bMT.mjs";
-import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$5, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$8, n as _default$9, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-D_rhHfZm.mjs";
+import { t as AnyRecord } from "../base-Csjc2oF-.mjs";
+import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-BcR2bFZQ.mjs";
+import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-DI5AN2b5.mjs";
+import { _ as HealthCheck, b as healthPlugin, f as ScheduleDefinition, g as schedulesPlugin, h as _default$7, m as SchedulesPluginOptions, p as ScheduleStats, v as HealthOptions, y as _default$3 } from "../types-BcTumAz_.mjs";
+import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-DVsTAy6X.mjs";
+import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$5, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$8, n as _default$9, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-DEs-_hFi.mjs";
 import { t as TracingOptions } from "../tracing-Dro5eH6j.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";

package/dist/plugins/index.mjs

@@ -1,19 +1,19 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { p as MUTATION_OPERATIONS } from "../constants-J99LGTJI.mjs";
-import { c as getOrgId } from "../types-DXYX7dIR.mjs";
-import { n as requestContext } from "../requestContext-B6vQF-sy.mjs";
-import { t as hasEvents } from "../typeGuards-B_5-hKjJ.mjs";
-import { t as HookSystem } from "../HookSystem-vimw5D7Z.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-BVr7PgA0.mjs";
-import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-5XnTa2uo.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-DFJqHyFs.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-B2AZUJUj.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-DdQL8syd.mjs";
-import { n as realtime_default, t as realtimePlugin } from "../realtime-DVvVZZFz.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-DS-P0b32.mjs";
-import { n as schedules_default, t as schedulesPlugin } from "../schedules-C2Q3uv2d.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-B9P4Y-UI.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-CKv2jz_U.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS } from "../constants-BxCoxmiN.mjs";
+import { c as getOrgId } from "../types-CoqIRrkY.mjs";
+import { n as requestContext } from "../requestContext-uYE35JxI.mjs";
+import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
+import { t as HookSystem } from "../HookSystem-DqXkMXkB.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-DoALUlOO.mjs";
+import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-CasG2A28.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-BcGmvnHh.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-C7xBqHsI.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-D7uchLjN.mjs";
+import { n as realtime_default, t as realtimePlugin } from "../realtime-CTkv3O59.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-BSBVCwL3.mjs";
+import { n as schedules_default, t as schedulesPlugin } from "../schedules-CAcZgia0.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-Cf0jUHsh.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-rZbyLVD-.mjs";
 import fp from "fastify-plugin";
 //#region src/core/arcCorePlugin.ts
 const arcCorePlugin = async (fastify, opts = {}) => {

package/dist/plugins/response-cache.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { t as hasEvents } from "../typeGuards-B_5-hKjJ.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 import { createRequire } from "node:module";
 import fp from "fastify-plugin";
 //#region src/plugins/tracing.ts
@@ -59,7 +59,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.32.0";
+	const resolvedVersion = serviceVersion ?? "2.34.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-C2ZkKbsn.mjs → pluralize-B7xf8qZF.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/utils/pluralize.ts
 /**
 * Lightweight English pluralization for the Arc CLI.

package/dist/{preloadResources-CDs87fTw.mjs → preloadResources-BkyqeTDz.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/factory/preloadResources.ts
 /**
 * Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.

package/dist/{preloadResources-T1hmlTEZ.d.mts → preloadResources-g07ldtzh.d.mts}

@@ -1,15 +1,15 @@
 
-import { Gt as Authenticator } from "./index-CpzxqePp.mjs";
+import { It as Authenticator } from "./index-BcR2bFZQ.mjs";
 import { r as CacheStore } from "./interface-BOk3YnTz.mjs";
 import { n as ElevationOptions } from "./elevation-BXCfVcNG.mjs";
-import { a as EventTransport } from "./EventTransport-2uVV34WU.mjs";
+import { a as EventTransport } from "./EventTransport-BEVP50ka.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-BzqxconG.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-CpYUJmPA.mjs";
-import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-CT5vu6M0.mjs";
-import "./index-ZWhLTp_s.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-GF5nnBIq.mjs";
-import { g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-D_rhHfZm.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-DI5AN2b5.mjs";
+import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-BcTumAz_.mjs";
+import "./index-C5NnMEKF.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-DSNEZWfV.mjs";
+import { g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-DEs-_hFi.mjs";
 import { r as IdempotencyStore } from "./interface-DEWNOMza.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 //#region src/factory/types/assets.d.ts
@@ -463,6 +463,29 @@ interface CreateAppOptions {
    *   would be instance-local.
    */
   runtime?: "memory" | "distributed";
+  /**
+   * Deployment ROLE of this process (topology plan, Phase 2). Decides which
+   * async machinery mounts; default `'all'` is the single-process case and
+   * changes nothing.
+   *
+   * - `'api'` / `'worker'` — no module schedule arms run here (the outbox
+   *   relay arm included); a worker fleet or scheduler deployment owns them.
+   *   Register `jobsPlugin({ mode })` to match ('api' → 'producer').
+   * - `'relay'` — ONLY `kind: 'relay'` schedule arms run (the outbox
+   *   relays); declaring HTTP `resources` is boot-fatal.
+   * - `'scheduler'` — every schedule arm runs; HTTP resources boot-fatal.
+   * - `'all'` — everything (default).
+   *
+   * A skipped arm is logged by name at boot so a misdeployed process is
+   * legible from its first lines.
+   *
+   * `createWorker` is the paved road for headless processes and forwards
+   * this option untouched — one axis, not two mechanisms. Its default stays
+   * `'all'` (its 2.23 contract: the headless process runs everything
+   * non-HTTP); pass `role: 'worker'` there when a dedicated scheduler/relay
+   * deployment owns the arms.
+   */
+  role?: "api" | "worker" | "relay" | "scheduler" | "all";
   /**
    * Store and transport instances for runtime profile validation.
    * When `runtime` is `'distributed'`, Arc validates that these are