@ultimat3/policy 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -51,12 +51,47 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   everything while nothing is declared, so the first declaration anywhere in the process turns
   strict checking on for everyone. A test that uses `can()` declares the set it uses and restores
   the one it found — never leans on the empty registry.
+- **`clearPermissions()` / `clearRoles()` are one-way; `restorePermissions()` / `restoreRoles()` are the
+  other halves.** Both declaration calls run at MODULE scope, and a module evaluates once per `bun test`
+  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.
 - **`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.
+- **A role name is ACTOR data, so the role map is read with `Object.hasOwn` and written with
+  `defineProperty`** (`roles.ts`, `As of 2026-08`). An app's map is a plain object literal, so
+  `map['constructor']` answered the `Object` FUNCTION, the `definition === undefined` guard passed,
+  and `for (const grant of definition.grants)` threw a bare `TypeError` out of `evaluate` — which
+  `@ultimat3/http` re-raises to the error boundary, so an actor holding a role named `constructor`,
+  `__proto__` or `toString` turned every authz decision it made into a **500 instead of a 403**.
+  `map[name] = value` is the same hazard writing: for `__proto__` it runs `Object.prototype`'s
+  setter and files no key at all. `test-kit.ts`'s verdict map has the same two rules for the same
+  reason — `allowedFor('constructor')` answered a truthy function — and `policyMatrix` builds it
+  through `Object.fromEntries`, which defines own keys whatever they spell.
+- **`Actor` is an ALIAS of core's, and `PolicyActorFields` is deleted** (`As of 2026-08-19`).
+  It was `CoreActor & PolicyActorFields`, a four-field interface declared here. Three fields
+  (`id`, `roles`, `orgId`) were already core's, so the intersection only restated them, and
+  `PolicyActorFields.orgId`'s `| null` never survived it — it was intersected straight back to
+  core's `string | undefined`. The fourth, `permissions`, was the only real content, and declaring
+  it here is what made it **unbuildable**: core is tier 0 and cannot import this package, so
+  `build()` had no field to carry and `userActor({ permissions })` compiled and discarded the
+  argument. Every caller worked around it with `{ ...userActor({ id }), permissions: [...] }` — a
+  spread over a frozen actor, producing an unfrozen one — so **32 fixtures across `query`,
+  `action` and a tracked app proved authz against a shape no request mints**. `@ultimat3/auth`
+  kept a second, hand-synced copy of the same interface for the same tier reason. `permissions`
+  now sits beside `roles` and `scopes` in `@ultimat3/core`.
+- **`testActor()` goes through `userActor()`** (`As of 2026-08-19`), so it is frozen with frozen
+  arrays and a field added to `Actor` arrives here without a second list to keep in sync. It used
+  to hand-roll the literal — it had to, since core's builder had no `permissions` — and omitted
+  `kind` and `scopes` behind an `as unknown as Actor`, so `hasScope(actor, …)` threw a bare
+  `TypeError` on every actor it built and `actorLabel()` rendered `undefined:editor`: a generated
+  scope-gated policy test failed as a 500-shaped throw instead of as the denial it asserts. The one
+  cast left is `orgId: null` — core declares `orgId?: string`, so nothing typed can mint the
+  `null` that `@ultimat3/query`'s `orgless()` guards against, and that test needs a producer.
 - 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.
@@ -82,7 +117,7 @@ reappearing there is a failing test.
 | `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 |
+| `test-kit.ts` | `policyMatrix()` for generated policy tests, and `testActor()` |
 
 ## The hot path
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "3.0.0",
+  "version": "4.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": "3.0.0"
+    "@ultimat3/core": "4.0.0"
   }
 }

package/src/grant-index.ts

