@ultimat3/policy 13.0.0 → 14.0.0

package/CLAUDE.md

@@ -73,9 +73,29 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   process — so a clear in one test file is permanent for every file after it, whose own `import` is a
   cache hit that declares nothing. `restoreRoles` takes the declaration sites too: `defineRoles()` derives
   them from the CALLER's stack, so restoring through it would make `X_ROLE_REDEFINED` name the harness.
-- **`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.
+- **`and()` and `or()` REFUSE an empty clause list** (`X_POLICY_CLAUSE_EMPTY`, `As of 2026-08-25`),
+  at the call that builds them. An empty `and()` found nothing to deny and answered ALLOWED, so
+  `and(...requiredCaps.map(can))` over a list that filtered to nothing — a config-driven or
+  per-tenant rule table — admitted an **anonymous** caller on all four surfaces, with `meta.auth`
+  deriving from `admitsAnonymous` so `@ultimat3/http` did not 401 first either, and no diagnostic:
+  the label renders as `and()`. `allow('public')` is the explicit spelling, so refusing costs a
+  caller nothing they cannot say another way. `or()` is refused for symmetry and for axiom 1 rather
+  than for safety — it fails closed, but with "no clause allowed this actor", a reason naming no
+  clause; `deny('<reason>')` carries one. Refused where it is WRITTEN, the same call
+  `@ultimat3/scraping`'s `allowHosts: []` and `discriminated-union.ts`'s unroutable member make.
+- **`not()` never inverts `X_UNAUTHENTICATED`, and `or()` is what makes that true of a TREE**
+  (`As of 2026-08-25`). 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 — but the rule held only while `not`'s DIRECT child was a `can()`:
+  `not(or(can('order:internal'), deny('read-only mode')))` **allowed `actor: null`**, because `or`
+  reported the LAST denial and `deny`'s `X_FORBIDDEN` overwrote the code `not()` had to recognise.
+  So `or` now reports a denial carrying `X_UNAUTHENTICATED` over a later one that does not, and
+  `policy-anonymous.ts`'s `or` walk mirrors it. **`and` needs no such rule** — it short-circuits, so
+  the denial it reports IS the deciding one. The other candidate repair, `not()` re-reading
+  `args.actor === null` itself, was refused: it would deny an anonymous caller under `not(deny(…))`,
+  which this file and `policy-anonymous.ts` both document as ALLOWED, and it states the wrong rule —
+  `not` inverts a decision about grants, and whether one was made without an actor is `or`'s to
+  report.
 - **`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.
@@ -112,6 +132,12 @@ two differ, and it is why a surface that decides on input alone needs no edit.
 - 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.
+- **Every owned code is classified `terminal`, and every one is LISTED** (`As of 2026-08-25`).
+  `classifyThrown` reads an unregistered code carrying `terminal` as UNCLASSIFIED, so the attempt
+  count governs and a job spends its whole retry policy re-proving a denial — the cost
+  `@ultimat3/jobs`' webhook block is written up against. Core's own `ErrorRetry` doc names "a
+  permission denial" as the canonical `terminal` case and `X_FORBIDDEN` was not classified at all.
+  `errors.test.ts` pins the whole list, so a new code with no classification is a failing test.
 
 ## The one authz rule — and the one honest exception
 

package/README.md

@@ -70,14 +70,24 @@ missing row to `null`. A surface that has no row passes `{ input, actor, ctx }`
 |---|---|
 | `can(p, predicate?)` | permission first, then the row-level predicate |
 | `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 |
+| `and(...)` | first denial wins, its reason is the reason; **no clauses is `X_POLICY_CLAUSE_EMPTY`** |
+| `or(...)` | first allowance wins; otherwise the last denial — except one carrying `X_UNAUTHENTICATED`, which outranks a later one. **No clauses is `X_POLICY_CLAUSE_EMPTY`** |
 | `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.
+internal one. `or()` is what makes that true of a whole TREE rather than only of `not`'s direct
+child: it used to report the LAST denial, so `not(or(can('order:internal'), deny('read-only mode')))`
+**allowed an anonymous caller** — `deny`'s `X_FORBIDDEN` had overwritten the code `not()` had to
+recognise.
+
+`and()` and `or()` refuse an empty clause list at the call that builds them. Nobody writes `and()`;
+they write `and(...requiredCaps.map(can))` over a config-driven list that filters to nothing — and
+an empty `and()` found nothing to deny and **allowed everyone, anonymous callers included**, on all
+four surfaces, with no diagnostic beyond a label reading `and()`. `allow('public')` and
+`deny('<reason>')` are the explicit spellings, so the refusal costs you nothing you cannot say
+another way.
 
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "The one authz rule, evaluated identically in every surface",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "13.0.0"
+    "@ultimat3/core": "14.0.0"
   }
 }

package/src/errors.ts

@@ -3,12 +3,20 @@
 // 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 { nearestName, registerErrorCodes, renderCauseValue, UltimateError } from '@ultimat3/core';
