@classytic/arc 2.28.0 → 2.31.0

package/dist/idempotency/index.d.mts

@@ -1,5 +1,6 @@
-import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-Uk8ONJv7.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-UDtLaNj6.mjs";
+
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-DEWNOMza.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-CduhKsJi.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/idempotency/idempotencyPlugin.d.ts

package/dist/idempotency/index.mjs

@@ -1,9 +1,10 @@
-import { n as requireSingleHeaderValue } from "../headers-BvlQSDMB.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
-import { t as createIdempotencyResult } from "../interface-n5hpKg1d.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { n as requireSingleHeaderValue } from "../headers-3zvE0rM3.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-D1MP_gRG.mjs";
+import { t as createIdempotencyResult } from "../interface-DYzM0q-u.mjs";
+import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
-import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { update } from "@classytic/repo-core/update";
 //#region src/idempotency/repository-idempotency-adapter.ts
 function repositoryAsIdempotencyStore(repository, defaultTtlMs) {

package/dist/idempotency/redis.d.mts

@@ -1,2 +1,3 @@
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-UDtLaNj6.mjs";
+
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-CduhKsJi.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/idempotency/redis.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/idempotency/stores/redis.ts
 var RedisIdempotencyStore = class {
 	name = "redis";

package/dist/{index-CjVg-Epg.d.mts → index-Bc2ox8_U.d.mts}

@@ -1,7 +1,8 @@
-import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-DPRH0Cme.mjs";
-import { i as RequestScope } from "./types-DjC-KUCz.mjs";
-import { c as AnyRecord, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
-import "./fastify-augmentation-OzYGIiU1.mjs";
+
+import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-CpzxqePp.mjs";
+import { i as RequestScope } from "./types-ChuShpCP.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "./types-B7XeLEgK.mjs";
+import "./fastify-augmentation-zh0_AYHa.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";
@@ -170,7 +171,7 @@ declare function defineAction<TSchema extends z.ZodTypeAny | undefined = undefin
 //#endregion
 //#region src/core/defineResource/seams.d.ts
 /**
- * Structural adapter boundary — the `ControllerLike` pattern (v2.10.6)
+ * Structural adapter boundary — the `ControllerLike` pattern
  * applied to adapters. `DataAdapter<T>` is invariant in `T`, so a
  * `DataAdapter<HydratedDocument<IProduct>>` built by the HOST does not
  * assign to a module's `DataAdapter<AnyRecord>` slot; before this type,

package/dist/{index-CG4yqMDB.d.mts → index-C-481Zf2.d.mts}

@@ -1,3 +1,5 @@
+
+import { r as PermissionCheck } from "./types-B7XeLEgK.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/integrations/jobs/execution.d.ts
 /**
@@ -43,18 +45,6 @@ interface ExecuteTimedHandlerOptions<T> {
 declare function executeTimedHandler<T>(options: ExecuteTimedHandlerOptions<T>): Promise<T>;
 //#endregion
 //#region src/integrations/jobs/types.d.ts
-/**
- * Job queue integration — public contract (definitions, meta, dispatcher).
- *
- * Directory map (mechanical split of the former single file):
- *   types.ts     — this contract + `defineJob`
- *   execution.ts — `executeTimedHandler` (timeout / cancellation / bulkhead)
- *   repeat.ts    — repeatable-schedule reconciliation (boot hygiene)
- *   plugin.ts    — BullMQ wiring (queues, workers, DLQ, routes, shutdown)
- *   index.ts     — public barrel; `src/integrations/jobs.ts` re-exports it
- *                  so the package subpath is unchanged
- */
-/** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
 interface JobRepeatOptions {
   /** Cron pattern (e.g. '0 9 * * *' = every day 09:00). Mutually exclusive with `every`. */
   pattern?: string;
@@ -177,6 +167,61 @@ interface JobsPluginOptions {
   jobs: JobDefinition[];
   /** URL prefix for job management endpoints (default: '/jobs') */
   prefix?: string;
+  /**
+   * Job management HTTP endpoints (`GET <prefix>/stats`,
+   * `GET <prefix>/:queue/:id/status`).
+   *
+   * **Disabled by default.** A job status carries `returnValue` and
+   * `failedReason` — the handler's own output and error text, which routinely
+   * hold export URLs, billing results, model output, recipient addresses, or
+   * internal stack detail. Serving that unauthenticated turns a job id into a
+   * read primitive over other tenants' work.
+   *
+   * Enable it deliberately, with a permission check:
+   *
+   * ```ts
+   * managementRoutes: { operatorPermission: requireRoles(["platform-ops"]) }
+   * ```
+   *
+   * Queue-level counts are also available through the metrics/health
+   * integration, which does not expose individual jobs.
+   */
+  managementRoutes?: false | {
+    /**
+     * REQUIRED — arc will not mount an unguarded management surface.
+     *
+     * **This is an OPERATOR surface, not a tenant-facing one.** A BullMQ job
+     * carries no framework-level tenant identity, and `getStatus` fetches
+     * straight by queue + id, so a row-level `policy` on the decision has
+     * nothing to filter: `requireOrgRole("manager")` would let a manager in
+     * org A read a known job handle from org B. `/stats` is inherently
+     * global for the same reason.
+     *
+     * Gate it on an operator role — `requireRoles(["platform-ops"])` — and
+     * keep tenant-facing job status in a resource that owns its own row
+     * policy. Arc REFUSES a request whose decision carries a `policy`
+     * rather than silently ignoring it.
+     */
+    operatorPermission: PermissionCheck;
+    /**
+     * Accept an `operatorPermission` that arc cannot prove is platform-only.
+     *
+     * By default the gate must carry `_platformOnly` (i.e. come from
+     * `requirePlatformRole`), because that property is unprovable from
+     * outside: `requireOrgRole("manager")` and the default
+     * `requireRoles(["ops"])` both return a bare allow with no policy, so a
+     * manager in org A passes and reads a known handle from org B. Boot fails
+     * rather than serving a surface whose guard reads as tenant-scoped.
+     *
+     * Set this only for a custom check you have verified consults platform
+     * identity alone.
+     */
+    allowUnverifiedOperatorPermission?: boolean;
+    /** Include the handler's return value in a status response. Default `false`. */
+    exposeResult?: boolean;
+    /** Include `failedReason` in a status response. Default `false`. */
+    exposeFailureReason?: boolean;
+  };
   /** Bridge job events to Arc's event bus (default: true) */
   bridgeEvents?: boolean;
   /** Default job options applied to all jobs */
@@ -192,19 +237,30 @@ interface JobsPluginOptions {
   };
 }
 interface JobDispatcher {
-  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<{
-    jobId: string;
-  }>;
+  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<JobHandle>;
   getQueue(name: string): unknown | null;
   getStats(): Promise<Record<string, QueueStats>>;
   /**
    * Fetch a point-in-time status snapshot for a job by its ID.
-   * Searches across all registered queues.
-   * Returns `null` if the job doesn't exist or has been removed by retention policy.
+   * QUEUE-QUALIFIED: BullMQ job ids are local to their queue, so an id alone
+   * cannot identify a job. `dispatch()` returns the queue name alongside the id
+   * for exactly this reason.
+   *
+   * Returns `null` if the queue is not registered, or the job doesn't exist /
+   * has been removed by retention policy.
    */
-  getStatus(jobId: string): Promise<JobStatus | null>;
+  getStatus(queue: string, jobId: string): Promise<JobStatus | null>;
   close(): Promise<void>;
 }
+/**
+ * A dispatched job's address. The queue is part of the identity because BullMQ
+ * ids are queue-local — two queues can both hold `"123"`.
+ */
+interface JobHandle {
+  /** Registered job name (= queue name). */
+  queue: string;
+  jobId: string;
+}
 interface QueueStats {
   waiting: number;
   active: number;

package/dist/{index-BMnbzvtO.d.mts → index-CEJNZFtX.d.mts}

@@ -1,6 +1,7 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-BGZCzOGL.mjs";
-import { i as RequestScope, n as Mandate } from "./types-DjC-KUCz.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
+
+import { r as CacheStore, t as CacheLogger } from "./interface-BOk3YnTz.mjs";
+import { i as RequestScope, n as Mandate } from "./types-ChuShpCP.mjs";
+import { i as PermissionContext, r as PermissionCheck, t as AuthorizationDecision } from "./types-B7XeLEgK.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -162,13 +163,37 @@ interface RequireAgentScopeOptions<TDoc = Record<string, unknown>> extends Requi
  */
 declare function requireAgentScope<TDoc = Record<string, unknown>>(opts: RequireAgentScopeOptions<TDoc>): PermissionCheck<TDoc>;
 //#endregion
-//#region src/permissions/applyPermissionResult.d.ts
+//#region src/permissions/authorizationDecision.d.ts
 /**
- * Normalize a permission check return value (`boolean | PermissionResult`)
- * into a concrete `PermissionResult`. This is the only place in Arc that
- * promotes booleans to results — keeps the type narrowing honest everywhere.
+ * A permission check returns either a bare boolean (terse allow/deny sugar) or
+ * a full {@link AuthorizationDecision}. There is no legacy `PermissionResult` —
+ * `AuthorizationDecision` is arc's single authorization contract.
  */
-declare function normalizePermissionResult(result: boolean | PermissionResult): PermissionResult;
+type PermissionCheckReturn = boolean | AuthorizationDecision;
+/**
+ * Normalize a check return into the canonical {@link AuthorizationDecision}.
+ * A boolean promotes to `{ effect: "allow" | "deny" }`; a decision passes
+ * through. This is the ONE place booleans are promoted, so the rest of the
+ * pipeline only ever handles decisions.
+ */
+declare function normalizeToDecision(result: PermissionCheckReturn): AuthorizationDecision;
+/**
+ * Run a permission check and return a canonical {@link AuthorizationDecision} —
+ * the transport-neutral PDP (HTTP, aggregation, MCP, and any future transport).
+ * A thin mapper over {@link evaluatePermissionOutcome}:
+ *
+ *   - a structured `ArcError` is RE-THROWN so the transport surfaces it verbatim
+ *     (e.g. a tier gate throwing `arc.tier_required` with machine-readable meta);
+ *   - any OTHER throw is fail-closed to a `deny` decision (a broken check must
+ *     never fall open to a 500 that skips authorization).
+ *
+ * Pure w.r.t. the request — it neither reads a reply nor mutates the request.
+ * Callers translate the returned decision into their own response mechanism and
+ * apply side-effects via {@link applyAuthorizationDecision}. HTTP additionally
+ * hardens a *thrown* check to 403-even-when-anonymous — that transport-specific
+ * nuance lives in {@link evaluateAndApplyPermission}, not here.
+ */
+declare function evaluatePermissionDecision(check: PermissionCheck, context: PermissionContext): Promise<AuthorizationDecision>;
 /**
  * Minimal shape of a Fastify request that can receive permission side-effects.
  * We avoid depending on the full augmented `FastifyRequest` type here because
@@ -180,8 +205,9 @@ type RequestSink = FastifyRequest & {
   scope?: RequestScope;
 };
 /**
- * Apply a granted `PermissionResult` to a Fastify request — merges row-level
- * filters into `_policyFilters` and conditionally installs the scope.
+ * Apply an allowed {@link AuthorizationDecision} to a Fastify request — conjoins
+ * the decision's row-level `policy` into `_policyFilters` and conditionally
+ * installs the `scope`.
  *
  * **Scope install rule:** only writes `scope` when the current request scope
  * is absent or `public`. This prevents downgrading an already-authenticated
@@ -189,13 +215,41 @@ type RequestSink = FastifyRequest & {
  * narrower `service` scope — the original `member` wins because it came from
  * a more authoritative source).
  *
- * Safe to call with a non-granted result — it simply no-ops. Callers should
- * still check `result.granted` and send an error response before reaching here,
- * but this function tolerates the misuse defensively.
+ * Safe to call with a denied decision — it simply no-ops. Callers should still
+ * check `decision.effect` and send an error response before reaching here, but
+ * this function tolerates the misuse defensively.
+ *
+ * This is the enforcement point (PEP) — the ONE place scope + data policy are
+ * installed (and the obligation seam lives).
+ */
+declare function applyAuthorizationDecision(decision: AuthorizationDecision, request: RequestSink): void;
+//#endregion
+//#region src/permissions/context.d.ts
+/**
+ * Resolve the request scope for a permission check. Prefers the context's
+ * first-class `scope`; falls back to the raw HTTP `request.scope` when present,
+ * else `PUBLIC_SCOPE`. Primitives MUST use this instead of touching
+ * `ctx.request` so scope threads through combinators and non-HTTP transports
+ * (MCP, jobs) — which have no request — resolve identity correctly.
  */
-declare function applyPermissionResult(result: PermissionResult, request: RequestSink): void;
+declare function scopeOf(ctx: PermissionContext): RequestScope;
 //#endregion
 //#region src/permissions/core.d.ts
+/**
+ * Build an `allow` {@link AuthorizationDecision}, optionally attaching a row-level
+ * `policy` and/or a `scope` to install. The idiomatic "grant" return for arc
+ * 2.30 checks (parallels Cedar's `permit`).
+ *
+ * @example
+ * return allow();                                  // simple grant
+ * return allow({ policy: { ownerId: userId } });   // grant + row policy
+ */
+declare function allow(extra?: Omit<AuthorizationDecision, "effect">): AuthorizationDecision;
+/**
+ * Build a `deny` {@link AuthorizationDecision} with an optional human-readable
+ * reason (parallels Cedar's `forbid`). The idiomatic "refuse" return.
+ */
+declare function deny(reason?: string): AuthorizationDecision;
 /**
  * Allow public access (no authentication required).
  *
@@ -248,6 +302,24 @@ declare function requireRoles(roles: readonly string[], options?: {
    */
   includeOrgRoles?: boolean;
 }): PermissionCheck;
+/**
+ * Require a PLATFORM role — global roles only. An organization role can never
+ * satisfy this gate.
+ *
+ * `requireRoles(["ops"])` also accepts an ORG role named `ops` (that is its
+ * documented default), and `requireOrgRole("manager")` grants ANY organization's
+ * manager. Both return a bare allow with no policy, so a surface that is global
+ * by construction — a queue dashboard, a cluster-wide operations endpoint —
+ * cannot distinguish them from a real operator gate by looking at the decision.
+ * That makes "platform-only" a property the check has to DECLARE, which is what
+ * `_platformOnly` records and what such a surface can then require.
+ *
+ * Elevated scope passes: platform admin is the identity this gate is for.
+ *
+ * @example
+ * permissions: { list: requirePlatformRole("platform-ops") }
+ */
+declare function requirePlatformRole(...args: string[] | [readonly string[]]): PermissionCheck;
 /**
  * Short-form alias of `requireRoles()`. Identical behavior — checks both
  * platform roles AND org roles. Prefer `requireRoles` for new code; this
@@ -272,11 +344,18 @@ declare function requireOwnership<TDoc = Record<string, unknown>>(ownerField?: E
 /**
  * Combine multiple checks — ALL must pass (AND logic).
  *
- * Each child runs against the **accumulated** state of previous children:
- *   - `filters` from earlier children merge into the next child's `_policyFilters`
- *   - `scope` from earlier children installs on the request before the next child runs
+ * Evaluation is PURE — nothing is written to the request. Each child runs
+ * against the accumulated state of previous children, threaded through a fresh
+ * child context:
+ *   - `policy` from earlier children is CONJOINED (logical AND) — a later child
+ *     can add or narrow restrictions but never silently replaces an earlier
+ *     child's constraint on the same key (conflicting values are preserved under
+ *     `$and`; see `conjoinPolicyFilters`)
+ *   - `scope` installed by an earlier child is visible to the next through
+ *     `scopeOf(ctx)`, and never downgrades an already-authoritative scope
  *
- * The final result carries both merged `filters` and merged `scope`.
+ * The returned decision carries the merged `policy` + `scope`; the enforcement
+ * point (`applyAuthorizationDecision`) applies them to the request once.
  *
  * @example
  * ```typescript
@@ -449,6 +528,145 @@ declare function createOrgPermissions(config: {
  */
 declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
 //#endregion
+//#region src/permissions/explain.d.ts
+/**
+ * The statically-known requirement of a permission check.
+ *
+ * - `public` — `allowPublic()`; anyone passes.
+ * - `roles` — grants if the caller holds ANY of these (platform OR org roles,
+ *   unioned — matches how `requireRoles`/`requireOrgRole`/`anyOf` compose).
+ * - `scoped` — grants only within a caller SCOPE dimension (`_scopeContext`,
+ *   e.g. `{ branchRole: "head_office" }`), optionally combined with `roles`. The
+ *   scope dimensions are known statically even though their per-request VALUES
+ *   aren't, so a consumer that holds the caller's scope (a FE that knows the
+ *   active branch's role) can decide it client-side — the piece a flat `roles`
+ *   requirement could not express.
+ * - `authenticated` — the check reads request-time facts (custom auth, service
+ *   scope, ownership, grants) that no static analysis can decide; the definitive
+ *   answer is computed per request. Treat as "server decides".
+ */
+type PermissionRequirement = {
+  readonly kind: "public";
+} | {
+  readonly kind: "roles";
+  readonly roles: readonly string[];
+  /**
+   * `true` when these roles are NECESSARY but not SUFFICIENT — the gate is an
+   * `allOf(...)` that also carries an opaque runtime branch (ownership /
+   * custom / dynamic / flow-mode …). A role MATCH is then `conditional`, not a
+   * definitive `allow`; a MISMATCH is still a definitive `deny`.
+   */
+  readonly conditional?: boolean;
+} | {
+  readonly kind: "scoped";
+  /** Required scope dimensions: `value` string = must equal; `undefined` = must be present. */
+  readonly scope: Readonly<Record<string, string | undefined>>;
+  /** Roles ALSO required alongside the scope (union of platform + org roles), if any. */
+  readonly roles?: readonly string[];
+  /** See `roles.conditional` — the composite also has an opaque/contradictory branch. */
+  readonly conditional?: boolean;
+} | {
+  readonly kind: "authenticated";
+};
+/**
+ * Extract a check's static requirement from its `PermissionCheckMeta`. Public
+ * wins; then a scope-context gate (optionally with roles); then the union of
+ * platform + org roles a role gate declares; otherwise "authenticated"
+ * (auth-required / custom / request-time checks). An `allOf` that couldn't be
+ * fully captured statically carries `conditional: true` (see `_conditional`).
+ */
+declare function describePermission(check: PermissionCheck): PermissionRequirement;
+/** Result of {@link explainAccess}. */
+interface AccessExplanation {
+  /**
+   * `allow` / `deny` are DEFINITIVE from static metadata (public, or a role
+   * match against the supplied principal). `conditional` means the gate reads
+   * request-time state, so the real decision is made per request — this is not a
+   * denial, it is "cannot be determined statically".
+   */
+  decision: "allow" | "deny" | "conditional";
+  /** Human-readable rationale, safe to surface in a UI or an audit report. */
+  reason: string;
+  /** The check's static requirement (the same value {@link describePermission} returns). */
+  requirement: PermissionRequirement;
+}
+/**
+ * Explain whether a principal (by roles) passes a permission check, from static
+ * metadata alone — for permission-matrix UIs, docs, and audits. Omit `principal`
+ * to get the requirement-only view (roles → `conditional`).
+ *
+ * @example
+ * explainAccess(requireRoles("admin"), { roles: ["editor"] })
+ * // → { decision: "deny", reason: "requires one of: admin", requirement: { kind: "roles", roles: ["admin"] } }
+ */
+declare function explainAccess(check: PermissionCheck, principal?: {
+  roles?: readonly string[];
+  orgRoles?: readonly string[];
+  /** The caller's scope-context values (e.g. `{ branchRole: "head_office" }`) — supply to decide a `scoped` gate. */
+  scope?: Readonly<Record<string, string | undefined>>;
+}): AccessExplanation;
+/**
+ * Introspect a whole permission map (`{ list, get, create, ... }` or any
+ * action→check record) into `action → requirement`. The reusable core of a
+ * `/permissions/matrix` endpoint or an access audit — framework-owned, so a host
+ * never hand-rolls `(check as any)._roles` peeking. Undefined slots (a CRUD op
+ * with no gate = public-by-omission) surface as `public` so the inventory is
+ * honest about what's exposed.
+ */
+declare function describePermissionMap(permissions: Readonly<Record<string, PermissionCheck | undefined>>): Record<string, PermissionRequirement>;
+/**
+ * The public attack surface of a permission map — the actions reachable with NO
+ * authentication (explicit `allowPublic()` or public-by-omission). Empty is the
+ * healthy default for a protected resource; a non-empty list is what a
+ * "what's exposed?" audit report should show.
+ */
+declare function collectPublicSurface(permissions: Readonly<Record<string, PermissionCheck | undefined>>): string[];
+//#endregion
+//#region src/permissions/filter-merge.d.ts
+/**
+ * Policy-filter composition — logical AND, never last-writer-wins.
+ *
+ * Row-level policy filters can arrive from several INDEPENDENT sources for one
+ * request: a tenant preset, an `ownedByUser` grant, an `allOf(...)` branch, a
+ * host permission check. Every one of them is a RESTRICTION the row must
+ * satisfy, so composing them is logical AND.
+ *
+ * The historical `{ ...base, ...incoming }` shallow spread did NOT implement AND:
+ * when two sources constrained the SAME key with different values, the later one
+ * silently REPLACED the earlier one — widening (or erasing) a restriction another
+ * layer deliberately imposed. That is a defense-in-depth defect, not a
+ * refinement. "Later can refine" is only sound when the refinement is provably
+ * narrower, and a bare overwrite proves nothing.
+ *
+ * {@link conjoinPolicyFilters} composes with AND semantics while preserving the
+ * common case byte-for-byte:
+ *
+ *  - key present on only one side      → carried through flat. Non-overlapping
+ *    filters (the ~99% case) produce exactly the same object the old spread did,
+ *    so there is ZERO behavior change for them.
+ *  - same key, deep-equal value        → kept once (idempotent — e.g. two checks
+ *    both pinning the same `organizationId`).
+ *  - same key, DIFFERENT value         → BOTH constraints are preserved under an
+ *    `$and`, so a row must satisfy both. For flat equality that conjunction is
+ *    unsatisfiable, so the query returns nothing — the safe, correct outcome for
+ *    contradictory policies (deny), and the earlier restriction is never dropped.
+ *
+ * Adapter safety: mongokit / sqlitekit compile `$and` natively at the DB layer,
+ * and arc's in-memory `simpleEqualityMatcher` (AccessControl.checkPolicyFilters)
+ * already fail-closes on operator-shaped filters. So a produced `$and` is either
+ * evaluated correctly by the DB or rejected fail-closed in memory — both safe.
+ *
+ * This is the pragmatic, adapter-neutral form of the AND semantics. A canonical
+ * filter IR in `repo-core` (nested and/or/not nodes each adapter compiles) is the
+ * fuller design, but this closes the security defect without one.
+ */
+/**
+ * Conjoin two policy-filter maps with AND semantics. Never silently overwrites a
+ * same-key constraint with a different value — conflicting keys are preserved
+ * under `$and`. See the module doc for the full contract.
+ */
+declare function conjoinPolicyFilters(base: Record<string, unknown> | undefined, incoming: Record<string, unknown> | undefined): Record<string, unknown>;
+//#endregion
 //#region src/permissions/grants.d.ts
 /**
  * The grant-mode lattice, weakest → strongest. Holding a mode satisfies
@@ -474,7 +692,7 @@ declare function modeSatisfies(held: string | undefined, required: GrantMode): b
  * - `{ mode }` — the strongest mode the caller holds on `ctx.resourceId`;
  *   the combinator applies the lattice against the required mode.
  * - `{ filters }` — list-shaped resolution: row filters that scope the
- *   query to visible records (flows through `PermissionResult.filters` →
+ *   query to visible records (flows through the decision's `policy` →
  *   `_policyFilters` → the repository query). Grants access with the
  *   filters attached.
  * - `{ mode, filters }` — mode gates; filters ride along when it passes.
@@ -655,8 +873,8 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  *
  * **Two call shapes:**
  * ```typescript
- * requireOrgInScope('acme-holding')                          // static
- * requireOrgInScope((ctx) => ctx.request.params.orgId)       // dynamic
+ * requireOrgInScope('acme-holding')                    // static
+ * requireOrgInScope((ctx) => ctx.params?.orgId)        // dynamic — from ctx facts, not the raw request
  * ```
  *
  * `elevated` scope grants unconditionally (cross-org bypass).
@@ -664,9 +882,9 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  * @example
  * ```typescript
  * permissions: {
- *   list: requireOrgInScope((ctx) => ctx.request.params.orgId),
+ *   list: requireOrgInScope((ctx) => ctx.params?.orgId),
  *   create: allOf(
- *     requireOrgInScope((ctx) => ctx.request.body?.organizationId),
+ *     requireOrgInScope((ctx) => (ctx.data as { organizationId?: string })?.organizationId),
  *     requireOrgRole('admin'),
  *   ),
  * }
@@ -772,4 +990,4 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { allOf as A, applyPermissionResult as B, requireGrant as C, PermissionEventBus as D, DynamicPermissionMatrixConfig as E, requireAuth as F, requireDPoP as G, RequireAgentScopeOptions as H, requireOwnership as I, requireMandate as K, requireRoles as L, anyOf as M, denyAll as N, createDynamicPermissionMatrix as O, not as P, roles as R, modeSatisfies as S, DynamicPermissionMatrix as T, RequireMandateOptions as U, normalizePermissionResult as V, requireAgentScope as W, createRoleHierarchy as _, permissionMatrix as a, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, allowPublic as j, createOrgPermissions as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, GRANT_MODES as v, ConnectEventsOptions as w, RequireGrantOptions as x, GrantMode as y, when as z };
+export { evaluatePermissionDecision as $, explainAccess as A, anyOf as B, requireGrant as C, collectPublicSurface as D, PermissionRequirement as E, createDynamicPermissionMatrix as F, requireOwnership as G, denyAll as H, createOrgPermissions as I, roles as J, requirePlatformRole as K, allOf as L, DynamicPermissionMatrix as M, DynamicPermissionMatrixConfig as N, describePermission as O, PermissionEventBus as P, applyAuthorizationDecision as Q, allow as R, modeSatisfies as S, AccessExplanation as T, not as U, deny as V, requireAuth as W, scopeOf as X, when as Y, PermissionCheckReturn as Z, createRoleHierarchy as _, permissionMatrix as a, requireMandate as at, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, normalizeToDecision as et, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireDPoP as it, ConnectEventsOptions as j, describePermissionMap as k, readOnly as l, requireServiceScope as m, authenticated as n, RequireMandateOptions as nt, presets_d_exports as o, requireScopeContext as p, requireRoles as q, fullPublic as r, requireAgentScope as rt, publicRead as s, adminOnly as t, RequireAgentScopeOptions as tt, requireOrgInScope as u, GRANT_MODES as v, conjoinPolicyFilters as w, RequireGrantOptions as x, GrantMode as y, allowPublic as z };