@ultimat3/policy 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# @ultimat3/policy 🔐
+
+**One authz system.** Two authz systems — one for HTTP, one for "the API", one for
+jobs — is how every Meteor-shaped framework died: the surfaces drift, one of them is
+wrong, and nobody finds out until it is a CVE. This package exists so a second one is
+never necessary. Every MCP tool, live query, job and route resolves the *same* policy
+object through the *same* `evaluate()`.
+
+```ts
+export const publishPost = action({
+  policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId)),
+});
+```
+
+## Shape
+
+A policy is a pure `(input, actor, ctx) => PolicyDecision`.
+
+```ts
+type PolicyDecision =
+  | { allowed: true }
+  | { allowed: false; reason: string; code: string };
+```
+
+`reason` is always **safe to log** (it names permissions, never row data) and useful
+to an agent: `actor lacks post:publish` and `post:publish predicate returned false`
+are different problems with different fixes.
+
+## Combinators
+
+| Builder | Behaviour |
+|---|---|
+| `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 |
+| `not(p)` | inverts |
+
+## Four surfaces, four adapters, one rule
+
+`surfaces.ts` is the proof. Each adapter evaluates and maps a denial to that surface's
+error shape; allowed returns `undefined`.
+
+| Adapter | Denial shape |
+|---|---|
+| `enforceHttp` | `403` + RFC-9457 fields |
+| `enforceLive` | close frame `4403` |
+| `enforceJob` | `failed`, `retryable: false` — the answer will not change on retry |
+| `enforceMcp` | `isError: true` with readable text |
+
+Adding a fifth surface means adding an adapter here **and nothing else**.
+
+## Permissions and roles
+
+`definePermissions(['post:publish', ...])` gives a typed set; augmenting
+`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.
+
+## Traces
+
+`evaluate()` returns a depth-first trace naming the clause that decided. `/_x` renders
+it, `explain()` logs one line, and `policyMatrix()` turns actors × policy into an
+assert-ready table:
+
+```
+owner   allow
+editor  deny   post:read predicate returned false
+viewer  deny   actor lacks post:publish
+```
+
+## Errors
+
+`X_FORBIDDEN` · `X_POLICY_MISSING` (an action with no policy is a **build** error, not
+a public endpoint) · `X_PERMISSION_UNKNOWN`
+
+## Boundaries
+
+Tier 2. Imports `@ultimat3/core` only. Surface error shapes are declared structurally
+so this package never imports `@ultimat3/http` (sibling tier) or the tier-3/4 surfaces
+that import it.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/policy",
+  "version": "0.0.1",
+  "description": "The one authz rule, evaluated identically in every surface",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/policy"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "^0.0.1"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,52 @@
+// 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.
+import { UltimateError } from '@ultimat3/core';
+
+export const POLICY_ERROR_CODES = [
+  'X_FORBIDDEN',
+  'X_POLICY_MISSING',
+  'X_PERMISSION_UNKNOWN',
+] as const;
+
+export type PolicyErrorCode = (typeof POLICY_ERROR_CODES)[number];
+
+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',
+};
+
+export class PolicyError extends UltimateError {
+  constructor(init: { code: PolicyErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+    this.name = 'PolicyError';
+  }
+}
+
+/** `reason` comes from a decision and is always safe to log: no row data, no PII. */
+export const forbidden = (label: string, reason: string): PolicyError =>
+  new PolicyError({
+    code: 'X_FORBIDDEN',
+    cause: `${label} denied: ${reason}`,
+    fix: `x policy explain ${label} --json   # shows which clause decided and why`,
+  });
+
+export const policyMissing = (subject: string): PolicyError =>
+  new PolicyError({
+    code: 'X_POLICY_MISSING',
+    cause: `${subject} has no policy; an action without a policy is a build error, not a public endpoint`,
+    fix: `add policy: can('<resource>:<verb>') to ${subject}, or allow('public') to say so explicitly`,
+  });
+
+export const permissionUnknown = (permission: string, known: readonly string[]): PolicyError =>
+  new PolicyError({
+    code: 'X_PERMISSION_UNKNOWN',
+    cause: `"${permission}" is not in the permission set (${known.length} known)`,
+    fix: `add '${permission}' to definePermissions([...]) — or fix the typo`,
+  });

package/src/evaluate.ts

@@ -0,0 +1,74 @@
+// 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';
+import type { Policy, PolicyDecision, TraceEntry } from './policy';
+import type { Actor } from './roles';
+
+export interface EvaluateArgs<I> {
+  readonly input: I;
+  readonly actor: Actor | null;
+  readonly ctx?: Ctx;
+}
+
+export interface PolicyEvaluation {
+  readonly allowed: boolean;
+  readonly decision: PolicyDecision;
+  /** Depth-first, in evaluation order. Empty only for a policy that never ran. */
+  readonly trace: readonly TraceEntry[];
+  /** The clause whose result the caller is looking at. */
+  readonly deciding: TraceEntry | null;
+  readonly label: string;
+}
+
+export const evaluate = <I>(policy: Policy<I>, args: EvaluateArgs<I>): PolicyEvaluation => {
+  const trace: TraceEntry[] = [];
+  const decision = policy.run(
+    {
+      input: args.input,
+      actor: args.actor,
+      ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
+    },
+    (entry) => trace.push(entry),
+  );
+  // 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
+  // reason is available it is matched too, which disambiguates `or(...)`.
+  const agrees = (entry: TraceEntry): boolean => entry.allowed === decision.allowed;
+  const deciding =
+    trace.find(
+      (entry) => agrees(entry) && (decision.allowed || entry.reason === decision.reason),
+    ) ??
+    trace.find(agrees) ??
+    null;
+  return {
+    allowed: decision.allowed,
+    decision,
+    trace,
+    deciding,
+    label: policy.label,
+  };
+};
+
+export const reasonOf = (decision: PolicyDecision): string | null =>
+  decision.allowed ? null : decision.reason;
+
+export const codeOf = (decision: PolicyDecision): string | null =>
+  decision.allowed ? null : decision.code;
+
+/** `post:publish -> denied: actor lacks post:publish` — one line, safe to log. */
+export const explain = (evaluation: PolicyEvaluation): string => {
+  const outcome = evaluation.allowed ? 'allowed' : `denied: ${reasonOf(evaluation.decision)}`;
+  const by = evaluation.deciding === null ? '' : ` (by ${evaluation.deciding.label})`;
+  return `${evaluation.label} -> ${outcome}${by}`;
+};
+
+/** Indented tree for the dev dashboard; one line per clause. */
+export const renderTrace = (evaluation: PolicyEvaluation): string =>
+  evaluation.trace
+    .map((entry) => {
+      const mark = entry.allowed ? 'allow' : 'deny ';
+      const why = entry.reason === null ? '' : ` — ${entry.reason}`;
+      return `${'  '.repeat(entry.depth)}${mark} ${entry.label}${why}`;
+    })
+    .join('\n');

package/src/index.ts

@@ -0,0 +1,67 @@
+// The public surface of @ultimat3/policy. Explicit, never `export *`.
+
+export type { PolicyErrorCode } from './errors';
+export {
+  forbidden,
+  POLICY_ERROR_CODES,
+  POLICY_ERROR_TITLES,
+  PolicyError,
+  permissionUnknown,
+  policyMissing,
+} from './errors';
+export type { EvaluateArgs, PolicyEvaluation } from './evaluate';
+export { codeOf, evaluate, explain, reasonOf, renderTrace } from './evaluate';
+export type {
+  KnownPermission,
+  Permission,
+  PermissionRegistry,
+  PermissionSet,
+} from './permissions';
+export {
+  assertPermission,
+  clearPermissions,
+  definePermissions,
+  isKnownPermission,
+  knownPermissions,
+  resourceOf,
+  verbOf,
+} from './permissions';
+export type {
+  Policy,
+  PolicyArgs,
+  PolicyDecision,
+  PolicyKind,
+  PolicyPredicate,
+  Recorder,
+  TraceEntry,
+} from './policy';
+export { ALLOWED, allow, and, can, denied, deny, not, or } from './policy';
+export type { Actor, PolicyActorFields, RoleDef, RoleMap } from './roles';
+export {
+  actorHas,
+  actorPermissions,
+  clearRoles,
+  defineRoles,
+  expandRoles,
+  grantMatches,
+  roleDefinitions,
+  rolesGranting,
+} from './roles';
+export type {
+  HttpDenial,
+  JobDenial,
+  LiveDenial,
+  McpDenial,
+  Surface,
+  SurfaceDenial,
+} from './surfaces';
+export {
+  assertAllowed,
+  enforce,
+  enforceHttp,
+  enforceJob,
+  enforceLive,
+  enforceMcp,
+} from './surfaces';
+export type { MatrixArgs, MatrixRow, NamedActor, PolicyMatrix } from './test-kit';
+export { policyMatrix, testActor } from './test-kit';

package/src/permissions.ts

@@ -0,0 +1,77 @@
+// Permissions are `resource:verb` strings. Two layers of protection: the template
+// literal type rejects a malformed string at compile time, and an app that augments
+// `PermissionRegistry` (which `x g policy` does) turns a typo into a type error.
+import { permissionUnknown } from './errors';
+
+export type Permission = `${string}:${string}`;
+
+/**
+ * Augmented by the generated app code:
+ *
+ * ```ts
+ * declare module '@ultimat3/policy' {
+ *   interface PermissionRegistry { 'post:publish': true; 'post:read': true }
+ * }
+ * ```
+ */
+export interface PermissionRegistry {
+  /** Phantom member; never augment or read this key. */
+  readonly __ultimate?: never;
+}
+
+type Declared = Exclude<keyof PermissionRegistry, '__ultimate'>;
+
+/** Every declared permission, or any `resource:verb` string before augmentation. */
+export type KnownPermission = [Declared] extends [never]
+  ? Permission
+  : Extract<Declared, Permission>;
+
+export interface PermissionSet<P extends Permission> {
+  readonly all: readonly P[];
+  has(value: string): value is P;
+  /** Narrows a string to a declared permission, or throws `X_PERMISSION_UNKNOWN`. */
+  assert(value: string): P;
+  byResource(resource: string): readonly P[];
+  resources(): readonly string[];
+}
+
+const declared = new Set<string>();
+
+export const knownPermissions = (): readonly string[] => [...declared].sort();
+
+/**
+ * Runtime membership check. It stays silent until an app has declared its set,
+ * because there is nothing to check against before then — `x verify` is what fails
+ * a build that references a permission no `definePermissions()` call declares.
+ */
+export const isKnownPermission = (value: string): boolean =>
+  declared.size === 0 || declared.has(value);
+
+export const assertPermission = (value: string): string => {
+  if (!isKnownPermission(value)) throw permissionUnknown(value, knownPermissions());
+  return value;
+};
+
+export const resourceOf = (permission: string): string => permission.split(':')[0] ?? permission;
+
+export const verbOf = (permission: string): string => permission.split(':')[1] ?? '';
+
+export const definePermissions = <const P extends readonly Permission[]>(
+  list: P,
+): PermissionSet<P[number]> => {
+  for (const permission of list) declared.add(permission);
+  const all = [...list] as P[number][];
+  return {
+    all,
+    has: (value): value is P[number] => all.includes(value as P[number]),
+    assert: (value) => {
+      if (!all.includes(value as P[number])) throw permissionUnknown(value, all);
+      return value as P[number];
+    },
+    byResource: (resource) => all.filter((permission) => resourceOf(permission) === resource),
+    resources: () => [...new Set(all.map(resourceOf))].sort(),
+  };
+};
+
+/** Test seam; production never forgets a permission it declared. */
+export const clearPermissions = (): void => declared.clear();

package/src/policy.ts

@@ -0,0 +1,175 @@
+// A policy is a pure function of (input, actor, ctx). Purity is what lets the same
+// 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 { assertPermission, type KnownPermission, type Permission } from './permissions';
+import { type Actor, actorHas } from './roles';
+
+export type PolicyDecision =
+  | { readonly allowed: true }
+  | { readonly allowed: false; readonly reason: string; readonly code: string };
+
+export const ALLOWED: PolicyDecision = { allowed: true };
+
+export const denied = (reason: string, code = 'X_FORBIDDEN'): PolicyDecision => ({
+  allowed: false,
+  reason,
+  code,
+});
+
+export interface PolicyArgs<I> {
+  readonly input: I;
+  readonly actor: Actor | null;
+  readonly ctx?: Ctx;
+}
+
+export type PolicyPredicate<I> = (args: PolicyArgs<I>) => boolean | PolicyDecision;
+
+export type PolicyKind = 'permission' | 'allow' | 'deny' | 'and' | 'or' | 'not';
+
+export interface TraceEntry {
+  readonly label: string;
+  readonly kind: PolicyKind;
+  readonly depth: number;
+  readonly allowed: boolean;
+  readonly reason: string | null;
+  readonly code: string | null;
+}
+
+export type Recorder = (entry: TraceEntry) => void;
+
+export interface Policy<I = unknown> {
+  readonly kind: PolicyKind;
+  /** Stable, human-readable, safe to log: shown in traces and denial reasons. */
+  readonly label: string;
+  readonly permissions: readonly Permission[];
+  readonly children: readonly Policy<I>[];
+  run(args: PolicyArgs<I>, record?: Recorder, depth?: number): PolicyDecision;
+}
+
+const record = (
+  recorder: Recorder | undefined,
+  policy: { kind: PolicyKind; label: string },
+  depth: number,
+  decision: PolicyDecision,
+): PolicyDecision => {
+  recorder?.({
+    label: policy.label,
+    kind: policy.kind,
+    depth,
+    allowed: decision.allowed,
+    reason: decision.allowed ? null : decision.reason,
+    code: decision.allowed ? null : decision.code,
+  });
+  return decision;
+};
+
+const asDecision = (result: boolean | PolicyDecision, label: string): PolicyDecision => {
+  if (typeof result === 'boolean') {
+    return result ? ALLOWED : denied(`${label} predicate returned false`);
+  }
+  return result;
+};
+
+/**
+ * The blessed constructor. The permission is checked first and the optional
+ * predicate second, so a denial reason distinguishes "you may never do this" from
+ * "you may, but not to this row" — an agent can act on the difference.
+ */
+export const can = <I = unknown>(
+  permission: KnownPermission,
+  predicate?: PolicyPredicate<I>,
+): Policy<I> => {
+  assertPermission(permission);
+  const label = permission;
+  return {
+    kind: 'permission',
+    label,
+    permissions: [permission as Permission],
+    children: [],
+    run(args, recorder, depth = 0) {
+      if (args.actor === null) {
+        return record(recorder, this, depth, denied(`no actor for ${label}`, 'X_UNAUTHENTICATED'));
+      }
+      if (!actorHas(args.actor, permission as Permission)) {
+        return record(recorder, this, depth, denied(`actor lacks ${label}`));
+      }
+      if (predicate === undefined) return record(recorder, this, depth, ALLOWED);
+      return record(recorder, this, depth, asDecision(predicate(args), label));
+    },
+  };
+};
+
+/** Explicitly public. Saying so is required; forgetting a policy is a build error. */
+export const allow = <I = unknown>(label = 'allow'): Policy<I> => ({
+  kind: 'allow',
+  label,
+  permissions: [],
+  children: [],
+  run(_args, recorder, depth = 0) {
+    return record(recorder, this, depth, ALLOWED);
+  },
+});
+
+export const deny = <I = unknown>(reason: string, code = 'X_FORBIDDEN'): Policy<I> => ({
+  kind: 'deny',
+  label: `deny(${reason})`,
+  permissions: [],
+  children: [],
+  run(_args, recorder, depth = 0) {
+    return record(recorder, this, depth, denied(reason, code));
+  },
+});
+
+const combined = <I>(
+  kind: PolicyKind,
+  label: string,
+  children: readonly Policy<I>[],
+  decide: (args: PolicyArgs<I>, recorder: Recorder | undefined, depth: number) => PolicyDecision,
+): Policy<I> => ({
+  kind,
+  label,
+  permissions: children.flatMap((child) => child.permissions),
+  children,
+  run(args, recorder, depth = 0) {
+    return record(recorder, this, depth, decide(args, recorder, depth + 1));
+  },
+});
+
+/** First denial wins, and its reason is the reason — short-circuit, left to right. */
+export const and = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
+  combined(
+    'and',
+    `and(${policies.map((policy) => policy.label).join(', ')})`,
+    policies,
+    (args, recorder, depth) => {
+      for (const policy of policies) {
+        const decision = policy.run(args, recorder, depth);
+        if (!decision.allowed) return decision;
+      }
+      return ALLOWED;
+    },
+  );
+
+/** First allowance wins; if none allow, the LAST denial is reported. */
+export const or = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
+  combined(
+    'or',
+    `or(${policies.map((policy) => policy.label).join(', ')})`,
+    policies,
+    (args, recorder, depth) => {
+      let last: PolicyDecision = denied('no clause allowed this actor');
+      for (const policy of policies) {
+        const decision = policy.run(args, recorder, depth);
+        if (decision.allowed) return ALLOWED;
+        last = decision;
+      }
+      return last;
+    },
+  );
+
+export const not = <I>(policy: Policy<I>): Policy<I> =>
+  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;
+  });