+import {
+  type ErrorRetry,
+  nearestName,
+  registerErrorCodes,
+  registerErrorRetry,
+  renderCauseValue,
+  UltimateError,
+} from '@ultimat3/core';
 
 export const POLICY_ERROR_CODES = [
   'X_FORBIDDEN',
   'X_POLICY_MISSING',
   'X_PERMISSION_UNKNOWN',
+  'X_POLICY_CLAUSE_EMPTY',
   'X_POLICY_SURFACE_UNKNOWN',
   'X_ROLE_REDEFINED',
 ] as const;
@@ -19,6 +27,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_POLICY_CLAUSE_EMPTY: 'a policy combinator was built with no clauses',
   X_POLICY_SURFACE_UNKNOWN: 'enforce() was handed a surface no adapter answers to',
   X_ROLE_REDEFINED: 'two modules define the same role differently',
 };
@@ -31,6 +40,38 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(POLICY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
+/**
+ * Every one of them, LISTED rather than left to the `terminal` default — the call
+ * `@ultimat3/jobs`' webhook block already makes, and for its reason: `classifyThrown` reads an
+ * unregistered code carrying `terminal` as UNCLASSIFIED, so the attempt count governs and a job
+ * spends its whole retry policy re-proving an answer no attempt can change.
+ *
+ * `X_FORBIDDEN` is the one that matters, and core's own `ErrorRetry` doc comment names its case
+ * verbatim — *"the same call will fail the same way forever (a config fault, a validation error, a
+ * permission denial)"*. The same actor, the same input and the same row decide the same way on
+ * attempt five; the four declaration faults beside it cannot change between attempts at all,
+ * because each is raised while a module is still evaluating.
+ *
+ * Registered here rather than by the surfaces that THROW `X_FORBIDDEN` (http, auth, ai, realtime)
+ * for the reason the title is: this package owns the code, and a second package registering a
+ * different classification for it is a conflict `registerErrorRetry` raises rather than absorbs.
+ *
+ * Written out key by key over a CLOSED `Record<PolicyErrorCode, …>` rather than derived from
+ * `POLICY_ERROR_CODES` with a `.map`: a derivation classifies a new code by accident, and the one
+ * question worth asking of a code is whether trying it again could ever answer differently. A code
+ * added above with no row here is a missing-key TYPE error, which is the enforcement.
+ */
+const POLICY_ERROR_RETRY = Object.freeze<Record<PolicyErrorCode, ErrorRetry>>({
+  X_FORBIDDEN: 'terminal',
+  X_POLICY_MISSING: 'terminal',
+  X_PERMISSION_UNKNOWN: 'terminal',
+  X_POLICY_CLAUSE_EMPTY: 'terminal',
+  X_POLICY_SURFACE_UNKNOWN: 'terminal',
+  X_ROLE_REDEFINED: 'terminal',
+});
+
+registerErrorRetry(POLICY_ERROR_RETRY);
+
 export class PolicyError extends UltimateError {
   override readonly name = 'PolicyError';
 
@@ -107,6 +148,38 @@ export const permissionUnknown = (permission: string, known: readonly string[]):
   });
 };
 
