@classytic/arc 2.31.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 evaluatePermissionDecision, A as explainAccess, B as anyOf, C as requireGrant, D as collectPublicSurface, E as PermissionRequirement, F as createDynamicPermissionMatrix, G as requireOwnership, H as denyAll, I as createOrgPermissions, J as roles, K as requirePlatformRole, L as allOf, M as DynamicPermissionMatrix, N as DynamicPermissionMatrixConfig, O as describePermission, P as PermissionEventBus, Q as applyAuthorizationDecision, R as allow, S as modeSatisfies, T as AccessExplanation, U as not, V as deny, W as requireAuth, X as scopeOf, Y as when, Z as PermissionCheckReturn, _ as createRoleHierarchy, a as permissionMatrix, at as requireMandate, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, et as normalizeToDecision, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, it as requireDPoP, j as ConnectEventsOptions, k as describePermissionMap, l as readOnly, m as requireServiceScope, n as authenticated, nt as RequireMandateOptions, o as presets_d_exports, p as requireScopeContext, q as requireRoles, r as fullPublic, rt as requireAgentScope, s as publicRead, t as adminOnly, tt as RequireAgentScopeOptions, u as requireOrgInScope, v as GRANT_MODES, w as conjoinPolicyFilters, x as RequireGrantOptions, y as GrantMode, z as allowPublic } from "../index-CEJNZFtX.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 PermissionEventBus, type PermissionRequirement, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, 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 };
+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.31.0 | MIT | https://classytic.com */
-import { a as conjoinPolicyFilters, i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-ChvUQGG1.mjs";
-import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-ChYJ6CdK.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-CB5Cuzk9.mjs";
-import { A as allow, B as roles, C as requireScopeContext, D as requireDPoP, E as requireAgentScope, F as not, H as scopeOf, I as requireAuth, L as requireOwnership, M as anyOf, N as deny, O as requireMandate, P as denyAll, R as requirePlatformRole, S as requireOrgRole, T as requireTeamMembership, V as when, _ as explainAccess, a as permissionMatrix, b as requireOrgInScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as describePermissionMap, h as describePermission, i as ownerWithAdminBypass, j as allowPublic, k as allOf, l as readOnly, m as collectPublicSurface, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as createDynamicPermissionMatrix, w as requireServiceScope, x as requireOrgMembership, y as createOrgPermissions, z as requireRoles } from "../permissions-L--QDAir.mjs";
-export { GRANT_MODES, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, 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 };
+/*! @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-L--QDAir.mjs → permissions-BAfwgBxc.mjs}

@@ -1,10 +1,10 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.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-ChvUQGG1.mjs";
-import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.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-Cys0ko9Z.mjs";
-import { t as MemoryCacheStore } from "./memory-DR6wpa9F.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
 /**
@@ -578,7 +578,8 @@ function requireAgentScope(opts) {
 */
 function requireOrgMembership() {
 	const check = (ctx) => {
-		if (hasOrgAccess(scopeOf(ctx))) return true;
+		const scope = scopeOf(ctx);
+		if (hasOrgAccess(scope)) return true;
 		if (!ctx.user) return deny("Authentication required");
 		return deny("Organization membership required");
 	};
@@ -1545,4 +1546,115 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { allow as A, roles as B, requireScopeContext as C, requireDPoP as D, requireAgentScope as E, not as F, scopeOf as H, requireAuth as I, requireOwnership as L, anyOf as M, deny as N, requireMandate as O, denyAll as P, requirePlatformRole as R, requireOrgRole as S, requireTeamMembership as T, when as V, explainAccess as _, permissionMatrix as a, requireOrgInScope as b, publicReadAdminWrite as c, GRANT_MODES as d, modeSatisfies as f, describePermissionMap as g, describePermission as h, ownerWithAdminBypass as i, allowPublic as j, allOf as k, readOnly as l, collectPublicSurface as m, authenticated as n, presets_exports as o, requireGrant as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, createDynamicPermissionMatrix as v, requireServiceScope as w, requireOrgMembership as x, createOrgPermissions as y, requireRoles as z };
+//#region src/permissions/matrix.ts
+/**
+* Permission MATRIX — what the caller may do, answered from the live registry.
+*
+* A permission-gated frontend has to decide which screens and buttons to render
+* before it issues a request. Without a server answer it keeps a hand-written
+* copy of the gates, and that copy drifts the moment a resource changes one —
+* silently, and in the dangerous direction: the UI offers an action the server
+* will refuse, or hides one the user is entitled to.
+*
+* This builds the answer from what arc ACTUALLY enforces. Every registered
+* resource contributes its CRUD gates, its state-transition `action:<verb>`
+* gates and its `agg:<name>` gates, introspected through `describePermission`.
+* A resource that exists therefore gates its own screen with no one adding it
+* anywhere — including resources unique to one deployment.
+*
+* ## Why it lives in arc
+*
+* Every input is arc's: `describePermission`, the resource registry, the shapes
+* of `actions` and `aggregations`. Nothing here knows what a domain is. Built
+* in a host, it is re-derived per deployment — and the known gap below is a
+* gap in arc's own introspection, which a host cannot close but arc can.
+*
+* ## Known gap
+*
+* `anyOf(a, b)` composes checks into a bare function with no aggregated meta,
+* so `anyOf(platformAdminOnly(), requireOrgRole(…))` introspects as
+* `authenticated` with no roles. Consumers must read `authenticated` as "the
+* server decides" rather than "any logged-in user", and fall back to an
+* explicit gate for those. Fixing it means teaching the combinators to
+* aggregate meta — an arc change, tracked here because this is where it shows.
+*/
+/** Re-shape arc's typed requirement into the wire entry. */
+function introspectCheck(check) {
+	const req = describePermission(check);
+	if (req.kind === "public") return {
+		type: "public",
+		roles: []
+	};
+	if (req.kind === "roles") return {
+		type: "roles",
+		roles: [...req.roles]
+	};
+	if (req.kind === "scoped") return {
+		type: "scoped",
+		roles: req.roles ? [...req.roles] : [],
+		scope: { ...req.scope }
+	};
+	return {
+		type: "authenticated",
+		roles: []
+	};
+}
+/** Introspect a permission module, flattening nested groups to `a.b`. */
+function introspectModule(mod) {
+	const result = {};
+	for (const [action, check] of Object.entries(mod)) if (typeof check === "function") result[action] = introspectCheck(check);
+	else if (typeof check === "object" && check !== null) for (const [nested, entry] of Object.entries(introspectModule(check))) result[`${action}.${nested}`] = entry;
+	return result;
+}
+/** Every live resource's ACTUAL gates, keyed by arc resource name. */
+function introspectRegistry(registry) {
+	const modules = {};
+	for (const entry of registry.getAll()) {
+		const map = {};
+		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;
+}
+function buildPermissionMatrix(options = {}) {
+	const platform = [...options.platformRoles ?? []];
+	const branch = [...options.orgRoles ?? []];
+	const modules = {};
+	for (const [name, mod] of Object.entries(options.curatedModules ?? {})) if (typeof mod === "object" && mod !== null) modules[name] = introspectModule(mod);
+	for (const [name, mod] of Object.entries(options.fallbackModules ?? {})) {
+		if (modules[name]) continue;
+		if (typeof mod === "object" && mod !== null) modules[name] = introspectModule(mod);
+	}
+	if (options.registry) Object.assign(modules, introspectRegistry(options.registry));
+	return {
+		roles: [.../* @__PURE__ */ new Set([...platform, ...branch])],
+		roleGroups: {
+			platform,
+			branch
+		},
+		modules
+	};
+}
+//#endregion
+export { requireAgentScope as A, requireAuth as B, createOrgPermissions as C, requireScopeContext as D, requireOrgRole as E, allowPublic as F, when as G, requirePlatformRole as H, anyOf as I, scopeOf as K, deny as L, requireMandate as M, allOf as N, requireServiceScope as O, allow as P, denyAll as R, createDynamicPermissionMatrix as S, requireOrgMembership as T, requireRoles as U, requireOwnership as V, roles as W, requireGrant as _, adminOnly as a, describePermissionMap as b, ownerWithAdminBypass as c, publicRead as d, publicReadAdminWrite as f, modeSatisfies as g, GRANT_MODES as h, introspectRegistry as i, requireDPoP as j, requireTeamMembership as k, permissionMatrix as l, createRoleHierarchy as m, introspectCheck as n, authenticated as o, readOnly as p, introspectModule as r, fullPublic as s, buildPermissionMatrix as t, presets_exports as u, collectPublicSurface as v, requireOrgInScope as w, explainAccess as x, describePermission as y, not as z };

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

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { r as ForbiddenError } from "./errors-Cj42AntO.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.
@@ -40,9 +40,7 @@ async function executePipeline(steps, ctx, handler, operation) {
 			case "transform":
 				transforms.push(step);
 				break;
-			case "interceptor":
-				interceptors.push(step);
-				break;
+			case "interceptor": interceptors.push(step);
 		}
 	}
 	for (const g of guards) if (!await g.handler(ctx)) throw new ForbiddenError(`Guard '${g.name}' denied access`);

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.31.0 | MIT | https://classytic.com */
-import { n as pipe, t as executePipeline } from "../pipe-DRDNsI2T.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.