@ultimat3/policy 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,101 @@
+# @ultimat3/policy
+
+The one authz rule, evaluated in every surface. Tier 2.
+
+## Boundary
+
+- May import: `@ultimat3/core`. That is all it needs.
+- Never import `@ultimat3/http`/`@ultimat3/entity` (same tier) or any surface package.
+  Surface denial shapes are declared structurally in `surfaces.ts`.
+
+## The one predicate signature
+
+```ts
+interface PolicyArgs<I = unknown, R = unknown> {
+  readonly input: I;
+  readonly actor: Actor | null;
+  readonly row: R | null; // required; `null` = this rule decides on input alone
+  readonly ctx?: Ctx;
+}
+```
+
+Every predicate on every surface sees these four fields. `row` is `R | null` rather than
+`row?: R` on purpose — an optional field lets a surface forget it and lets the two shapes
+drift apart again, which is exactly how the realtime row gate ended up nesting the row
+inside `input`.
+
+`EvaluateArgs<I, R>` is what *callers* pass and its `row` **is** optional; `evaluate()`
+normalises a missing row to `null` before the predicate sees it. That is the only place the
+two differ, and it is why a surface that decides on input alone needs no edit.
+
+## Rules
+
+- **Never add a second authz path.** If a surface cannot use `evaluate()`, add an
+  adapter to `surfaces.ts` — nothing else.
+- **One predicate shape.** A row-level rule reads `args.row`. Never pass a row through
+  `input`, and never add a per-surface args type.
+- A policy is pure and synchronous. No I/O, no `await`. Load the row first, then decide.
+- `reason` must be safe to log: name permissions and clauses, never row data or PII —
+  `row` being in scope changes nothing about what a denial is allowed to say. The same
+  guarantee is what a `DecisionSink` event inherits: `decisions.ts` carries the label, the
+  deciding clause and the actor's identifiers, and **never `row` or `input`**.
+- A missing policy is refused by the **type system**, not by a throw: `ActionDef.policy`
+  is a required field in `@ultimat3/action`, so an action without one does not compile.
+  `X_POLICY_MISSING` / `policyMissing()` stay published for a declaration site that cannot
+  say it in a type (a config-driven route table, a policy resolved by name). Never default
+  to allow.
+- `can()` validates its permission at declaration time, not at request time.
+- **`not()` never inverts `X_UNAUTHENTICATED`.** A null actor is not a fact about this
+  actor's grants; inverting it makes `not(can('order:internal'))` a public door into the
+  internal one. Any denial carrying that code propagates unchanged.
+- **`defineRoles()` merges** and refuses a role two modules define differently
+  (`X_ROLE_REDEFINED`, naming both declaration sites). A re-declaration of an *identical*
+  role is a no-op, which is what keeps `defineRoles({ ...roleDefinitions(), … })` legal.
+- No `any`. Never throw a bare `Error` — use `errors.ts`.
+- **This package owns `X_FORBIDDEN`** and registers its title with core. `http`, `auth`
+  and every surface adapter reuse the code and must not re-register it.
+
+## The one authz rule — and the one honest exception
+
+Actions, queries, jobs, MCP tools **and routes** all resolve their rule through `evaluate()`.
+There is no second door. `@ultimat3/auth`'s `requireRole()` / `requireScope()` were one until
+1.3.0 — they asserted on the ambient actor and never evaluated a policy, and a route gated that
+way was invisible to `x policy list`, to `framework.manifest.json` and to `openapi.json`. They
+are deleted: in the repo's whole history, and in both tracked apps, **nothing ever called them**,
+so the framework shipped a documented invitation to an under-reported route and nobody accepted
+it. `packages/auth/src/guards.test.ts` pins that module's export list, so an authz decision
+reappearing there is a failing test.
+
+## Files
+
+| File | Job |
+|---|---|
+| `policy.ts` | `can`/`allow`/`deny`/`and`/`or`/`not` + decision recording |
+| `evaluate.ts` | the single entry point; builds the trace, emits the one decision event |
+| `decisions.ts` | the `DecisionSink` seam — no-op default, one call site, never PII |
+| `surfaces.ts` | http/live/job/mcp adapters — the "one system" proof |
+| `roles.ts` | the role map: merge, conflict, inheritance, wildcards |
+| `grant-index.ts` | the per-actor flattened grant set, memoised against the role generation |
+| `test-kit.ts` | `policyMatrix()` for generated policy tests |
+
+## The hot path
+
+A live query evaluates policy **per subscriber on every change event** — one write to a channel
+with 10k watchers is 10k evaluations in one tick. Two consequences, both load-bearing:
+
+- `grant-index.ts` memoises the flattened grant set on a `WeakMap<Actor, …>`, invalidated by
+  `roleMapGeneration()` — the same shape `@ultimat3/entity`'s `relationMap()` uses against
+  `registryGeneration()`. Keyed on the actor **object**, never on its id: `@ultimat3/auth`
+  re-reads the user row every request and mints a fresh frozen actor, so a revoked role still
+  takes effect on the next request and the entry dies with it. **Never cache an actor, or a
+  grant set, across requests** — that is the stale-authz window the framework does not have.
+- The trace is opt-in: on outside production, and in production only once a `DecisionSink` is
+  installed. `evaluate(policy, args, { trace: true })` forces it — `policyMatrix()` does,
+  because `deciding` *is* the matrix.
+
+## Commands
+
+```
+bun test packages/policy
+bun run --filter @ultimat3/policy typecheck
+```

