@ultimat3/policy 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -49,12 +49,18 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   hoisted here. `admitsAnonymous` in particular is EXACT for `actor === null` rather than a
   heuristic, because `can()` short-circuits on the actor check before its predicate and
   `allow()`/`deny()` ignore their arguments — no predicate is consulted, so the tree alone decides.
+- **`action` and `query` reach authz through `guardPrimitive()`, one function** (`As of 2026-11`, v31).
+  The two tier-3 `policy-gate.ts` files were the same pipeline twice and drifted: a query's MCP
+  call was judged as `'job'`, an action's as `'mcp'`. The surface rule is
+  `PRIMITIVE_POLICY_SURFACES`, data, read with `Object.hasOwn` at both levels; it RETURNS the
+  denial (code, reason, shape) because the error class is the primitive's and this tier cannot
+  name it. A new primitive surface is a row there, never a branch in a caller.
 - **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
+  guarantee is what a `policy.decision` 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.
@@ -176,8 +182,10 @@ reappearing there is a failing test.
 | `policy.ts` | `can`/`allow`/`deny`/`and`/`or`/`not` + decision recording, and `policyPermissions` |
 | `policy-anonymous.ts` | `admitsAnonymous` — the one question a SURFACE asks of a built tree, apart from the file that builds them |
 | `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 |
+| `decisions.ts` | the `policy.decision` bus event — built only while subscribed, one call site, never PII. No slot (`X_INSTRUMENT_SLOT_FORBIDDEN`) |
 | `surfaces.ts` | http/live/job/mcp adapters — the "one system" proof |
+| `guard-primitive.ts` | `guardPrimitive` — the one gate `action` and `query` run, and the per-primitive surface table |
+| `denial-parts.ts` | `denialCode` / `denialReason` — any `SurfaceDenial` read back as one code and one reason |
 | `roles.ts` | the role map: merge, conflict, inheritance, wildcards |
 | `declaration-site.ts` | the caller's stack frame a role or permission declaration records |
 | `grant-index.ts` | the per-actor flattened grant set, memoised against the role generation |
@@ -194,13 +202,13 @@ with 10k watchers is 10k evaluations in one tick. Two consequences, both load-be
   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,
+- The trace is opt-in: on outside production, and in production only while `policy.decision` has a
+  subscriber. `evaluate(policy, args, { trace: true })` forces it — `policyMatrix()` does,
   because `deciding` *is* the matrix.
 
 ## Commands
 
 ```
-bun test packages/policy
+bun test ./packages/policy/
 bun run --filter @ultimat3/policy typecheck
 ```

package/README.md

@@ -119,7 +119,9 @@ arguments, so no predicate is ever consulted and the tree alone decides. `true`
 ## 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`.
+error shape; allowed returns `undefined`. The barrel exports `enforceHttp` and
+`enforce(surface, policy, args)`; the live, job and MCP adapters are reached through `enforce` only
+(off `.` since 31.0.0).
 
 | Adapter | Denial shape |
 |---|---|
@@ -147,6 +149,39 @@ it inherits `Object.prototype` — `enforce('valueOf' as Surface, …)` used to
 `Object.prototype.valueOf` with the table as its receiver and return a truthy value, so an authz
 dispatch failed **closed with a `SurfaceDenial` no caller could read**.
 
+## One guard for action and query
+
+`guardPrimitive(kind, policy, subject, surface)` is the gate `@ultimat3/action` and
+`@ultimat3/query` both run — siblings at tier 3 that cannot share a file, so it lives here.
+
+```ts
+import type { Actor } from '@ultimat3/core';
+import { can, guardPrimitive } from '@ultimat3/policy';
+
+declare const actor: Actor | null;
+const refused = guardPrimitive(
+  'query',
+  can('post:read'),
+  { stage: 'actor', name: 'postFeed', actor },
+  'mcp',
+);
+// `@ultimat3/query` throws its own class from the answer: `new QueryDeniedError(refused)`.
+if (refused !== undefined) console.log(refused.code, refused.reason);
+```
+
+| Field | Meaning |
+|---|---|
+| `kind` | `'action'` or `'query'` — picks the surface table |
+| `subject.stage` | `'actor'`: before the input parse, only `can()`/`allow()`/`deny()` decide, undecided passes · `'input'`: the full evaluation, with `input` and the loaded `row` |
+| `surface` | where the primitive ran: action `server · http · mcp · job`, query `server · http · mcp · live` |
+| returns | `undefined` to proceed, or `{ kind, name, surface, code, reason, denial }` |
+
+`PRIMITIVE_POLICY_SURFACES` is the surface rule as data: `server` is judged as `job`, `mcp` as
+`mcp` for **both** primitives (a read was judged as `job` until v31). A surface the primitive does
+not run on is `X_POLICY_SURFACE_UNKNOWN`, never a decision. `denialCode(denial)` /
+`denialReason(denial)` read any `SurfaceDenial` back as one code and one reason — the MCP text
+without its `<code>: ` prefix.
+
 ## Permissions and roles
 
 `definePermissions(['post:publish', ...])` gives a typed set; augmenting