package/src/roles.ts

@@ -0,0 +1,92 @@
+// 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.
+import type { Actor as CoreActor } from '@ultimat3/core';
+import { type Permission, 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").
+ */
+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 interface RoleDef {
+  readonly grants: readonly string[];
+  readonly inherits?: readonly string[];
+  readonly description?: string;
+}
+
+export type RoleMap = Readonly<Record<string, RoleDef>>;
+
+let roleMap: RoleMap = {};
+
+export const defineRoles = <const M extends RoleMap>(map: M): M => {
+  roleMap = map;
+  return map;
+};
+
+export const roleDefinitions = (): RoleMap => roleMap;
+
+/** Test seam. */
+export const clearRoles = (): void => {
+  roleMap = {};
+};
+
+/**
+ * Depth-first expansion with a visited set: `owner -> admin -> editor` collapses to
+ * one list, and `a -> b -> a` terminates instead of blowing the stack.
+ */
+export const expandRoles = (
+  roles: readonly string[],
+  map: RoleMap = roleMap,
+): readonly string[] => {
+  const seen = new Set<string>();
+  const out = new Set<string>();
+  const walk = (name: string): void => {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const definition = map[name];
+    if (definition === undefined) return;
+    for (const grant of definition.grants) out.add(grant);
+    for (const parent of definition.inherits ?? []) walk(parent);
+  };
+  for (const role of roles) walk(role);
+  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;
+};
+
+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)
+    .filter((role) => expandRoles([role], map).some((grant) => grantMatches(grant, permission)))
+    .sort();