package/README.md

@@ -12,6 +12,15 @@ export const publishPost = action({
 });
 ```
 
+**No exception, as of 1.3.0.** `@ultimat3/auth`'s `requireRole()` / `requireScope()` used to gate
+*routes* on the ambient actor without evaluating a policy; they are deleted. They were documented
+here as "one honest exception" and had **zero callers** in the framework or in either tracked app —
+a sanctioned second door nobody walked through, whose own documentation admitted that a route
+gated that way is invisible to `x policy list`, to `framework.manifest.json` and to `openapi.json`.
+Gate a route with a `Policy`: `can('admin:access')`, which every introspection surface can read.
+`requireActor()` and `currentActor()` remain — those assert *authentication*, which is what
+`@ultimat3/auth` produces.
+
 ## Shape
 
 A policy is a pure `(input, actor, row, ctx) => PolicyDecision`.
@@ -63,7 +72,17 @@ missing row to `null`. A surface that has no row passes `{ input, actor, ctx }`
 | `allow()` / `deny(reason)` | terminal; `allow()` is how "public" is said out loud |
 | `and(...)` | first denial wins, its reason is the reason |
 | `or(...)` | first allowance wins; otherwise the last denial is reported |
-| `not(p)` | inverts |
+| `not(p)` | inverts — except `X_UNAUTHENTICATED`, which propagates unchanged |
+
+`not()` never turns "there is no actor" into an allow. `can()` denies a null actor with
+`X_UNAUTHENTICATED`, and inverting that would make `not(can('order:internal'))` — the natural
+simplification of `and(can('order:read'), not(can('order:internal')))` — a public door into the
+internal one.
+
+`policy.permissions` (or `policyPermissions(policy)`) is the flattened, deduped, sorted list of
+every permission a tree references, `not()` clauses included. It is what a compliance report has
+to read: `label` renders a composite as `and(post:publish, org:administer)`, which is a sentence,
+never a permission.
 
 ## Four surfaces, four adapters, one rule
 
@@ -87,6 +106,15 @@ Adding a fifth surface means adding an adapter here **and nothing else**.
 `defineRoles({ owner: { grants: ['post:delete'], inherits: ['editor'] } })` expands
 depth-first to a flat set, cycles included. `post:*` and `*` are supported.
 
+`defineRoles()` **merges** into the app's one role map. A second call in a new feature folder
+adds roles; it never deletes the first module's. A role two modules define *differently* is
+`X_ROLE_REDEFINED`, naming both declaration sites — and an identical re-declaration is a no-op,
+so `defineRoles({ ...roleDefinitions(), … })` stays legal.
+
+The flattened grant set is memoised per actor and invalidated the moment the role map changes.
+It is keyed on the actor object, so it lives exactly as long as the request does: `@ultimat3/auth`
+re-reads the user row every request, and a revoked role takes effect on the next one.
+
 ## Traces
 
 `evaluate()` returns a depth-first trace naming the clause that decided. `/_x` renders
@@ -99,10 +127,34 @@ editor  deny   post:read predicate returned false
 viewer  deny   actor lacks post:publish
 ```
 
+Building it is opt-in: on outside production, and in production only once a decision sink is
+installed. A live query evaluates policy per subscriber on every change event, so an unread
+`TraceEntry[]` per evaluation is real allocation on the busiest path there is. Force it with
+`evaluate(policy, args, { trace: true })`.
+
+## The decision log
+
+```ts
+setDecisionSink({
+  record(event) {
+    // { label, allowed, code, reason, actorId, actorKind, orgId, surface, deciding }
+  },
+});
+```
+
+No-op until installed, emitted from **one place** — inside `evaluate()`, so a fifth surface
+inherits it — and it records the **allow** as well as the denial, which is the half an access
+review actually asks for. It never carries `row` or `input`: `reason` is safe to log by
+construction, and the sink inherits that guarantee. A sink that throws is logged and swallowed;
+it never turns an allowed request into a 500.
+
 ## Errors
 