+/**
+ * A combinator built with no clauses, refused where it is WRITTEN — the call
+ * `@ultimat3/scraping`'s `allowHosts: []` and `discriminated-union.ts`'s unroutable member both
+ * already make: a declaration that is wrong for every input is wrong at its first import, not at
+ * the request that discovers it.
+ *
+ * `and()` is the dangerous half and the reason this code exists. With no clauses its loop finds
+ * nothing to deny and answers ALLOWED, so `and(...requiredCaps.map(can))` over a list that
+ * filtered to empty is a policy admitting an ANONYMOUS caller on all four surfaces — and
+ * `meta.auth` derives from `admitsAnonymous`, so `@ultimat3/http` does not 401 first either. There
+ * was no diagnostic to follow: the label renders as `and()`.
+ *
+ * `or()` is refused for symmetry and for axiom 1, not for safety: it denies, which fails closed,
+ * but it denies with "no clause allowed this actor" — a reason naming no clause, which is a denial
+ * nobody can debug. `deny('<reason>')` is the spelling that says the same thing WITH one.
+ *
+ * Both fixes name the explicit spelling, so refusing costs a caller nothing they cannot say
+ * another way.
+ */
+export const emptyClauseList = (combinator: 'and' | 'or'): PolicyError =>
+  new PolicyError({
+    code: 'X_POLICY_CLAUSE_EMPTY',
+    cause:
+      combinator === 'and'
+        ? 'and() was built with no clauses, so it allows every actor — anonymous callers included — on every surface'
+        : 'or() was built with no clauses, so it denies every actor and names no clause that could have allowed one',
+    fix:
+      combinator === 'and'
+        ? "write allow('public') if every caller may act — otherwise pass the clauses the list was meant to hold: and(can('<resource>:<verb>'), …)"
+        : "write deny('<why nobody may act>') if nobody may act — otherwise pass the clauses the list was meant to hold: or(can('<resource>:<verb>'), …)",
+  });
+
 /**
  * `enforce()` was handed a surface with no adapter. Thrown rather than denied, because the value
  * this reports on is one an index would have resolved to something: every object literal inherits

package/src/index.ts

@@ -11,6 +11,7 @@ export type { DefinePolicyInput } from './define';
 export { definePolicy } from './define';
 export type { PolicyErrorCode } from './errors';
 export {
+  emptyClauseList,
   forbidden,
   POLICY_ERROR_CODES,
   POLICY_ERROR_TITLES,

package/src/policy-anonymous.ts

@@ -58,14 +58,20 @@ const OUTCOME_BY_KIND = Object.freeze<Record<PolicyKind, (policy: PolicyTree) =>
       }
       return 'allowed';
     },
-    // First allowance wins; if none allow, `or` reports the LAST denial.
+    // First allowance wins; if none allow, `or` reports the LAST denial — except that a clause
+    // denying for want of an actor outranks one that does not, which is `or`'s own rule in
+    // `policy.ts` and the reason `not()` can recognise an `X_UNAUTHENTICATED` raised deeper than
+    // its direct child. Both halves were wrong here identically, so the agreement test between
+    // this walk and `policy.run` stayed green over the shape neither got right.
     or: (policy) => {
       let last: AnonymousOutcome = 'denied';
+      let unauthenticated = false;
       for (const child of policy.children) {
         last = anonymousOutcome(child);
         if (last === 'allowed') return 'allowed';
+        if (last === 'unauthenticated') unauthenticated = true;
       }
-      return last;
+      return unauthenticated ? 'unauthenticated' : last;
     },
     not: (policy) => {
       const inner = policy.children[0];

package/src/policy.ts

@@ -2,6 +2,7 @@
 // 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 { emptyClauseList } from './errors';
 import { actorHas } from './grant-index';
 import { assertPermission, type KnownPermission, type Permission } from './permissions';
 import type { Actor } from './roles';
@@ -175,9 +176,18 @@ const combined = <I, R>(
   },
 });
 
-/** First denial wins, and its reason is the reason — short-circuit, left to right. */
-export const and = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> =>
-  combined(
+/**
+ * First denial wins, and its reason is the reason — short-circuit, left to right.
+ *
+ * An EMPTY clause list is refused here rather than answered: the loop below finds nothing to deny
+ * and returns ALLOWED, so `and(...requiredCaps.map(can))` over a list that filtered to nothing is
+ * a policy that admits an anonymous caller on every surface. `allow('public')` is how that is said
+ * on purpose. The rest parameter stays a rest parameter — a required first argument would make the
+ * spread that produces this bug a type error AND make every legitimate spread one too.
+ */
+export const and = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> => {
+  if (policies.length === 0) throw emptyClauseList('and');
+  return combined(
     'and',
     `and(${policies.map((policy) => policy.label).join(', ')})`,
     policies,
@@ -189,23 +199,44 @@ export const and = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Polic
       return ALLOWED;
     },
   );
+};
 
-/** First allowance wins; if none allow, the LAST denial is reported. */
-export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> =>
-  combined(
+/**
+ * First allowance wins; if none allow, the LAST denial is reported — **except** that a denial
+ * carrying `X_UNAUTHENTICATED` outranks one that does not.
+ *
+ * That exception is what makes `not()`'s rule below true of a TREE rather than only of a direct
+ * `can()` child. `not(or(can('order:internal'), deny('read-only mode')))` allowed `actor: null`:
+ * the `can` clause raised `X_UNAUTHENTICATED`, `deny`'s `X_FORBIDDEN` overwrote it as the last
+ * denial, and `not()` had nothing left to recognise, so it inverted a decision that was made
+ * because there was no actor. It is also the more accurate code on its own terms — a clause that
+ * could not be decided without an actor makes "authenticate and retry" a real instruction, which
+ * a 403 is not.
+ *
+ * `and` needs no such rule: it short-circuits, so the denial it reports IS the deciding one and
+ * every clause after it went unevaluated.
+ *
+ * An empty clause list is refused for the reason `and`'s is — see `emptyClauseList`.
+ */
+export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> => {
+  if (policies.length === 0) throw emptyClauseList('or');
+  return combined(
     'or',
     `or(${policies.map((policy) => policy.label).join(', ')})`,
     policies,
     (args, recorder, depth) => {
       let last: PolicyDecision = denied('no clause allowed this actor');
+      let unauthenticated: PolicyDecision | undefined;
       for (const policy of policies) {
         const decision = policy.run(args, recorder, depth);
         if (decision.allowed) return ALLOWED;
+        if (decision.code === 'X_UNAUTHENTICATED') unauthenticated = decision;
         last = decision;
       }
-      return last;
+      return unauthenticated ?? last;
     },
   );
+};
 
 /**
  * Inverts a decision about an actor's grants — and only that.