@classytic/arc 2.41.1 → 2.44.0

package/dist/{outbox-module-BHdUnuuK.d.mts → outbox-module-gZCHoE4H.d.mts}

@@ -1,10 +1,24 @@
 
-import { a as EventTransport, n as DomainEvent, t as DeadLetteredEvent } from "./EventTransport-CbUKDzZZ.mjs";
-import { t as ArcModule } from "./types-DfVDvkdP.mjs";
+import { a as EventTransport, n as DomainEvent, t as DeadLetteredEvent } from "./EventTransport-CiicKz2Z.mjs";
+import { n as ArcModule } from "./types-BJ-2XqVF.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/health.d.ts
+/** Pending age past which the relay counts as stalled. */
+declare const DEFAULT_RELAY_LAG_UNHEALTHY_MS: number;
+interface OutboxHealth {
+  pending: number;
+  deadLetter: number;
+  /** Age of the oldest pending event, `null` when nothing is pending. */
+  relayLagMs: number | null;
+  healthy: boolean;
+}
+/** A store that can report its own depth — both reads are optional on the contract. */
+type OutboxHealthStore = OutboxStore & Required<Pick<OutboxStore, "countByStatus" | "oldestPendingAgeMs">>;
+declare function readOutboxHealth(store: OutboxHealthStore, relayLagUnhealthyMs?: number): Promise<OutboxHealth>;
+//#endregion
 //#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";