-`X_FORBIDDEN` · `X_POLICY_MISSING` (an action with no policy is a **build** error, not
-a public endpoint) · `X_PERMISSION_UNKNOWN`
+`X_FORBIDDEN` · `X_POLICY_MISSING` · `X_PERMISSION_UNKNOWN` · `X_ROLE_REDEFINED`
+
+A missing policy is a **type** error, not a throw: `ActionDef.policy` is required, so an action
+without one does not compile. `policyMissing()` stays for a declaration site that cannot say it
+in a type — a config-driven route table, a policy resolved by name.
 
 ## Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "The one authz rule, evaluated identically in every surface",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/decisions.ts

@@ -0,0 +1,90 @@
+// The authz decision log's one seam. Shaped exactly like core's `ErrorReporter`: always on, a
+// no-op by default, the wire format supplied by a sink and never here. It exists because the
+// question after an incident is "who did this, and which rule let them?" — and until now an
+// allowed decision left no trace at all, on any of the four surfaces.
+//
+// PII rule, inherited and not negotiable: an event carries the label, the clause and the actor's
+// identifiers. Never `row`, never `input`. `reason` is already safe to log by construction
+// (policy/CLAUDE.md) and this is the guarantee that keeps it that way.
+import { logger, renderThrowable } from '@ultimat3/core';
+import type { Surface } from './surfaces';
+
+export interface PolicyDecisionEvent {
+  /** The policy's own label — `and(post:publish, org:administer)`. Safe to log. */
+  readonly label: string;
+  readonly allowed: boolean;
+  /** `null` on an allow: there is no code for "yes". */
+  readonly code: string | null;
+  readonly reason: string | null;
+  readonly actorId: string | null;
+  readonly actorKind: string | null;
+  readonly orgId: string | null;
+  /** `null` when the evaluation did not come through a surface adapter. */
+  readonly surface: Surface | null;
+  /** The clause that decided, by label. `null` when the trace was off. */
+  readonly deciding: string | null;
+}
+
+/** The driver seam. A SIEM exporter, an append-only table or a log line all arrive as one. */
+export interface DecisionSink {
+  record(event: PolicyDecisionEvent): void;
+}
+
+export const noopDecisionSink: DecisionSink = Object.freeze({
+  record(): void {
+    // Intentionally empty: an app that logs no decisions pays one property read per evaluation.
+  },
+});
+
+let sink: DecisionSink | undefined;
+
+export const setDecisionSink = (next: DecisionSink): void => {
+  sink = next;
+};
+
+/** Test seam, and the only way back to "unconfigured" — which a literal cannot express. */
+export const resetDecisionSink = (): void => {
+  sink = undefined;
+};
+
+/**
+ * Read by `evaluate()` before it builds an event, and by the trace default: a sink is the one
+ * reason to keep building a trace in production.
+ */
+export const decisionSinkInstalled = (): boolean => sink !== undefined;
+
+/**
+ * Called from exactly ONE place — inside `evaluate()`, so a fifth surface inherits the log the
+ * day it is added rather than the day someone remembers to wire it. Never throws: a sink that is
+ * down must not turn an allowed request into a 500.
+ */
+export const emitDecision = (event: PolicyDecisionEvent): void => {
+  if (sink === undefined) return;
+  try {
+    sink.record(event);
+  } catch (failure) {
+    logger.warn('policy decision sink failed', {
+      label: event.label,
+      error: renderThrowable(failure),
+    });
+  }
+};
+
+export interface MemoryDecisionSink extends DecisionSink {
+  readonly events: readonly PolicyDecisionEvent[];
+  reset(): void;
+}
+
+/** For tests, and for a `x dev` process that shows its own authz decisions without leaving the box. */
+export const memoryDecisionSink = (): MemoryDecisionSink => {
+  const events: PolicyDecisionEvent[] = [];
+  return {
+    events,
+    record(event: PolicyDecisionEvent): void {
+      events.push(event);
+    },
+    reset(): void {
+      events.length = 0;
+    },
+  };
+};

package/src/errors.ts

