@ultimat3/policy 25.0.0 → 25.1.0

package/CLAUDE.md

@@ -111,6 +111,10 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   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.
+- **A wildcard grant reaches its PREFIX, never its first segment**: `grantMatches` and the grant
+  index both ask core's `grantCovers` (`auth` cuts API keys with it too — same tier, so the one
+  copy lives in core). `billing:invoice:*` never grants `billing:refund:issue`
+  (`grant-wildcard.test.ts`). `resourceOf` is for grouping (`byResource`), never for coverage.
 - **`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.

package/README.md

@@ -151,7 +151,9 @@ dispatch failed **closed with a `SurfaceDenial` no caller could read**.
 `PermissionRegistry` (which `x g policy` generates) makes a typo a compile error, and
 `can()` throws `X_PERMISSION_UNKNOWN` at declaration time either way. Roles are sugar:
 `defineRoles({ owner: { grants: ['post:delete'], inherits: ['editor'] } })` expands
-depth-first to a flat set, cycles included. `post:*` and `*` are supported.
+depth-first to a flat set, cycles included. `post:*` and `*` are supported. A wildcard reaches
+its PREFIX and nothing beside it: `billing:invoice:*` grants `billing:invoice:read`, never
+`billing:refund:issue` (`@ultimat3/core`'s `grantCovers`, the one reading `auth` shares).
 
 `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

package/package.json

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

package/src/grant-index.ts

@@ -2,18 +2,23 @@
 // 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 { grantCovers } from '@ultimat3/core';
+import type { Permission } 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
+ * scan: an exact grant, a `<prefix>:*` 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>;
+  /**
+   * The `<prefix>:*` grants themselves, asked through core's `grantCovers` — a list, not a set of
+   * resources: keyed by the first segment, `billing:invoice:*` answered for `billing:refund:issue`.
+   * An actor holds a handful, so the scan is a few `startsWith`.
+   */
+  readonly wildcards: readonly string[];
   readonly all: boolean;
   /** Deduped and sorted, built once so `actorPermissions()` never sorts per clause. */
   readonly sorted: readonly string[];
@@ -39,11 +44,11 @@ const buildIndex = (actor: Actor, map: RoleMap): GrantIndex => {
   // 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>();
+  const wildcards: string[] = [];
   let all = false;
   for (const grant of exact) {
     if (grant === '*') all = true;
-    else if (grant.endsWith(':*')) wildcards.add(resourceOf(grant));
+    else if (grant.endsWith(':*')) wildcards.push(grant);
   }
   return { exact, wildcards, all, sorted: [...exact].sort() };
 };
@@ -78,5 +83,5 @@ export const actorHas = (
   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));
+  return index.wildcards.some((grant) => grantCovers(grant, permission));
 };

package/src/roles.ts

@@ -3,9 +3,9 @@
 // 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 { grantCovers } from '@ultimat3/core';
 import { callerSite, UNKNOWN_SITE } from './declaration-site';
 import { roleRedefined } from './errors';
-import { resourceOf } from './permissions';
 
 /**
  * An **alias** of core's declaration, and nothing more (`As of 2026-08-19`) — so the actor
@@ -156,12 +156,12 @@ export const expandRoles = (
   return [...out].sort();
 };
 
-/** `post:*` matches every verb on `post`; `*` matches everything. */
-export const grantMatches = (grant: string, wanted: string): boolean => {
-  if (grant === '*' || grant === wanted) return true;
-  if (grant.endsWith(':*')) return resourceOf(grant) === resourceOf(wanted);
-  return false;
-};
+/**
+ * `post:*` matches every name under `post:`; `billing:invoice:*` only those under
+ * `billing:invoice:`; `*` matches everything. Core's `grantCovers` is the one reading — `auth`
+ * cuts an API key to its owner with it too, and the two may not share a copy at tier 2.
+ */
+export const grantMatches = (grant: string, wanted: string): boolean => grantCovers(grant, wanted);
 
 /** For the `/_x` dashboard: which roles would satisfy a permission. */
 export const rolesGranting = (permission: string, map: RoleMap = roleMap): readonly string[] =>