@@ -34,6 +34,9 @@ interface CacheEntry {
 const cache = new WeakMap<Actor, CacheEntry>();
 
 const buildIndex = (actor: Actor, map: RoleMap): GrantIndex => {
+  // `?? []` on both, though `Actor` declares them required and `userActor()` defaults them: this
+  // takes an `Actor | null` from surfaces that hand it a value parsed out of JSON, and an authz
+  // read that throws where it should have DENIED is the `testActor` defect one layer down.
   const exact = new Set<string>(actor.permissions ?? []);
   for (const grant of expandRoles(actor.roles ?? [], map)) exact.add(grant);
   const wildcards = new Set<string>();

package/src/index.ts

@@ -42,6 +42,7 @@ export {
   isKnownPermission,
   knownPermissions,
   resourceOf,
+  restorePermissions,
   verbOf,
 } from './permissions';
 export type {
@@ -64,12 +65,13 @@ export {
   or,
   policyPermissions,
 } from './policy';
-export type { Actor, PolicyActorFields, RoleDef, RoleMap } from './roles';
+export type { Actor, RoleDef, RoleMap } from './roles';
 export {
   clearRoles,
   defineRoles,
   expandRoles,
   grantMatches,
+  restoreRoles,
   roleDeclarationSites,
   roleDefinitions,
   roleMapGeneration,

package/src/permissions.ts

@@ -75,3 +75,18 @@ export const definePermissions = <const P extends readonly Permission[]>(
 
 /** Test seam; production never forgets a permission it declared. */
 export const clearPermissions = (): void => declared.clear();
+
+/**
+ * `clearPermissions()`'s other half, taking exactly what `knownPermissions()` answers.
+ *
+ * `definePermissions()` runs at MODULE scope — `@ultimat3/admin` declares `admin:*` on its
+ * barrel's import — and a module evaluates once per `bun test` process. So a clear in one test
+ * file is permanent for every file after it: that file's own `import` is a cache hit which
+ * registers nothing, and `can('admin:read')` throws X_PERMISSION_UNKNOWN for a permission the
+ * process really did declare. Only putting the captured set back repairs it; re-importing cannot.
+ * Replaces rather than merges — a capture is the whole truth about the process, not an addition.
+ */
+export const restorePermissions = (permissions: readonly string[]): void => {
+  declared.clear();
+  for (const permission of permissions) declared.add(permission);
+};

package/src/roles.ts

@@ -7,18 +7,21 @@ import { roleRedefined } from './errors';
 import { resourceOf } from './permissions';
 
 /**
- * The fields policy evaluation reads off an actor. `Actor` itself is core's; these
- * are authz roles ("editor", "owner"), not core's runtime `Role` ("web", "worker").
+ * An **alias** of core's declaration, and nothing more (`As of 2026-08-19`) — so the actor
+ * `userActor()` mints IS the actor a predicate decides about, with no spread and no second type.
+ *
+ * It used to be `CoreActor & PolicyActorFields`, a four-field interface declared here. Three of
+ * those fields (`id`, `roles`, `orgId`) were already core's, so the intersection restated them;
+ * `PolicyActorFields.orgId`'s `| null` never survived it at all, being intersected back to core's
+ * `string | undefined`. The fourth, `permissions`, was the only real content — and declaring THAT
+ * here is what made it unbuildable: core is tier 0, so `userActor({ permissions })` had no field
+ * to land in and dropped the argument in silence. It now lives beside `roles` and `scopes` in
+ * `@ultimat3/core`, where every actor is built, and this interface has nothing left to say.
+ *
+ * Same shape as `@ultimat3/entity`'s `MoneyValue`, aliased from `@ultimat3/schema` for the same
+ * reason: one declaration, re-exported by the package whose public API talks about it.
  */
-export interface PolicyActorFields {
-  readonly id: string;
-  readonly roles?: readonly string[] | undefined;
-  /** Direct grants, bypassing roles. Used by service tokens. */
-  readonly permissions?: readonly string[] | undefined;
-  readonly orgId?: string | null | undefined;
-}
-
-export type Actor = CoreActor & PolicyActorFields;
+export type Actor = CoreActor;
 
 export interface RoleDef {
   readonly grants: readonly string[];
@@ -52,6 +55,26 @@ const declarationSite = (): string => {
   return frame.trim() === '' ? 'unknown site' : frame.trim();
 };
 
+/**
+ * A role name is caller data, and an app's role map is a plain object literal — so `map['constructor']`
+ * answers the `Object` FUNCTION rather than `undefined`, the `=== undefined` guard at the call site
+ * never fires, and reading `.grants` off it throws a bare `TypeError` from inside `evaluate`. That is
+ * an authz decision arriving at the error boundary as a 500 instead of a 403, for every request an
+ * actor holding a role named `constructor`, `__proto__` or `toString` makes. Same discriminator
+ * `@ultimat3/entity`'s `tenancy.ts` uses, for the same reason.
+ */
+const own = <V>(map: Readonly<Record<string, V>>, name: string): V | undefined =>
+  Object.hasOwn(map, name) ? map[name] : undefined;
+
+/**
+ * `map[name] = value` is the same hazard writing: for `name === '__proto__'` it runs the setter on
+ * `Object.prototype` and stores NO key, so the role would vanish between being merged and being
+ * read back. `defineProperty` files an own key whatever the name spells.
+ */
+const put = <V>(map: Record<string, V>, name: string, value: V): void => {
+  Object.defineProperty(map, name, { value, writable: true, enumerable: true, configurable: true });
+};
+
 const sameList = (left: readonly string[], right: readonly string[]): boolean => {
   if (left.length !== right.length) return false;
   const sortedRight = [...right].sort();
@@ -81,12 +104,12 @@ export const defineRoles = <const M extends RoleMap>(map: M): M => {
   const merged: Record<string, RoleDef> = { ...roleMap };
   const nextSites: Record<string, string> = { ...sites };
   for (const [role, definition] of Object.entries(map)) {
-    const existing = merged[role];
+    const existing = own(merged, role);
     if (existing !== undefined && !sameDefinition(existing, definition)) {
-      throw roleRedefined(role, sites[role] ?? 'unknown site', site);
+      throw roleRedefined(role, own(sites, role) ?? 'unknown site', site);
     }
-    merged[role] = definition;
-    nextSites[role] = nextSites[role] ?? site;
+    put(merged, role, definition);
+    put(nextSites, role, own(nextSites, role) ?? site);
   }
   roleMap = merged;
   sites = nextSites;
@@ -106,6 +129,23 @@ export const clearRoles = (): void => {
   generation += 1;
 };
 
+/**
+ * `clearRoles()`'s other half, taking what `roleDefinitions()` and `roleDeclarationSites()`
+ * answer. `defineRoles()` runs at an app's MODULE scope and a module evaluates once per
+ * `bun test` process, so a clear in one test file is permanent for every file after it — the
+ * later file's `import` is a cache hit that declares nothing.
+ *
+ * `defineRoles()` cannot be the restore: it re-derives the declaration site from the CALLER's
+ * stack, so every role would report this frame as its origin and `X_ROLE_REDEFINED` would name a
+ * site no reader can open. The generation is bumped for `grant-index.ts`, whose per-actor memo is
+ * invalidated by that number alone.
+ */
+export const restoreRoles = (map: RoleMap, declaredAt: Readonly<Record<string, string>>): void => {
+  roleMap = { ...map };
+  sites = { ...declaredAt };
+  generation += 1;
+};
+
 /**
  * Depth-first expansion with a visited set: `owner -> admin -> editor` collapses to
  * one list, and `a -> b -> a` terminates instead of blowing the stack.
@@ -119,7 +159,7 @@ export const expandRoles = (
   const walk = (name: string): void => {
     if (seen.has(name)) return;
     seen.add(name);
-    const definition = map[name];
+    const definition = own(map, name);
     if (definition === undefined) return;
     for (const grant of definition.grants) out.add(grant);
     for (const parent of definition.inherits ?? []) walk(parent);

package/src/test-kit.ts

@@ -1,6 +1,7 @@
 // `policyMatrix()` turns "who can do this?" into a table a test can assert on in one
 // expression. `x g policy` generates a test that calls it, so every policy ships with
 // its allow/deny matrix and a change to a role shows up as a diff in that table.
+import { userActor } from '@ultimat3/core';
 import { type EvaluateArgs, evaluate, reasonOf } from './evaluate';
 import type { Policy } from './policy';
 import type { Actor } from './roles';
@@ -59,15 +60,21 @@ export const policyMatrix = <I, R = unknown>(
     };
   });
 
-  const verdicts: Record<string, boolean> = {};
-  for (const row of rows) verdicts[row.actor] = row.allowed;
+  // `Object.fromEntries` rather than `verdicts[row.actor] = …`: an actor named `__proto__` assigns
+  // the PROTOTYPE through that spelling and files no key at all, so the matrix would report a
+  // verdict it never stored. Every name here is an own key.
+  const verdicts: Record<string, boolean> = Object.fromEntries(
+    rows.map((row) => [row.actor, row.allowed]),
+  );
 
   const width = Math.max(5, ...rows.map((row) => row.actor.length));
   return {
     label: policy.label,
     rows,
     verdicts,
-    allowedFor: (name) => verdicts[name] ?? false,
+    // `verdicts[name] ?? false` answered the `Object` FUNCTION — truthy, and not a boolean — for
+    // `allowedFor('constructor')`, so a matrix asserting on an actor of that name read as allow.
+    allowedFor: (name) => (Object.hasOwn(verdicts, name) ? verdicts[name] === true : false),
     toTable: () =>
       rows
         .map((row) =>
@@ -77,16 +84,39 @@ export const policyMatrix = <I, R = unknown>(
   };
 };
 
-/** Builds an actor for tests without asserting anything about core's Actor shape. */
+/**
+ * Builds a test actor through `userActor()` — core's own builder, and now the only one, since
+ * `permissions` moved to core's `Actor` (`As of 2026-08-19`).
+ *
+ * This function hand-rolled the object literal because it had to: a direct grant was declared on
+ * policy's `PolicyActorFields` and core's builder had no field for it. That is what made every
+ * actor it minted structurally different from a request's — it omitted `kind` and `scopes` behind
+ * an `as unknown as Actor`, so `hasScope()` threw a bare `TypeError` and `actorLabel()` rendered
+ * `undefined:editor` into logs and spans, and a generated policy test (`x g policy`) asserting a
+ * scope-gated denial failed as a 500-shaped throw rather than as the denial it wrote.
+ *
+ * Going through `userActor()` closes that by construction rather than by keeping a second field
+ * list in sync: a field added to `Actor` arrives here, and the result is FROZEN with frozen
+ * arrays, exactly as the actor `@ultimat3/auth` resolves per request is.
+ */
 export const testActor = (
   name: string,
-  init: { roles?: readonly string[]; permissions?: readonly string[]; orgId?: string } = {},
-): NamedActor => ({
-  name,
-  actor: {
+  init: {
+    roles?: readonly string[];
+    permissions?: readonly string[];
+    scopes?: readonly string[];
+    orgId?: string;
+  } = {},
+): NamedActor => {
+  const built = userActor({
     id: name,
     roles: init.roles ?? [],
+    scopes: init.scopes ?? [],
     permissions: init.permissions ?? [],
-    orgId: init.orgId ?? null,
-  } as unknown as Actor,
-});
+  });
+  // `orgId: null` is deliberate and load-bearing, and the ONE cast left. Core declares
+  // `orgId?: string | undefined`, so nothing typed can mint the `null` an app's own adapter still
+  // puts on the wire — and `@ultimat3/query`'s `orgless()` treats `null`, `undefined` and `''`
+  // alike precisely because it does reach there. Frozen, so this stays a production-shaped actor.
+  return { name, actor: Object.freeze({ ...built, orgId: init.orgId ?? null }) as Actor };
+};