@@ -1,12 +1,15 @@
-// The policy layer's stable error codes. `X_POLICY_MISSING` is deliberately a build
-// error rather than a runtime default: an action with no policy is not "public", it
-// is unfinished.
+// The policy layer's stable error codes. `X_POLICY_MISSING` is enforced by the TYPE system,
+// not by a throw: `ActionDef.policy` is a required field (`@ultimat3/action`'s `action.ts`), so
+// an action with no policy never compiles. The code and its factory stay published for a
+// declaration site that cannot express the requirement in a type — a config-driven route table,
+// a policy resolved by name — and `policyMissing()` is how such a site says it.
 import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 
 export const POLICY_ERROR_CODES = [
   'X_FORBIDDEN',
   'X_POLICY_MISSING',
   'X_PERMISSION_UNKNOWN',
+  'X_ROLE_REDEFINED',
 ] as const;
 
 export type PolicyErrorCode = (typeof POLICY_ERROR_CODES)[number];
@@ -15,6 +18,7 @@ export const POLICY_ERROR_TITLES: Readonly<Record<PolicyErrorCode, string>> = {
   X_FORBIDDEN: 'policy denied this actor',
   X_POLICY_MISSING: 'an action was declared without a policy',
   X_PERMISSION_UNKNOWN: 'permission string is not in the permission set',
+  X_ROLE_REDEFINED: 'two modules define the same role differently',
 };
 
 // This package OWNS X_FORBIDDEN — http, auth, ai, realtime and every other surface adapter throw
@@ -53,6 +57,17 @@ export const policyMissing = (subject: string): PolicyError =>
     fix: `add policy: can('<resource>:<verb>') to ${subject}, or allow('public') to say so explicitly`,
   });
 