@@ -94,6 +108,8 @@ interface EventOutboxOptions {
    * logging and metrics. Must not throw — exceptions are swallowed.
    */
   readonly onError?: OutboxRelayErrorHandler;
+  /** Called with each event the transport accepted — observation only, never affects the batch. */
+  readonly onPublished?: (event: DomainEvent) => void;
   /**
    * Enable {@link EventTransport.publishMany} when the transport implements it.
    * Default: `true`. Set to `false` to force per-event `publish()` — useful
@@ -166,6 +182,7 @@ declare class EventOutbox {
   private readonly _consumerId;
   private readonly _leaseMs;
   private readonly _onError?;
+  private readonly _onPublished?;
   private readonly _usePublishMany;
   private readonly _sessionProvider?;
   private readonly _traceContextProvider?;
@@ -175,9 +192,11 @@ declare class EventOutbox {
    * 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}.
+   * resolved by another relay worker can't accumulate forever.
+   *
+   * A FALLBACK only: when the store reports `attempts` on the fenced claim
+   * (`repositoryAsOutboxStore` and primitives' `MemoryOutboxStore` do), the
+   * durable count wins — see the failure path in `relayBatch`.
    */
   private readonly _attempts;
   constructor(opts: EventOutboxOptions);
@@ -365,6 +384,46 @@ interface OutboxModuleOptions {
    * the events the previous process failed to publish.
    */
   runOnStart?: boolean;
+  /**
+   * The relay's readiness check (`/_health/ready`, name `<name>.relay`). NON-critical:
+   * a stalled relay is a cluster problem, and pulling this instance from rotation would
+   * not drain it. Unhealthy when anything is dead-lettered or the oldest pending event
+   * is older than `relayLagUnhealthyMs` (default 5 min), and when the store cannot
+   * report either. `false` omits the check.
+   *
+   * `probeCacheMs` (default 5000) is how long the check reuses its last reading.
+   * The reading costs two status counts and an oldest-pending lookup, and a
+   * readiness probe runs on EVERY replica every few seconds — uncached, 50 pods
+   * probed every 5 s is ~30 outbox queries a second, and a status count is at
+   * its most expensive during a backlog, the moment the database has least to
+   * spare. Concurrent probes also share one in-flight reading. Keep it at or
+   * below the probe interval; `0` reads on every probe. The `health()` export is
+   * never cached — an operator asking wants the current answer.
+   *
+   * `alertEveryMs` (default 5 min, `0` disables) schedules `<name>.health`, which logs
+   * while unhealthy: `marker: 'OUTBOX_RELAY_LAG'` at error, `marker: 'OUTBOX_DEAD_LETTER'`
+   * at warn. A readiness check is PULLED — nobody is paged by a degraded row in a probe
+   * body, so the stall is also pushed into the log where alerting reads it. It is a
+   * `kind: 'relay'` arm, so it runs wherever the relay runs (including a `role: 'relay'`
+   * process). A store that cannot report counts is warned about once, not every tick.
+   */
+  health?: {
+    relayLagUnhealthyMs?: number;
+    probeCacheMs?: number;
+    alertEveryMs?: number;
+  } | false;
+}
+/** Totals across the passes of one {@link OutboxModuleExports.drain}. */
+interface OutboxDrainResult {
+  passes: number;
+  relayed: number;
+  publishFailed: number;
+  deadLettered: number;
+  /**
+   * `true` once a pass found nothing VISIBLE to claim. Rows backing off after a failed
+   * publish are invisible until their retry time, so read `publishFailed` too.
+   */
+  drained: boolean;
 }
 /** What the module exports at `fastify.arc.modules.<name>`. */
 interface OutboxModuleExports {
@@ -385,6 +444,20 @@ interface OutboxModuleExports {
    * The pass runs scope-free, so each event opens its own (see `runWorkScope`).
    */
   requestDrain: () => void;
+  /**
+   * Relay passes until nothing visible is pending, and resolve with the totals —
+   * including events published BY the handlers it ran. For tests that assert what
+   * an event eventually did, and for a shutdown that should empty the queue.
+   * Bounded by `maxPasses` (default 100). Runs outside the caller's request scope,
+   * like {@link requestDrain}. Waits for this module's own in-flight passes (a nudge,
+   * a scheduled tick), whose leased rows no other pass can see; rows leased by
+   * ANOTHER process are not awaited.
+   */
+  drain: (options?: {
+    maxPasses?: number;
+  }) => Promise<OutboxDrainResult>;
+  /** The same reading as the readiness check. Throws when the store cannot report. */
+  health: () => Promise<OutboxHealth>;
 }
 /**
  * Compose the outbox as a module.
@@ -415,4 +488,4 @@ interface OutboxModuleExports {
  */
 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 };
+export { MemoryOutboxStore as a, OutboxRelayErrorHandler as c, DEFAULT_RELAY_LAG_UNHEALTHY_MS as d, OutboxHealth as f, createOutboxModule as i, OutboxRelayErrorKind as l, readOutboxHealth as m, OutboxModuleExports as n, EventOutbox as o, OutboxHealthStore as p, OutboxModuleOptions as r, EventOutboxOptions as s, OutboxDrainResult as t, RelayResult as u };

package/dist/permissions/index.d.mts

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

package/dist/permissions/index.mjs

@@ -1,6 +1,8 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { a as conjoinPolicyFilters, i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-DawKGoXb.mjs";
-import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-ChRvkuSZ.mjs";
-import { a as resolveEffectiveRoles, i as fields, n as applyFieldWritePermissions, t as applyFieldReadPermissions } from "../fields-BHrkoF5y.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-D8TBH44E.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 };
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as conjoinPolicyFilters } from "../filter-merge-DGM-GQ1J.mjs";
+import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-C76zD5pa.mjs";
+import { a as resolveEffectiveRoles, i as fields, n as applyFieldWritePermissions, t as applyFieldReadPermissions } from "../fields-A5crhsJb.mjs";
+import { i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-wX3SA9w_.mjs";
+import { i as resolveResourceRateLimiter, t as createMemoryResourceRateLimiter } from "../resourceRateLimit-urWPJxrt.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-C5ijIz5Q.mjs";
+export { GRANT_MODES, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, buildPermissionMatrix, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createMemoryResourceRateLimiter, 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, resolveResourceRateLimiter, roles, scopeOf, when };

package/dist/{permissions-D8TBH44E.mjs → permissions-C5ijIz5Q.mjs}

@@ -1,11 +1,12 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { a as conjoinPolicyFilters, i as normalizeToDecision } from "./authorizationDecision-DawKGoXb.mjs";
-import { n as getUserRoles } from "./userHelpers-ChRvkuSZ.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-CgenB1gv.mjs";
-import { n as declareRuntimeCapability } from "./runtimeCapabilities-CkhS6jn6.mjs";
-import { t as MemoryCacheStore } from "./memory-Iotz0cCx.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { t as arcLog } from "./logger-D4V1zGLI.mjs";
+import { t as conjoinPolicyFilters } from "./filter-merge-DGM-GQ1J.mjs";
+import { n as getUserRoles } from "./userHelpers-C76zD5pa.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-fvO6Ovzx.mjs";
+import { i as normalizeToDecision } from "./authorizationDecision-wX3SA9w_.mjs";
+import { n as declareRuntimeCapability } from "./runtimeCapabilities-DIMKMV2G.mjs";
+import { t as MemoryCacheStore } from "./memory-CTa5pOCW.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/permissions/context.ts
 /**
@@ -76,20 +77,78 @@ function deny(reason) {
 function normalizeVariadicOrArray(args) {
 	return Array.isArray(args[0]) ? args[0] : args;
 }
+/** A non-null, non-array object — the only shape a row policy can take. */
+function isPolicyObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Own keys, symbol-keyed included (a branded adapter-native filter is symbol-keyed). */
+function hasPolicyKeys(policy) {
+	return Object.keys(policy).length > 0 || Object.getOwnPropertySymbols(policy).length > 0;
+}
 /**
-* Allow public access (no authentication required).
+* Allow public access (no authentication required) — optionally row-filtered.
+*
+* Without options, anyone passes and sees everything the query asks for.
+*
+* With `policy`, anyone still passes, but only the rows the policy admits are
+* readable (or writable). This is the declarative form of a check that returns
+* `allow({ policy })`, and it exists because the hand-written form has a trap:
+* a check function is treated as PROTECTED unless it carries `_isPublic`, so a
+* custom "public, but only published rows" check that forgets to set the flag
+* answers every anonymous visitor with a 401 — the public page silently
+* becomes a login wall. `allowPublic({ policy })` sets it for you.
+*
+* Fail-closed on both ends:
+*  - a STATIC policy must be a non-empty object — `{}` filters nothing and is
+*    almost certainly a mistake, so it throws at definition time (use
+*    `allowPublic()` for an unrestricted gate);
+*  - a RESOLVER that returns anything but an object throws per request, which
+*    arc answers as a 403 for everyone. A forgotten branch that falls off the
+*    end of the function must not quietly mean "no filter". Return `{}` when a
+*    caller genuinely should be unrestricted.
+*
+* Composing: inside `anyOf`, the FIRST granting branch wins, and a public
+* branch grants everyone — so `anyOf(allowPublic({ policy }), requireRoles("admin"))`
+* filters admins too. Put the privileged branch first, or use the resolver
+* form and return `{}` for staff.
 *
 * @example
 * ```typescript
-* permissions: {
-*   list: allowPublic(),
-*   get: allowPublic(),
-* }
+* // Strangers see only published reviews, whatever filter they send.
+* list: allowPublic({ policy: { status: { $in: ["published", "flagged"] } } }),
+*
+* // Scope-aware: the author also sees their own pending review; staff see all.
+* list: allowPublic({
+*   policy: (ctx) => {
+*     const scope = scopeOf(ctx);
+*     if (isElevated(scope)) return {};
+*     const visible = { status: { $in: ["published", "flagged"] } };
+*     const userId = getUserId(scope);
+*     return userId ? { $or: [visible, { authorId: userId }] } : visible;
+*   },
+* }),
 * ```
 */
-function allowPublic() {
-	const check = () => true;
+function allowPublic(options) {
+	const policy = options?.policy;
+	if (policy === void 0) {
+		const check = () => true;
+		check._isPublic = true;
+		return check;
+	}
+	let check;
+	if (typeof policy === "function") check = async (ctx) => {
+		const resolved = await policy(ctx);
+		if (!isPolicyObject(resolved)) throw new Error(`[arc] allowPublic({ policy }) resolver returned ${resolved === null ? "null" : Array.isArray(resolved) ? "an array" : typeof resolved} for '${ctx.resource}:${ctx.action}'. Return a filter object, or {} to admit this caller unrestricted. Returning nothing is refused rather than read as 'no filter'.`);
+		return hasPolicyKeys(resolved) ? allow({ policy: resolved }) : allow();
+	};
+	else {
+		if (!isPolicyObject(policy)) throw new Error(`[arc] allowPublic({ policy }) expects a filter object or a function returning one, got ${policy === null ? "null" : Array.isArray(policy) ? "an array" : typeof policy}.`);
+		if (!hasPolicyKeys(policy)) throw new Error("[arc] allowPublic({ policy: {} }) filters nothing. Use allowPublic() for an unrestricted public gate, or give the policy a constraint.");
+		check = () => allow({ policy });
+	}
 	check._isPublic = true;
+	check._rowPolicy = true;
 	return check;
 }
 /**
@@ -262,8 +321,11 @@ function allOf(...checks) {
 	};
 	const roleBranches = checks.filter((c) => (c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0);
 	if (checks.some((c) => c._isDenied)) check._isDenied = true;
-	else if (checks.length > 0 && checks.every((c) => c._isPublic)) check._isPublic = true;
-	else if (roleBranches.length === 1) {
+	else if (checks.some((c) => c._deniedWhen)) check._deniedWhen = () => checks.some((c) => c._deniedWhen?.() === true);
+	if (check._isDenied) {} else if (checks.length > 0 && checks.every((c) => c._isPublic)) {
+		check._isPublic = true;
+		if (checks.some((c) => c._rowPolicy)) check._rowPolicy = true;
+	} else if (roleBranches.length === 1) {
 		const [rb] = roleBranches;
 		if (rb?._roles?.length) check._roles = [...rb._roles];
 		if (rb?._orgRoles?.length) check._orgRoles = [...rb._orgRoles];
@@ -274,7 +336,7 @@ function allOf(...checks) {
 	else scopeContext[dim] = val;
 	if (Object.keys(scopeContext).length > 0) check._scopeContext = scopeContext;
 	const hasMetaSurface = (c) => Boolean(c._isPublic || c._roles?.length || c._orgRoles?.length || c._scopeContext && Object.keys(c._scopeContext).length > 0);
-	const opaqueBranch = checks.some((c) => !hasMetaSurface(c) && !c._requiresAuth);
+	const opaqueBranch = checks.some((c) => !hasMetaSurface(c) && !c._requiresAuth && !c._deniedWhen);
 	const childConditional = checks.some((c) => c._conditional);
 	if (opaqueBranch || scopeConflict || childConditional) check._conditional = true;
 	return check;
@@ -302,9 +364,13 @@ function anyOf(...checks) {
 		}
 		return deny(reasons.join("; "));
 	};
+	const closed = (c) => Boolean(c._isDenied || c._deniedWhen?.());
 	if (checks.length > 0 && checks.every((c) => c._isDenied)) check._isDenied = true;
-	else if (checks.some((c) => c._isPublic)) check._isPublic = true;
-	else if (checks.every((c) => (c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0)) {
+	else if (checks.length > 0 && checks.every((c) => c._isDenied || c._deniedWhen)) check._deniedWhen = () => checks.every(closed);
+	else if (checks.some((c) => c._isPublic)) {
+		check._isPublic = true;
+		if (checks.find((c) => c._isPublic)?._rowPolicy) check._rowPolicy = true;
+	} else if (checks.every((c) => (c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0)) {
 		const roles = /* @__PURE__ */ new Set();
 		const orgRoles = /* @__PURE__ */ new Set();
 		for (const c of checks) {
@@ -314,9 +380,27 @@ function anyOf(...checks) {
 		if (roles.size > 0) check._roles = [...roles];
 		if (orgRoles.size > 0) check._orgRoles = [...orgRoles];
 		if (checks.some((c) => c._conditional)) check._conditional = true;
+		const scopes = checks.map((c) => c._scopeContext ?? {});
+		const key = (s) => JSON.stringify(Object.entries(s).sort(([a], [b]) => a.localeCompare(b)));
+		const first = scopes[0] ?? {};
+		if (scopes.every((s) => key(s) === key(first))) {
+			if (Object.keys(first).length > 0) check._scopeContext = { ...first };
+		} else check._conditional = true;
+	} else if (checks.some(isMembershipGate) && checks.every((c) => isMembershipGate(c) || isPlainRoleGate(c))) {
+		check._orgPermission = "membership";
+		const roles = /* @__PURE__ */ new Set();
+		const orgRoles = /* @__PURE__ */ new Set();
+		for (const c of checks) {
+			for (const r of c._roles ?? []) roles.add(r);
+			for (const r of c._orgRoles ?? []) orgRoles.add(r);
+		}
+		if (roles.size > 0) check._roles = [...roles];
+		if (orgRoles.size > 0) check._orgRoles = [...orgRoles];
 	}
 	return check;
 }
+const isMembershipGate = (c) => c._orgPermission === "membership" && !c._conditional && !c._scopeContext;
+const isPlainRoleGate = (c) => ((c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0) && !c._conditional && !c._scopeContext;
 /**
 * Invert a permission check. Grants when the wrapped check denies, denies
 * when the wrapped check grants. Useful for "block if X" patterns —
@@ -1085,25 +1169,33 @@ function createDynamicPermissionMatrix(config) {
 * fully captured statically carries `conditional: true` (see `_conditional`).
 */
 function describePermission(check) {
-	if (check._isDenied) return { kind: "denied" };
-	if (check._isPublic) return { kind: "public" };
+	if (check._isDenied || check._deniedWhen?.() === true) return { kind: "denied" };
+	if (check._isPublic) return check._rowPolicy ? {
+		kind: "public",
+		rowFiltered: true
+	} : { kind: "public" };
 	const roles = [...check._roles ?? [], ...check._orgRoles ?? []];
 	const scope = check._scopeContext;
-	const conditional = check._conditional ? true : void 0;
+	const conditional = check._conditional === true;
+	const flag = conditional ? { conditional: true } : {};
 	if (scope && Object.keys(scope).length > 0) return roles.length > 0 ? {
 		kind: "scoped",
 		scope,
 		roles,
-		conditional
+		...flag
 	} : {
 		kind: "scoped",
 		scope,
-		conditional
+		...flag
 	};
+	if (check._orgPermission === "membership" && !conditional) return roles.length > 0 ? {
+		kind: "member",
+		roles
+	} : { kind: "member" };
 	if (roles.length > 0) return {
 		kind: "roles",
 		roles,
-		conditional
+		...flag
 	};
 	return { kind: "authenticated" };
 }
@@ -1131,7 +1223,7 @@ function explainAccess(check, principal) {
 	};
 	if (requirement.kind === "public") return {
 		decision: "allow",
-		reason: "public — no authentication required",
+		reason: requirement.rowFiltered ? "public — no authentication required; rows narrowed by a policy" : "public — no authentication required",
 		requirement
 	};
 	if (requirement.kind === "authenticated") return {
@@ -1140,6 +1232,29 @@ function explainAccess(check, principal) {
 		requirement
 	};
 	const held = /* @__PURE__ */ new Set([...principal?.roles ?? [], ...principal?.orgRoles ?? []]);
+	if (requirement.kind === "member") {
+		const reason = `requires membership of the active organization${requirement.roles?.length ? ` or one of: ${requirement.roles.join(", ")}` : ""}`;
+		const byRole = requirement.roles?.filter((r) => held.has(r)) ?? [];
+		if (byRole.length > 0) return {
+			decision: "allow",
+			reason: `granted via role(s): ${byRole.join(", ")}`,
+			requirement
+		};
+		if (principal?.member === void 0) return {
+			decision: "conditional",
+			reason,
+			requirement
+		};
+		return principal.member ? {
+			decision: "allow",
+			reason: "granted as a member of the active organization",
+			requirement
+		} : {
+			decision: "deny",
+			reason,
+			requirement
+		};
+	}
 	if (requirement.kind === "scoped") {
 		const scopeReason = describeScope(requirement.scope);
 		const rolesReason = requirement.roles?.length ? `role(s) ${requirement.roles.join(", ")} + ` : "";
@@ -1600,12 +1715,9 @@ function readOnly(overrides) {
 *
 * ## 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.
+* `authenticated` means "the server decides" — a custom or request-time check
+* (ownership, service scope) — never "any logged-in user". Membership and
+* role/membership disjunctions are `member`; only opaque branches remain here.
 */
 /** Re-shape arc's typed requirement into the wire entry. */
 function introspectCheck(check) {
@@ -1623,6 +1735,10 @@ function introspectCheck(check) {
 		roles: req.roles ? [...req.roles] : [],
 		scope: { ...req.scope }
 	};
+	if (req.kind === "member") return {
+		type: "member",
+		roles: req.roles ? [...req.roles] : []
+	};
 	if (req.kind === "denied") return {
 		type: "denied",
 		roles: []

package/dist/{pipe-FMWNheSO.mjs → pipe-D81zMtWs.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { r as ForbiddenError } from "./errors-BH7YU_9O.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as ForbiddenError } from "./errors-CW4anJBy.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, 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-DHbyPo5j.mjs";
+import { Vn as IControllerResponse, _t as PipelineConfig, bt as Transform, gt as OperationFilter, ht as NextFunction, mt as Interceptor, pt as Guard, vt as PipelineContext, yt as PipelineStep } from "../index-WH7xgvxS.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;
@@ -11,7 +11,7 @@ interface GuardOptions {
  * @param name - Guard name (for debugging/introspection)
  * @param handlerOrOptions - Handler function or options object
  */
-declare function guard(name: string, handlerOrOptions: ((ctx: PipelineContext) => boolean | Promise<boolean>) | GuardOptions): Guard;
+export declare function guard(name: string, handlerOrOptions: ((ctx: PipelineContext) => boolean | Promise<boolean>) | GuardOptions): Guard;
 //#endregion
 //#region src/pipeline/intercept.d.ts
 interface InterceptOptions {
@@ -24,14 +24,14 @@ interface InterceptOptions {
  * @param name - Interceptor name (for debugging/introspection)
  * @param handlerOrOptions - Handler function or options object
  */
-declare function intercept(name: string, handlerOrOptions: ((ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>) | InterceptOptions): Interceptor;
+export declare function intercept(name: string, handlerOrOptions: ((ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>) | InterceptOptions): Interceptor;
 //#endregion
 //#region src/pipeline/pipe.d.ts
 /**
  * Compose pipeline steps into an ordered array.
  * Accepts guards, transforms, and interceptors in any order.
  */
-declare function pipe(...steps: PipelineStep[]): PipelineStep[];
+export declare function pipe(...steps: PipelineStep[]): PipelineStep[];
 /**
  * Execute a pipeline against a request context.
  *
@@ -44,7 +44,7 @@ declare function pipe(...steps: PipelineStep[]): PipelineStep[];
  * @param operation - The CRUD operation name
  * @returns The controller response (possibly modified by interceptors)
  */
-declare function executePipeline(steps: PipelineStep[], ctx: PipelineContext, handler: (ctx: PipelineContext) => Promise<IControllerResponse<unknown>>, operation: string): Promise<IControllerResponse<unknown>>;
+export declare function executePipeline(steps: PipelineStep[], ctx: PipelineContext, handler: (ctx: PipelineContext) => Promise<IControllerResponse<unknown>>, operation: string): Promise<IControllerResponse<unknown>>;
 //#endregion
 //#region src/pipeline/transform.d.ts
 interface TransformOptions {
@@ -57,6 +57,6 @@ interface TransformOptions {
  * @param name - Transform name (for debugging/introspection)
  * @param handlerOrOptions - Handler function or options object
  */
-declare function transform(name: string, handlerOrOptions: ((ctx: PipelineContext) => PipelineContext | undefined | Promise<PipelineContext | undefined>) | TransformOptions): Transform;
+export declare function transform(name: string, handlerOrOptions: ((ctx: PipelineContext) => PipelineContext | undefined | Promise<PipelineContext | undefined>) | TransformOptions): Transform;
 //#endregion
-export { type Guard, type Interceptor, type NextFunction, type OperationFilter, type PipelineConfig, type PipelineContext, type PipelineStep, type Transform, executePipeline, guard, intercept, pipe, transform };
+export type { Guard, GuardOptions, InterceptOptions, Interceptor, NextFunction, OperationFilter, PipelineConfig, PipelineContext, PipelineStep, Transform, TransformOptions };

package/dist/pipeline/index.mjs

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