package/src/surfaces.ts

@@ -0,0 +1,127 @@
+// Proof that one policy covers every surface. Each adapter is the same three lines:
+// evaluate, map a denial to that surface's error shape, return `undefined` when
+// 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.
+//
+// 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.
+
+import { forbidden } from './errors';
+import { codeOf, type EvaluateArgs, evaluate, type PolicyEvaluation, reasonOf } from './evaluate';
+import type { Policy } from './policy';
+
+export type Surface = 'http' | 'live' | 'job' | 'mcp';
+
+export interface HttpDenial {
+  readonly surface: 'http';
+  readonly status: 403;
+  /** RFC-9457 fields `@ultimat3/http` renders verbatim. */
+  readonly problem: {
+    readonly title: string;
+    readonly status: 403;
+    readonly detail: string;
+    readonly code: string;
+  };
+}
+
+export interface LiveDenial {
+  readonly surface: 'live';
+  /** WebSocket close code in the private range; the client stops resubscribing. */
+  readonly close: 4403;
+  readonly code: string;
+  readonly reason: string;
+}
+
+export interface JobDenial {
+  readonly surface: 'job';
+  readonly outcome: 'failed';
+  /** Authz denials are never retried: the answer will not change on attempt two. */
+  readonly retryable: false;
+  readonly code: string;
+  readonly reason: string;
+}
+
+export interface McpDenial {
+  readonly surface: 'mcp';
+  readonly isError: true;
+  readonly content: readonly { readonly type: 'text'; readonly text: string }[];
+}
+
+const reason = (evaluation: PolicyEvaluation): string => reasonOf(evaluation.decision) ?? 'denied';
+
+const code = (evaluation: PolicyEvaluation): string => codeOf(evaluation.decision) ?? 'X_FORBIDDEN';
+
+export const enforceHttp = <I>(
+  policy: Policy<I>,
+  args: EvaluateArgs<I>,
+): HttpDenial | undefined => {
+  const evaluation = evaluate(policy, args);
+  if (evaluation.allowed) return undefined;
+  return {
+    surface: 'http',
+    status: 403,
+    problem: {
+      title: 'policy denied this actor',
+      status: 403,
+      detail: reason(evaluation),
+      code: code(evaluation),
+    },
+  };
+};
+
+export const enforceLive = <I>(
+  policy: Policy<I>,
+  args: EvaluateArgs<I>,
+): LiveDenial | undefined => {
+  const evaluation = evaluate(policy, args);
+  if (evaluation.allowed) return undefined;
+  return { surface: 'live', close: 4403, code: code(evaluation), reason: reason(evaluation) };
+};
+
+export const enforceJob = <I>(policy: Policy<I>, args: EvaluateArgs<I>): JobDenial | undefined => {
+  const evaluation = evaluate(policy, args);
+  if (evaluation.allowed) return undefined;
+  return {
+    surface: 'job',
+    outcome: 'failed',
+    retryable: false,
+    code: code(evaluation),
+    reason: reason(evaluation),
+  };
+};
+
+export const enforceMcp = <I>(policy: Policy<I>, args: EvaluateArgs<I>): McpDenial | undefined => {
+  const evaluation = evaluate(policy, args);
+  if (evaluation.allowed) return undefined;
+  return {
+    surface: 'mcp',
+    isError: true,
+    // An MCP client is an agent: the text has to say what was denied and why.
+    content: [{ type: 'text', text: `${code(evaluation)}: ${reason(evaluation)}` }],
+  };
+};
+
+export type SurfaceDenial = HttpDenial | LiveDenial | JobDenial | McpDenial;
+
+type Adapter = <I>(policy: Policy<I>, args: EvaluateArgs<I>) => SurfaceDenial | undefined;
+
+const adapters: Readonly<Record<Surface, Adapter>> = {
+  http: enforceHttp,
+  live: enforceLive,
+  job: enforceJob,
+  mcp: enforceMcp,
+};
+
+/** Dispatcher for code that is generic over surfaces (the action projector). */
+export const enforce = <I>(
+  surface: Surface,
+  policy: Policy<I>,
+  args: EvaluateArgs<I>,
+): SurfaceDenial | undefined => adapters[surface](policy, args);
+
+/** For call sites that would rather throw than branch. Same decision, same reason. */
+export const assertAllowed = <I>(policy: Policy<I>, args: EvaluateArgs<I>): PolicyEvaluation => {
+  const evaluation = evaluate(policy, args);
+  if (!evaluation.allowed) throw forbidden(policy.label, reason(evaluation));
+  return evaluation;
+};