+/**
+ * Both declaration sites are named because the fix is always "one of these two wins", and which
+ * two is the only thing the author does not already know.
+ */
+export const roleRedefined = (role: string, first: string, second: string): PolicyError =>
+  new PolicyError({
+    code: 'X_ROLE_REDEFINED',
+    cause: `role "${role}" is defined twice with different grants — first at ${first}, again at ${second}`,
+    fix: `x policy list --json   # then keep ONE definition of "${role}": rename the second, or fold its grants into the first`,
+  });
+
 export const permissionUnknown = (permission: string, known: readonly string[]): PolicyError =>
   new PolicyError({
     code: 'X_PERMISSION_UNKNOWN',

package/src/evaluate.ts

@@ -1,9 +1,13 @@
 // One entry point for evaluating a policy, and the only place a decision trace is
 // built. The trace is what makes an authz denial debuggable: `/_x` renders it, policy
 // tests assert on it, and an agent reading a 403 can see which clause decided.
-import type { Ctx } from '@ultimat3/core';
+// It is also the one place a decision reaches the `DecisionSink` — allowed decisions
+// included, since "who was let in" is the half an audit actually needs.
+import { type Ctx, DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { decisionSinkInstalled, emitDecision } from './decisions';
 import type { Policy, PolicyDecision, TraceEntry } from './policy';
 import type { Actor } from './roles';
+import type { Surface } from './surfaces';
 
 /**
  * What a *caller* supplies. `row` is optional here and required in `PolicyArgs`: a surface
@@ -18,21 +22,52 @@ export interface EvaluateArgs<I, R = unknown> {
   readonly ctx?: Ctx;
 }
 
+export interface EvaluateOptions {
+  /**
+   * Build the trace. Defaults to on outside production, and to on in production only once a
+   * `DecisionSink` is installed — a `TraceEntry[]` per evaluation is real allocation on the
+   * live-query path, where one write fans out to one evaluation per subscriber.
+   */
+  readonly trace?: boolean | undefined;
+  /** Which adapter asked. Carried to the sink; the decision itself never depends on it. */
+  readonly surface?: Surface | undefined;
+}
+
 export interface PolicyEvaluation {
   readonly allowed: boolean;
   readonly decision: PolicyDecision;
-  /** Depth-first, in evaluation order. Empty only for a policy that never ran. */
+  /** Depth-first, in evaluation order. Empty for a policy that never ran, or a trace turned off. */
   readonly trace: readonly TraceEntry[];
-  /** The clause whose result the caller is looking at. */
+  /** The clause whose result the caller is looking at. `null` when the trace is off. */
   readonly deciding: TraceEntry | null;
   readonly label: string;
 }
 
+let outsideProduction: boolean | undefined;
+
+/**
+ * Resolved once and cached: `ULTIMATE_ENV` cannot change under a running process, and reading
+ * `process.env` per evaluation is exactly the per-subscriber cost this change exists to remove.
+ * Non-throwing on purpose — a malformed `ULTIMATE_ENV` is its own error with its own fix, and it
+ * must never be raised for the first time by an authz check.
+ */
+const traceByDefault = (): boolean => {
+  outsideProduction ??= (tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT) !== 'production';
+  return outsideProduction || decisionSinkInstalled();
+};
+
+/** Test seam: re-reads the environment on the next evaluation. */
+export const resetPolicyTracing = (): void => {
+  outsideProduction = undefined;
+};
+
 export const evaluate = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
+  options?: EvaluateOptions,
 ): PolicyEvaluation => {
   const trace: TraceEntry[] = [];
+  const wanted = options?.trace ?? traceByDefault();
   const decision = policy.run(
     {
       input: args.input,
@@ -43,7 +78,8 @@ export const evaluate = <I, R = unknown>(
       row: args.row ?? null,
       ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
     },
-    (entry) => trace.push(entry),
+    // No recorder at all when the trace is off, so not even the closure is allocated.
+    wanted ? (entry) => trace.push(entry) : undefined,
   );
   // Entries are recorded post-order (children before their combinator), so the first
   // entry that agrees with the outcome is the leaf that actually decided — and when a
@@ -55,6 +91,19 @@ export const evaluate = <I, R = unknown>(
     ) ??
     trace.find(agrees) ??
     null;
+  if (decisionSinkInstalled()) {
+    emitDecision({
+      label: policy.label,
+      allowed: decision.allowed,
+      code: decision.allowed ? null : decision.code,
+      reason: decision.allowed ? null : decision.reason,
+      actorId: args.actor?.id ?? null,
+      actorKind: args.actor?.kind ?? null,
+      orgId: args.actor?.orgId ?? null,
+      surface: options?.surface ?? null,
+      deciding: deciding?.label ?? null,
+    });
+  }
   return {
     allowed: decision.allowed,
     decision,

package/src/grant-index.ts

@@ -0,0 +1,79 @@
+// One flattened grant set per actor, memoised for as long as the role map it was built from
+// stays put. Why it earns a file: a live query evaluates policy PER SUBSCRIBER on every change
+// event, and every `can()` clause asks this question — so an unmemoised expansion turned one
+// write on a channel with 10k subscribers into 10k role-graph walks in a single tick.
+import { type Permission, resourceOf } from './permissions';
+import { type Actor, expandRoles, type RoleMap, roleDefinitions, roleMapGeneration } from './roles';
+
+/**
+ * The three shapes `grantMatches()` can take, pre-split so a lookup is a `Set.has` instead of a
+ * scan: an exact grant, a `<resource>:*` wildcard, and the bare `*`. Equivalent to
+ * `actorPermissions(actor).some((grant) => grantMatches(grant, permission))`, per grant kind.
+ */
+interface GrantIndex {
+  readonly exact: ReadonlySet<string>;
+  /** Resources covered by a `<resource>:*` grant. */
+  readonly wildcards: ReadonlySet<string>;
+  readonly all: boolean;
+  /** Deduped and sorted, built once so `actorPermissions()` never sorts per clause. */
+  readonly sorted: readonly string[];
+}
+
+interface CacheEntry {
+  readonly map: RoleMap;
+  readonly generation: number;
+  readonly index: GrantIndex;
+}
+
+/**
+ * Keyed on the actor OBJECT, never on its id: `@ultimat3/auth` mints a fresh, frozen actor per
+ * request from a freshly-read user row, so the entry dies with the request and a revoked role
+ * still takes effect on the very next one. Caching by id — or across requests — would trade that
+ * property for the same allocations.
+ */
+const cache = new WeakMap<Actor, CacheEntry>();
+
+const buildIndex = (actor: Actor, map: RoleMap): GrantIndex => {
+  const exact = new Set<string>(actor.permissions ?? []);
+  for (const grant of expandRoles(actor.roles ?? [], map)) exact.add(grant);
+  const wildcards = new Set<string>();
+  let all = false;
+  for (const grant of exact) {
+    if (grant === '*') all = true;
+    else if (grant.endsWith(':*')) wildcards.add(resourceOf(grant));
+  }
+  return { exact, wildcards, all, sorted: [...exact].sort() };
+};
+
+const indexFor = (actor: Actor, map: RoleMap): GrantIndex => {
+  const generation = roleMapGeneration();
+  const hit = cache.get(actor);
+  // The map is compared by reference as well as by generation, because both `actorHas()` and
+  // `actorPermissions()` take an explicit map override that the generation counter never sees.
+  if (hit !== undefined && hit.map === map && hit.generation === generation) return hit.index;
+  const index = buildIndex(actor, map);
+  cache.set(actor, { map, generation, index });
+  return index;
+};
+
+/**
+ * A COPY, per call. `readonly string[]` is compile-time only, so handing back `index.sorted` —
+ * which is the per-actor authz cache itself — let any caller `push` a grant into it through a
+ * widened reference and hold it for the life of that request. The list is small (an actor's own
+ * grants) and this is not on `actorHas`'s path, which reads the `Set` and copies nothing.
+ */
+export const actorPermissions = (
+  actor: Actor | null,
+  map: RoleMap = roleDefinitions(),
+): readonly string[] => (actor === null ? [] : [...indexFor(actor, map).sorted]);
+
+export const actorHas = (
+  actor: Actor | null,
+  permission: Permission,
+  map: RoleMap = roleDefinitions(),
+): boolean => {
+  if (actor === null) return false;
+  const index = indexFor(actor, map);
+  if (index.all || index.exact.has(permission)) return true;
+  return index.wildcards.has(resourceOf(permission));
+};

package/src/index.ts

@@ -1,7 +1,14 @@
+// The public surface of @ultimat3/policy. Explicit, never `export *`.
+export type { DecisionSink, MemoryDecisionSink, PolicyDecisionEvent } from './decisions';
+export {
+  decisionSinkInstalled,
+  memoryDecisionSink,
+  noopDecisionSink,
+  resetDecisionSink,
+  setDecisionSink,
+} from './decisions';
 export type { DefinePolicyInput } from './define';
 export { definePolicy } from './define';
-// The public surface of @ultimat3/policy. Explicit, never `export *`.
-
 export type { PolicyErrorCode } from './errors';
 export {
   forbidden,
@@ -10,9 +17,18 @@ export {
   PolicyError,
   permissionUnknown,
   policyMissing,
+  roleRedefined,
 } from './errors';
-export type { EvaluateArgs, PolicyEvaluation } from './evaluate';
-export { codeOf, evaluate, explain, reasonOf, renderTrace } from './evaluate';
+export type { EvaluateArgs, EvaluateOptions, PolicyEvaluation } from './evaluate';
+export {
+  codeOf,
+  evaluate,
+  explain,
+  reasonOf,
+  renderTrace,
+  resetPolicyTracing,
+} from './evaluate';
+export { actorHas, actorPermissions } from './grant-index';
 export type {
   KnownPermission,
   Permission,
@@ -37,16 +53,26 @@ export type {
   Recorder,
   TraceEntry,
 } from './policy';
-export { ALLOWED, allow, and, can, denied, deny, not, or } from './policy';
+export {
+  ALLOWED,
+  allow,
+  and,
+  can,
+  denied,
+  deny,
+  not,
+  or,
+  policyPermissions,
+} from './policy';
 export type { Actor, PolicyActorFields, RoleDef, RoleMap } from './roles';
 export {
-  actorHas,
-  actorPermissions,
   clearRoles,
   defineRoles,
   expandRoles,
   grantMatches,
+  roleDeclarationSites,
   roleDefinitions,
+  roleMapGeneration,
   rolesGranting,
 } from './roles';
 export type {

package/src/policy.ts

@@ -2,8 +2,9 @@
 // object be evaluated in an HTTP request, a job, a live query and an MCP tool without
 // any of them re-implementing the rule — one authz system, never two.
 import type { Ctx } from '@ultimat3/core';
+import { actorHas } from './grant-index';
 import { assertPermission, type KnownPermission, type Permission } from './permissions';
-import { type Actor, actorHas } from './roles';
+import type { Actor } from './roles';
 
 export type PolicyDecision =
   | { readonly allowed: true }
@@ -141,6 +142,22 @@ export const deny = <I = unknown, R = unknown>(
   },
 });
 
+/**
+ * Every permission a policy tree references, deduped and sorted. This is the list a compliance
+ * report has to read: `label` renders a composite as `and(post:publish, org:administer)`, which
+ * is a sentence, not a permission — matching a grant against it reports every non-trivial rule's
+ * permissions as unenforced.
+ *
+ * A `not()` clause contributes its inner permissions too. The grant still decides the outcome,
+ * so "nothing references this permission" would be the false statement, not this one.
+ */
+export const policyPermissions = <I = unknown, R = unknown>(
+  policy: Policy<I, R>,
+): readonly Permission[] => policy.permissions;
+
+const flatten = (children: readonly { readonly permissions: readonly Permission[] }[]) =>
+  [...new Set(children.flatMap((child) => child.permissions))].sort();
+
 // Combinators hand `args` to every child untouched — `row` included. A clause that rewrote
 // the args would be the second authz shape all over again.
 const combined = <I, R>(
@@ -151,7 +168,7 @@ const combined = <I, R>(
 ): Policy<I, R> => ({
   kind,
   label,
-  permissions: children.flatMap((child) => child.permissions),
+  permissions: flatten(children),
   children,
   run(args, recorder, depth = 0) {
     return record(recorder, this, depth, decide(args, recorder, depth + 1));
@@ -190,8 +207,19 @@ export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy
     },
   );
 
+/**
+ * Inverts a decision about an actor's grants — and only that.
+ *
+ * `X_UNAUTHENTICATED` is propagated, never inverted. "There is no actor" is not a fact about
+ * this actor's permissions, so flipping it makes `not(can('order:internal'))` read as *allow
+ * everyone who is not internal, anonymous callers first*. That is how a "public unless internal"
+ * route becomes a public internal route: the mistake is invisible in `and(can(…), not(can(…)))`
+ * because the first clause carries the authentication, and it ships the moment someone simplifies.
+ */
 export const not = <I, R = unknown>(policy: Policy<I, R>): Policy<I, R> =>
   combined('not', `not(${policy.label})`, [policy], (args, recorder, depth) => {
     const decision = policy.run(args, recorder, depth);
-    return decision.allowed ? denied(`not(${policy.label}) — inner clause allowed`) : ALLOWED;
+    if (decision.allowed) return denied(`not(${policy.label}) — inner clause allowed`);
+    if (decision.code === 'X_UNAUTHENTICATED') return decision;
+    return ALLOWED;
   });

package/src/roles.ts

@@ -1,8 +1,10 @@
 // Roles are sugar over permissions: a role grants a set, and may inherit others.
 // Everything is expanded to a flat permission set before any policy runs, so the
 // evaluator never has to reason about hierarchy — and a cycle is caught here, once.
+// The per-actor flattening and its memo live in `grant-index.ts`; this file owns the map.
 import type { Actor as CoreActor } from '@ultimat3/core';
-import { type Permission, resourceOf } from './permissions';
+import { roleRedefined } from './errors';
+import { resourceOf } from './permissions';
 
 /**
  * The fields policy evaluation reads off an actor. `Actor` itself is core's; these
@@ -27,17 +29,81 @@ export interface RoleDef {
 export type RoleMap = Readonly<Record<string, RoleDef>>;
 
 let roleMap: RoleMap = {};
+let sites: Readonly<Record<string, string>> = {};
+let generation = 0;
 
+/**
+ * Bumped by every write to the map. `grant-index.ts` memoises a flattened grant set against
+ * it, the same shape `@ultimat3/entity`'s `relationMap()` uses against `registryGeneration()`:
+ * a memo that cannot be invalidated by a later `defineRoles()` is a stale-authz bug.
+ */
+export const roleMapGeneration = (): number => generation;
+
+/** Frames inside this file — never the answer to "who declared this role?". */
+const INTERNAL_FRAME = /declarationSite|defineRoles/;
+
+const declarationSite = (): string => {
+  // Not a throw: the stack is the only place the declaring module's name exists at this point,
+  // and `X_ROLE_REDEFINED` is unactionable without both sides of the collision.
+  const stack = new Error().stack;
+  if (stack === undefined) return 'unknown site';
+  const frames = stack.split('\n').slice(1);
+  const frame = frames.find((line) => !INTERNAL_FRAME.test(line)) ?? frames[0] ?? '';
+  return frame.trim() === '' ? 'unknown site' : frame.trim();
+};
+
+const sameList = (left: readonly string[], right: readonly string[]): boolean => {
+  if (left.length !== right.length) return false;
+  const sortedRight = [...right].sort();
+  return [...left].sort().every((value, index) => value === sortedRight[index]);
+};
+
+/**
+ * A re-declaration of an identical role is a no-op, not a collision. That is what keeps the
+ * `defineRoles({ ...roleDefinitions(), … })` spelling both tracked apps already use legal:
+ * the spread hands every earlier role straight back.
+ */
+const sameDefinition = (left: RoleDef, right: RoleDef): boolean =>
+  left === right ||
+  (left.description === right.description &&
+    sameList(left.grants, right.grants) &&
+    sameList(left.inherits ?? [], right.inherits ?? []));
+
+/**
+ * MERGES into the app's one role map, and refuses a role two modules define differently.
+ *
+ * It used to replace, which made the map import-order-dependent: a second `defineRoles()` in a
+ * new feature folder silently deleted the first module's roles, every `can()` still typechecked,
+ * and every request 403'd on whichever bundler ordering CI happened to pick.
+ */
 export const defineRoles = <const M extends RoleMap>(map: M): M => {
-  roleMap = map;
+  const site = declarationSite();
+  const merged: Record<string, RoleDef> = { ...roleMap };
+  const nextSites: Record<string, string> = { ...sites };
+  for (const [role, definition] of Object.entries(map)) {
+    const existing = merged[role];
+    if (existing !== undefined && !sameDefinition(existing, definition)) {
+      throw roleRedefined(role, sites[role] ?? 'unknown site', site);
+    }
+    merged[role] = definition;
+    nextSites[role] = nextSites[role] ?? site;
+  }
+  roleMap = merged;
+  sites = nextSites;
+  generation += 1;
   return map;
 };
 
 export const roleDefinitions = (): RoleMap => roleMap;
 
+/** Where each role was first declared. Read by `X_ROLE_REDEFINED`, and by nothing else. */
+export const roleDeclarationSites = (): Readonly<Record<string, string>> => sites;
+
 /** Test seam. */
 export const clearRoles = (): void => {
   roleMap = {};
+  sites = {};
+  generation += 1;
 };
 
 /**
@@ -69,22 +135,6 @@ export const grantMatches = (grant: string, wanted: string): boolean => {
   return false;
 };
 
-export const actorPermissions = (
-  actor: Actor | null,
-  map: RoleMap = roleMap,
-): readonly string[] => {
-  if (actor === null) return [];
-  const direct = actor.permissions ?? [];
-  const fromRoles = expandRoles(actor.roles ?? [], map);
-  return [...new Set([...direct, ...fromRoles])].sort();
-};
-
-export const actorHas = (
-  actor: Actor | null,
-  permission: Permission,
-  map: RoleMap = roleMap,
-): boolean => actorPermissions(actor, map).some((grant) => grantMatches(grant, permission));
-
 /** For the `/_x` dashboard: which roles would satisfy a permission. */
 export const rolesGranting = (permission: string, map: RoleMap = roleMap): readonly string[] =>
   Object.keys(map)

package/src/surfaces.ts

@@ -3,6 +3,9 @@
 // allowed. Adding a fifth surface means adding an adapter HERE and nothing else — no
 // new policy model, no second authz path, no per-surface exceptions.
 //
+// An adapter names its surface and does nothing else with it: the decision log is emitted
+// inside `evaluate()`, so the fifth adapter inherits it instead of having to remember it.
+//
 // The shapes are declared structurally rather than imported: `@ultimat3/http` is a
 // sibling tier, and jobs/realtime/mcp are higher tiers that import this package.
 
@@ -55,7 +58,7 @@ export const enforceHttp = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): HttpDenial | undefined => {
-  const evaluation = evaluate(policy, args);
+  const evaluation = evaluate(policy, args, { surface: 'http' });
   if (evaluation.allowed) return undefined;
   return {
     surface: 'http',
@@ -73,7 +76,7 @@ export const enforceLive = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): LiveDenial | undefined => {
-  const evaluation = evaluate(policy, args);
+  const evaluation = evaluate(policy, args, { surface: 'live' });
   if (evaluation.allowed) return undefined;
   return { surface: 'live', close: 4403, code: code(evaluation), reason: reason(evaluation) };
 };
@@ -82,7 +85,7 @@ export const enforceJob = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): JobDenial | undefined => {
-  const evaluation = evaluate(policy, args);
+  const evaluation = evaluate(policy, args, { surface: 'job' });
   if (evaluation.allowed) return undefined;
   return {
     surface: 'job',
@@ -97,7 +100,7 @@ export const enforceMcp = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): McpDenial | undefined => {
-  const evaluation = evaluate(policy, args);
+  const evaluation = evaluate(policy, args, { surface: 'mcp' });
   if (evaluation.allowed) return undefined;
   return {
     surface: 'mcp',

package/src/test-kit.ts

@@ -39,12 +39,18 @@ export const policyMatrix = <I, R = unknown>(
   const rows = args.actors.map((entry): MatrixRow => {
     // Every field but the actor is forwarded verbatim: a matrix that dropped `row` would
     // report a row rule as denying everyone, and the table would lie.
-    const evaluation = evaluate(policy, {
-      input: args.input,
-      actor: entry.actor,
-      ...(args.row === undefined ? {} : { row: args.row }),
-      ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
-    });
+    const evaluation = evaluate(
+      policy,
+      {
+        input: args.input,
+        actor: entry.actor,
+        ...(args.row === undefined ? {} : { row: args.row }),
+        ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
+      },
+      // The `deciding` column IS the matrix; a production default that skips the trace would
+      // blank it, and `x policy explain` renders this table.
+      { trace: true },
+    );
     return {
       actor: entry.name,
       allowed: evaluation.allowed,