@@ -183,26 +218,30 @@ 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
+Building it is opt-in: on outside production, and in production only while a `policy.decision`
+subscriber is listening. 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 }
-  },
+import { subscribe } from '@ultimat3/core';
+
+// { label, allowed, code, reason, actorId, actorKind, orgId, surface, deciding }
+export const stopAudit = subscribe('policy.decision', ({ payload }) => {
+  void payload.label;
 });
 ```
 
-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.
+`As of 2026-11` (v31): every evaluation is one `policy.decision` event on core's instrumentation
+bus (`PolicyDecisionEvent`, re-exported here). Nothing is built until something subscribes, it is
+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 event inherits that
+guarantee. Every subscriber hears it — there is no slot to replace. A subscriber's throw is
+contained by the bus, as on every event: an observer is not an authorization input, so it can
+neither deny nor break the evaluation.
 
 ## Errors
 
@@ -220,7 +259,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `PolicyError` | any `PolicyErrorCode` — `POLICY_ERROR_CODES` | `src/errors.ts` |
+| `PolicyError` | any `PolicyErrorCode` | `src/errors.ts` |
 
 ## Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "The one authz rule, evaluated identically in every surface",
   "keywords": [
     "ultimate",
@@ -42,6 +42,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0"
+    "@ultimat3/core": "31.0.0"
   }
 }

package/src/decisions.ts

@@ -1,90 +1,26 @@
-// 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.
+// The authz decision log: every evaluation, allowed ones included, is a `policy.decision` event on
+// the instrumentation bus — because the question after an incident is "who did this, and which
+// rule let them?", and an allowed decision used to leave no trace on any of the four surfaces.
+// A SIEM exporter, an append-only table or a log line all arrive as one `subscribe()`.
 //
 // 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';
+import { instrument, type PolicyDecisionEvent, subscribed } from '@ultimat3/core';
 
-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;
-};
+const DECISION = 'policy.decision';
 
 /**
- * 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.
+ * Read by `evaluate()` before it builds an event, and by the trace default: a subscriber is the
+ * one reason to keep building a trace in production. One map read when nobody listens.
  */
-export const decisionSinkInstalled = (): boolean => sink !== undefined;
+export const decisionObserved = (): boolean => subscribed(DECISION);
 
 /**
- * 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.
+ * 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. A throwing subscriber is contained
+ * by the bus, as on every event: an observer is not an authorization input and cannot deny.
  */
 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;
-    },
-  };
+  instrument(DECISION, event);
 };

package/src/denial-parts.ts

@@ -0,0 +1,48 @@
+// The code and the reason a surface-shaped denial carries, read back out of whichever shape the
+// adapter rendered. Here once: `@ultimat3/action` and `@ultimat3/query` each kept a copy, and both
+// copies read an MCP denial's whole text as its reason, so the cause said the code twice.
+
+import { assertNever } from '@ultimat3/core';
+import type { SurfaceDenial } from './surfaces';
+
+/** The `X_*` code the policy decided with — the same one on every surface. */
+export function denialCode(denial: SurfaceDenial): string {
+  switch (denial.surface) {
+    case 'http':
+      return denial.problem.code;
+    case 'live':
+    case 'job':
+      return denial.code;
+    case 'mcp':
+      return mcpParts(denial.content[0]?.text).code;
+    default:
+      return assertNever(denial);
+  }
+}
+
+/** The policy's reason, safe to log by construction — never prefixed with the code. */
+export function denialReason(denial: SurfaceDenial): string {
+  switch (denial.surface) {
+    case 'http':
+      return denial.problem.detail;
+    case 'live':
+    case 'job':
+      return denial.reason;
+    case 'mcp':
+      return mcpParts(denial.content[0]?.text).reason;
+    default:
+      return assertNever(denial);
+  }
+}
+
+/**
+ * `enforceMcp` writes `<code>: <reason>`, and a code never holds `': '`, so the first separator
+ * splits it exactly. A text without one is a reason with no code: `X_FORBIDDEN`, the default
+ * every adapter falls back to.
+ */
+function mcpParts(text: string | undefined): { readonly code: string; readonly reason: string } {
+  if (text === undefined) return { code: 'X_FORBIDDEN', reason: 'denied' };
+  const at = text.indexOf(': ');
+  if (at <= 0) return { code: 'X_FORBIDDEN', reason: text };
+  return { code: text.slice(0, at), reason: text.slice(at + 2) };
+}

package/src/errors.ts

@@ -243,3 +243,23 @@ export const surfaceUnknown = (surface: unknown, known: readonly string[]): Poli
     cause: `enforce() was handed surface ${renderCauseValue(surface)}, which no policy adapter answers to`,
     fix: `pass one of ${known.join(', ')} — e.g. enforce('${known[0] ?? 'http'}', policy, args)`,
   });
+
+/**
+ * `guardPrimitive()` was handed a surface its primitive does not run on — an action on `live`, a
+ * query on `job` — or a kind that is neither. The same code as `surfaceUnknown`, because it is the
+ * same fault one layer up: no adapter answers. Both values are rendered, never interpolated: the
+ * call site this exists for is a JS host or a config table no type reached.
+ */
+export const primitiveSurfaceUnknown = (
+  kind: unknown,
+  surface: unknown,
+  known: readonly string[],
+): PolicyError =>
+  new PolicyError({
+    code: 'X_POLICY_SURFACE_UNKNOWN',
+    cause: `guardPrimitive() was handed surface ${renderCauseValue(surface)} for kind ${renderCauseValue(kind)}, which that primitive does not run on`,
+    fix:
+      known.length === 0
+        ? "guardPrimitive('action', policy, subject, 'server')   # the kind is 'action' or 'query'"
+        : `guardPrimitive(kind, policy, subject, '${known[0]}')   # the surface is one of ${known.map((name) => `'${name}'`).join(', ')}`,
+  });