package/src/test-kit.ts

@@ -0,0 +1,79 @@
+// `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 { type EvaluateArgs, evaluate, reasonOf } from './evaluate';
+import type { Policy } from './policy';
+import type { Actor } from './roles';
+
+export interface NamedActor {
+  readonly name: string;
+  readonly actor: Actor | null;
+}
+
+export interface MatrixRow {
+  readonly actor: string;
+  readonly allowed: boolean;
+  readonly reason: string | null;
+  readonly deciding: string | null;
+}
+
+export interface PolicyMatrix {
+  readonly label: string;
+  readonly rows: readonly MatrixRow[];
+  /** `{ owner: true, viewer: false }` — the shape an assertion reads best. */
+  readonly verdicts: Readonly<Record<string, boolean>>;
+  allowedFor(name: string): boolean;
+  /** Fixed-width table for a snapshot test or the dev dashboard. */
+  toTable(): string;
+}
+
+export interface MatrixArgs<I> extends Omit<EvaluateArgs<I>, 'actor'> {
+  readonly actors: readonly NamedActor[];
+}
+
+export const policyMatrix = <I>(policy: Policy<I>, args: MatrixArgs<I>): PolicyMatrix => {
+  const rows = args.actors.map((entry): MatrixRow => {
+    const evaluation = evaluate(policy, {
+      input: args.input,
+      actor: entry.actor,
+      ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
+    });
+    return {
+      actor: entry.name,
+      allowed: evaluation.allowed,
+      reason: reasonOf(evaluation.decision),
+      deciding: evaluation.deciding?.label ?? null,
+    };
+  });
+
+  const verdicts: Record<string, boolean> = {};
+  for (const row of rows) verdicts[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,
+    toTable: () =>
+      rows
+        .map((row) =>
+          `${row.actor.padEnd(width)}  ${row.allowed ? 'allow' : 'deny '}  ${row.reason ?? ''}`.trimEnd(),
+        )
+        .join('\n'),
+  };
+};
+
+/** Builds an actor for tests without asserting anything about core's Actor shape. */
+export const testActor = (
+  name: string,
+  init: { roles?: readonly string[]; permissions?: readonly string[]; orgId?: string } = {},
+): NamedActor => ({
+  name,
+  actor: {
+    id: name,
+    roles: init.roles ?? [],
+    permissions: init.permissions ?? [],
+    orgId: init.orgId ?? null,
+  } as unknown as Actor,
+});