package/src/evaluate.ts

@@ -1,10 +1,10 @@
 // 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.
-// It is also the one place a decision reaches the `DecisionSink` — allowed decisions
+// It is also the one place a `policy.decision` event is emitted — 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 { decisionObserved, emitDecision } from './decisions';
 import type { Policy, PolicyDecision, TraceEntry } from './policy';
 import type { Actor } from './roles';
 import type { Surface } from './surfaces';
@@ -24,12 +24,12 @@ export interface EvaluateArgs<I, R = unknown> {
 
 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
+   * Build the trace. Defaults to on outside production, and to on in production only while
+   * `policy.decision` has a subscriber — 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. */
+  /** Which adapter asked. Carried on the event; the decision itself never depends on it. */
   readonly surface?: Surface | undefined;
 }
 
@@ -53,7 +53,7 @@ let outsideProduction: boolean | undefined;
  */
 const traceByDefault = (): boolean => {
   outsideProduction ??= (tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT) !== 'production';
-  return outsideProduction || decisionSinkInstalled();
+  return outsideProduction || decisionObserved();
 };
 
 /** Test seam: re-reads the environment on the next evaluation. */
@@ -91,7 +91,7 @@ export const evaluate = <I, R = unknown>(
     ) ??
     trace.find(agrees) ??
     null;
-  if (decisionSinkInstalled()) {
+  if (decisionObserved()) {
     emitDecision({
       label: policy.label,
       allowed: decision.allowed,

package/src/guard-primitive.ts

@@ -0,0 +1,125 @@
+// The one policy guard `action` and `query` both run: which policy surface each projection is
+// judged on, the actor-only stage before the input parse, the full stage after it, and the denial
+// read back as one code and one reason. Tier 3 siblings cannot share a file, so it lives here.
+
+import type { Ctx } from '@ultimat3/core';
+import { denialCode, denialReason } from './denial-parts';
+import { primitiveSurfaceUnknown } from './errors';
+import type { Policy } from './policy';
+import { enforceBeforeInput } from './pre-input';
+import type { Actor } from './roles';
+import { enforce, type Surface, type SurfaceDenial } from './surfaces';
+
+/** The two primitives that carry a policy. A mutator is an action; a route asks `evaluate()`. */
+export type GuardedPrimitive = 'action' | 'query';
+
+/** Where each primitive runs. `'server'` is in-process app code; `live` is a read's alone. */
+export interface PrimitiveSurfaces {
+  readonly action: 'server' | 'http' | 'mcp' | 'job';
+  readonly query: 'server' | 'http' | 'mcp' | 'live';
+}
+
+export type PrimitiveSurface<K extends GuardedPrimitive = GuardedPrimitive> = PrimitiveSurfaces[K];
+
+/**
+ * The surface rules, as data. A direct server call has no request and no response to shape, so it
+ * is judged as a job. An MCP call is an agent's on BOTH primitives: a read was judged as `'job'`
+ * until v31, so its decision events and its denial shape disagreed with an MCP action's.
+ */
+export const PRIMITIVE_POLICY_SURFACES = Object.freeze<{
+  readonly [K in GuardedPrimitive]: Readonly<Record<PrimitiveSurfaces[K], Surface>>;
+}>({
+  action: Object.freeze<Record<PrimitiveSurfaces['action'], Surface>>({
+    server: 'job',
+    http: 'http',
+    mcp: 'mcp',
+    job: 'job',
+  }),
+  query: Object.freeze<Record<PrimitiveSurfaces['query'], Surface>>({
+    server: 'job',
+    http: 'http',
+    mcp: 'mcp',
+    live: 'live',
+  }),
+});
+
+interface SubjectBase {
+  /** The registered name of the primitive — what the denial and `x policy explain` name. */
+  readonly name: string;
+  readonly actor: Actor | null;
+  readonly ctx?: Ctx | undefined;
+}
+
+/** Before the input parse: only who is asking. Undecided passes to the `'input'` stage. */
+export interface ActorStageSubject extends SubjectBase {
+  readonly stage: 'actor';
+}
+
+/** After the parse: the input, and the loaded row a row-level rule decides about. */
+export interface InputStageSubject<I = unknown, R = unknown> extends SubjectBase {
+  readonly stage: 'input';
+  readonly input: I;
+  /** Omitted when nothing was loaded; `evaluate()` hands the predicate `null`. */
+  readonly row?: R | undefined;
+}
+
+export type GuardSubject<I = unknown, R = unknown> = ActorStageSubject | InputStageSubject<I, R>;
+
+/** A refusal, already read: the adopting package throws its own error class from it. */
+export interface PrimitiveDenial<K extends GuardedPrimitive = GuardedPrimitive> {
+  readonly kind: K;
+  readonly name: string;
+  readonly surface: PrimitiveSurface<K>;
+  readonly code: string;
+  readonly reason: string;
+  /** The surface-shaped denial — a live socket closes 4403 off it, HTTP renders its problem. */
+  readonly denial: SurfaceDenial;
+}
+
+/**
+ * Decide once and return the refusal, or `undefined` to proceed. Returned rather than thrown: the
+ * error class is the primitive's (`ActionDeniedError`, `QueryDeniedError`) and this tier cannot
+ * name it. The decision event is `evaluate()`'s, emitted once, on the mapped policy surface.
+ */
+export function guardPrimitive<K extends GuardedPrimitive, I, R>(
+  kind: K,
+  policy: Policy<I, R>,
+  subject: GuardSubject<I, R>,
+  surface: PrimitiveSurface<K>,
+): PrimitiveDenial<K> | undefined {
+  const target = policySurfaceOf(kind, surface);
+  const denial =
+    subject.stage === 'actor'
+      ? enforceBeforeInput(target, policy, actorArgs(subject))
+      : enforce(target, policy, {
+          input: subject.input,
+          actor: subject.actor,
+          ...(subject.row === undefined ? {} : { row: subject.row }),
+          ...(subject.ctx === undefined ? {} : { ctx: subject.ctx }),
+        });
+  if (denial === undefined) return undefined;
+  return {
+    kind,
+    name: subject.name,
+    surface,
+    code: denialCode(denial),
+    reason: denialReason(denial),
+    denial,
+  };
+}
+
+function actorArgs(subject: SubjectBase): { actor: Actor | null; ctx?: Ctx } {
+  return subject.ctx === undefined
+    ? { actor: subject.actor }
+    : { actor: subject.actor, ctx: subject.ctx };
+}
+
+/** `Object.hasOwn` at both levels, for the reason `enforce()` gives: an index answers `valueOf`. */
+function policySurfaceOf(kind: GuardedPrimitive, surface: string): Surface {
+  if (!Object.hasOwn(PRIMITIVE_POLICY_SURFACES, kind))
+    throw primitiveSurfaceUnknown(kind, surface, []);
+  const table: Readonly<Record<string, Surface>> = PRIMITIVE_POLICY_SURFACES[kind];
+  if (!Object.hasOwn(table, surface))
+    throw primitiveSurfaceUnknown(kind, surface, Object.keys(table));
+  return table[surface] as Surface;
+}

package/src/index.ts

@@ -1,44 +1,33 @@
 // The public surface of @ultimat3/policy. Explicit, never `export *`.
-export type { DecisionSink, MemoryDecisionSink, PolicyDecisionEvent } from './decisions';
-export {
-  decisionSinkInstalled,
-  memoryDecisionSink,
-  noopDecisionSink,
-  resetDecisionSink,
-  setDecisionSink,
-} from './decisions';
+// The `policy.decision` payload is core's (the bus is tier 0); re-exported, never a second shape.
+export type { PolicyDecisionEvent } from '@ultimat3/core';
 export type { DefinePolicyInput } from './define';
 export { definePolicy } from './define';
+export { denialCode, denialReason } from './denial-parts';
 export type { PolicyErrorCode } from './errors';
 export {
   denialError,
-  emptyClauseList,
   POLICY_BORROWED_ERROR_CODES,
-  POLICY_ERROR_CODES,
-  POLICY_ERROR_TITLES,
   PolicyDenialError,
   PolicyError,
   permissionUnknown,
   policyForbidden,
   policyMissing,
-  roleRedefined,
 } from './errors';
 export type { EvaluateArgs, EvaluateOptions, PolicyEvaluation } from './evaluate';
-export {
-  codeOf,
-  evaluate,
-  explain,
-  reasonOf,
-  renderTrace,
-  resetPolicyTracing,
-} from './evaluate';
+export { codeOf, evaluate, explain, reasonOf } from './evaluate';
 export { actorHas, actorPermissions } from './grant-index';
 export type {
-  KnownPermission,
-  Permission,
-  PermissionRegistry,
-  PermissionSet,
-} from './permissions';
+  ActorStageSubject,
+  GuardedPrimitive,
+  GuardSubject,
+  InputStageSubject,
+  PrimitiveDenial,
+  PrimitiveSurface,
+  PrimitiveSurfaces,
+} from './guard-primitive';
+export { guardPrimitive, PRIMITIVE_POLICY_SURFACES } from './guard-primitive';
+export type { KnownPermission, Permission, PermissionRegistry, PermissionSet } from './permissions';
 export {
   assertPermission,
   clearPermissions,
@@ -48,7 +37,6 @@ export {
   permissionDeclarationSites,
   resourceOf,
   restorePermissions,
-  verbOf,
 } from './permissions';
 export type {
   Policy,
@@ -83,7 +71,6 @@ export {
   restoreRoles,
   roleDeclarationSites,
   roleDefinitions,
-  roleMapGeneration,
   rolesGranting,
 } from './roles';
 export type {
@@ -95,13 +82,6 @@ export type {
   Surface,
   SurfaceDenial,
 } from './surfaces';
-export {
-  assertAllowed,
-  enforce,
-  enforceHttp,
-  enforceJob,
-  enforceLive,
-  enforceMcp,
-} from './surfaces';
+export { assertAllowed, enforce, enforceHttp } from './surfaces';
 export type { MatrixArgs, MatrixRow, NamedActor, PolicyMatrix } from './test-kit';
 export { policyMatrix, testActor } from './test-kit';