@ultimat3/policy 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,7 +14,7 @@ export const publishPost = action({
 
 ## Shape
 
-A policy is a pure `(input, actor, ctx) => PolicyDecision`.
+A policy is a pure `(input, actor, row, ctx) => PolicyDecision`.
 
 ```ts
 type PolicyDecision =
@@ -26,6 +26,35 @@ type PolicyDecision =
 to an agent: `actor lacks post:publish` and `post:publish predicate returned false`
 are different problems with different fixes.
 
+## One predicate signature, every surface
+
+```ts
+interface PolicyArgs<I = unknown, R = unknown> {
+  input: I;
+  actor: Actor | null;
+  row: R | null; // required — `null` means "this rule decides on input alone"
+  ctx?: Ctx;
+}
+```
+
+A predicate is written once and is correct in an HTTP route, a job, an MCP tool and a
+live query's per-row gate:
+
+```ts
+// decides on input alone — `row` is null
+can<{ orgId: string }>('post:create', ({ actor, input }) => actor?.orgId === input.orgId);
+
+// decides about a row the surface already loaded
+can<{ postId: string }, Post>('post:publish', ({ actor, row }) => row?.authorId === actor?.id);
+```
+
+`row` is required and nullable, not optional. An optional field is how the two shapes
+drifted apart the first time: the realtime row gate nested the row inside `input`, so a
+row rule and an input rule received different objects and nothing caught it.
+
+Callers have it easier — `EvaluateArgs.row` **is** optional, and `evaluate()` normalises a
+missing row to `null`. A surface that has no row passes `{ input, actor, ctx }` unchanged.
+
 ## Combinators
 
 | Builder | Behaviour |

package/package.json

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

package/src/define.ts

@@ -0,0 +1,71 @@
+// `definePolicy` — the authoring form apps use. Sugar over `can()`, deliberately synchronous.
+//
+// Why sync, when an async `check` would let a rule fetch what it needs and no surface could
+// forget to load it: a live query evaluates policy PER SUBSCRIBER on every change event. That
+// is the design — it is why two actors watching one query see different rows. An async check
+// that reads a row turns one insert into one round-trip per subscriber, so a hot feed with
+// 10k watchers costs 10k reads per write and the fanout the realtime tier is built on stops
+// working. HTTP and jobs would tolerate async fine; live queries have the least slack, so they
+// set the constraint.
+//
+// The cost is real and belongs in the open: the caller loads the row first and passes it in.
+// That is more boilerplate than `check: async () => db.posts.find(...)`, and it is the same
+// trade as cursor-only pagination — the more ergonomic option is correct right up until
+// concurrency arrives.
+
+import type { KnownPermission } from './permissions';
+import type { Policy, PolicyArgs, PolicyDecision } from './policy';
+import { can, denied } from './policy';
+
+export interface DefinePolicyInput<I, R = unknown> {
+  /**
+   * Message key rendered when the rule denies. A key rather than a sentence so the denial is
+   * translatable and so two surfaces cannot word the same refusal differently.
+   */
+  readonly deny: string;
+  /**
+   * Pure decision over the actor, the already-loaded input and the already-loaded row.
+   * Returning `false` denies with `deny`; return a `PolicyDecision` for a more specific reason.
+   *
+   * Must not perform I/O — see the file header. A rule that needs a row reads `args.row`,
+   * which the surface loaded and passed in; `row` is `null` when the rule decides on input
+   * alone. Never reach for a row through `input` — that is the drift this signature ended.
+   */
+  readonly check?: (args: PolicyArgs<I, R>) => boolean | PolicyDecision;
+}
+
+/**
+ * Decides on input alone — `row` stays `null`:
+ *
+ * ```ts
+ * export const postCreate = definePolicy<{ orgId: string }>('post:create', {
+ *   deny: 'errors.policyDenied',
+ *   check: ({ actor, input }) => actor?.orgId === input.orgId,
+ * });
+ * ```
+ *
+ * Decides about a row the surface already loaded — second type argument, read `row`:
+ *
+ * ```ts
+ * export const postPublish = definePolicy<{ postId: string }, Post>('post:publish', {
+ *   deny: 'errors.policyDenied',
+ *   check: ({ actor, row }) => row !== null && row.authorId === actor?.id,
+ * });
+ * ```
+ *
+ * Identical in behaviour to `can(permission, predicate)` — the same `Policy` object, so the
+ * same instance is evaluated by HTTP, live queries, jobs, MCP and the admin UI.
+ */
+export const definePolicy = <I = unknown, R = unknown>(
+  permission: KnownPermission,
+  input: DefinePolicyInput<I, R>,
+): Policy<I, R> => {
+  const { deny, check } = input;
+  if (check === undefined) return can<I, R>(permission);
+  return can<I, R>(permission, (args) => {
+    const outcome = check(args);
+    if (outcome === true) return true;
+    if (outcome === false) return denied(deny);
+    return outcome;
+  });
+};

package/src/errors.ts

@@ -1,7 +1,7 @@
 // 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';
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 
 export const POLICY_ERROR_CODES = [
   'X_FORBIDDEN',
@@ -17,7 +17,17 @@ export const POLICY_ERROR_TITLES: Readonly<Record<PolicyErrorCode, string>> = {
   X_PERMISSION_UNKNOWN: 'permission string is not in the permission set',
 };
 
+// This package OWNS X_FORBIDDEN — http, auth, ai, realtime and every other surface adapter throw
+// it and none of them declare a title for it. One authz code, one title, so every surface renders
+// the same string. Registered unconditionally: a second package claiming one of these codes is a
+// bug the registry must surface as X_ERROR_CODE_DUPLICATE, not absorb into a silent first-wins.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(POLICY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
 export class PolicyError extends UltimateError {
+  override readonly name = 'PolicyError';
+
   constructor(init: { code: PolicyErrorCode; cause: string; fix: string }) {
     super({
       code: init.code,
@@ -25,7 +35,6 @@ export class PolicyError extends UltimateError {
       fix: init.fix,
       docs: `https://ultimate.dev/errors/${init.code}`,
     });
-    this.name = 'PolicyError';
   }
 }
 

package/src/evaluate.ts

@@ -5,9 +5,16 @@ import type { Ctx } from '@ultimat3/core';
 import type { Policy, PolicyDecision, TraceEntry } from './policy';
 import type { Actor } from './roles';
 
-export interface EvaluateArgs<I> {
+/**
+ * What a *caller* supplies. `row` is optional here and required in `PolicyArgs`: a surface
+ * that decides on input alone should not have to write `row: null`, but the predicate it
+ * reaches must still see the field. `evaluate()` is the one place that gap is closed.
+ */
+export interface EvaluateArgs<I, R = unknown> {
   readonly input: I;
   readonly actor: Actor | null;
+  /** The already-loaded row for a row-level rule. Omitted means "this rule has no row". */
+  readonly row?: R;
   readonly ctx?: Ctx;
 }
 
@@ -21,12 +28,19 @@ export interface PolicyEvaluation {
   readonly label: string;
 }
 
-export const evaluate = <I>(policy: Policy<I>, args: EvaluateArgs<I>): PolicyEvaluation => {
+export const evaluate = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
+): PolicyEvaluation => {
   const trace: TraceEntry[] = [];
   const decision = policy.run(
     {
       input: args.input,
       actor: args.actor,
+      // Normalising here is what keeps `row` a required field of `PolicyArgs`: an absent row
+      // and an explicit `null` reach the predicate as the same value, so no rule needs to
+      // handle both.
+      row: args.row ?? null,
       ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
     },
     (entry) => trace.push(entry),

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { DefinePolicyInput } from './define';
+export { definePolicy } from './define';
 // The public surface of @ultimat3/policy. Explicit, never `export *`.
 
 export type { PolicyErrorCode } from './errors';

package/src/policy.ts

@@ -1,4 +1,4 @@
-// A policy is a pure function of (input, actor, ctx). Purity is what lets the same
+// A policy is a pure function of (input, actor, row, 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';
@@ -17,13 +17,29 @@ export const denied = (reason: string, code = 'X_FORBIDDEN'): PolicyDecision =>
   code,
 });
 
-export interface PolicyArgs<I> {
+/**
+ * The one shape every predicate sees, on every surface. An input-level rule reads `input`,
+ * a row-level rule reads `row`, and neither has to know which surface called it.
+ */
+export interface PolicyArgs<I = unknown, R = unknown> {
   readonly input: I;
   readonly actor: Actor | null;
+  /**
+   * The already-loaded row a row-level rule decides about; `null` when the rule decides on
+   * input alone.
+   *
+   * Required and nullable rather than optional, deliberately. An optional `row?: R` lets the
+   * two shapes drift apart again: a surface that forgets to pass it still typechecks, so a
+   * row rule reading `args.row` silently sees `undefined` and denies (or worse, allows) for
+   * the wrong reason. `R | null` forces every caller to say which case it is, and makes
+   * "no row here" a value the predicate can branch on instead of an absence it must guess at.
+   * This is the field that used to be smuggled inside `input` by the realtime row gate.
+   */
+  readonly row: R | null;
   readonly ctx?: Ctx;
 }
 
-export type PolicyPredicate<I> = (args: PolicyArgs<I>) => boolean | PolicyDecision;
+export type PolicyPredicate<I, R = unknown> = (args: PolicyArgs<I, R>) => boolean | PolicyDecision;
 
 export type PolicyKind = 'permission' | 'allow' | 'deny' | 'and' | 'or' | 'not';
 
@@ -38,13 +54,14 @@ export interface TraceEntry {
 
 export type Recorder = (entry: TraceEntry) => void;
 
-export interface Policy<I = unknown> {
+/** `R` is defaulted so `Policy<Input>` keeps meaning "decides on input, any row or none". */
+export interface Policy<I = unknown, R = 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;
+  readonly children: readonly Policy<I, R>[];
+  run(args: PolicyArgs<I, R>, record?: Recorder, depth?: number): PolicyDecision;
 }
 
 const record = (
@@ -76,10 +93,10 @@ const asDecision = (result: boolean | PolicyDecision, label: string): PolicyDeci
  * 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>(
+export const can = <I = unknown, R = unknown>(
   permission: KnownPermission,
-  predicate?: PolicyPredicate<I>,
-): Policy<I> => {
+  predicate?: PolicyPredicate<I, R>,
+): Policy<I, R> => {
   assertPermission(permission);
   const label = permission;
   return {
@@ -101,7 +118,7 @@ export const can = <I = unknown>(
 };
 
 /** Explicitly public. Saying so is required; forgetting a policy is a build error. */
-export const allow = <I = unknown>(label = 'allow'): Policy<I> => ({
+export const allow = <I = unknown, R = unknown>(label = 'allow'): Policy<I, R> => ({
   kind: 'allow',
   label,
   permissions: [],
@@ -111,7 +128,10 @@ export const allow = <I = unknown>(label = 'allow'): Policy<I> => ({
   },
 });
 
-export const deny = <I = unknown>(reason: string, code = 'X_FORBIDDEN'): Policy<I> => ({
+export const deny = <I = unknown, R = unknown>(
+  reason: string,
+  code = 'X_FORBIDDEN',
+): Policy<I, R> => ({
   kind: 'deny',
   label: `deny(${reason})`,
   permissions: [],
@@ -121,12 +141,14 @@ export const deny = <I = unknown>(reason: string, code = 'X_FORBIDDEN'): Policy<
   },
 });
 
-const combined = <I>(
+// Combinators hand `args` to every child untouched — `row` included. A clause that rewrote
+// the args would be the second authz shape all over again.
+const combined = <I, R>(
   kind: PolicyKind,
   label: string,
-  children: readonly Policy<I>[],
-  decide: (args: PolicyArgs<I>, recorder: Recorder | undefined, depth: number) => PolicyDecision,
-): Policy<I> => ({
+  children: readonly Policy<I, R>[],
+  decide: (args: PolicyArgs<I, R>, recorder: Recorder | undefined, depth: number) => PolicyDecision,
+): Policy<I, R> => ({
   kind,
   label,
   permissions: children.flatMap((child) => child.permissions),
@@ -137,7 +159,7 @@ const combined = <I>(
 });
 
 /** First denial wins, and its reason is the reason — short-circuit, left to right. */
-export const and = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
+export const and = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> =>
   combined(
     'and',
     `and(${policies.map((policy) => policy.label).join(', ')})`,
@@ -152,7 +174,7 @@ export const and = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
   );
 
 /** First allowance wins; if none allow, the LAST denial is reported. */
-export const or = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
+export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy<I, R> =>
   combined(
     'or',
     `or(${policies.map((policy) => policy.label).join(', ')})`,
@@ -168,7 +190,7 @@ export const or = <I>(...policies: readonly Policy<I>[]): Policy<I> =>
     },
   );
 
-export const not = <I>(policy: Policy<I>): Policy<I> =>
+export const not = <I, R = unknown>(policy: Policy<I, R>): Policy<I, R> =>
   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/surfaces.ts

@@ -51,9 +51,9 @@ const reason = (evaluation: PolicyEvaluation): string => reasonOf(evaluation.dec
 
 const code = (evaluation: PolicyEvaluation): string => codeOf(evaluation.decision) ?? 'X_FORBIDDEN';
 
-export const enforceHttp = <I>(
-  policy: Policy<I>,
-  args: EvaluateArgs<I>,
+export const enforceHttp = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
 ): HttpDenial | undefined => {
   const evaluation = evaluate(policy, args);
   if (evaluation.allowed) return undefined;
@@ -69,16 +69,19 @@ export const enforceHttp = <I>(
   };
 };
 
-export const enforceLive = <I>(
-  policy: Policy<I>,
-  args: EvaluateArgs<I>,
+export const enforceLive = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
 ): 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 => {
+export const enforceJob = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
+): JobDenial | undefined => {
   const evaluation = evaluate(policy, args);
   if (evaluation.allowed) return undefined;
   return {
@@ -90,7 +93,10 @@ export const enforceJob = <I>(policy: Policy<I>, args: EvaluateArgs<I>): JobDeni
   };
 };
 
-export const enforceMcp = <I>(policy: Policy<I>, args: EvaluateArgs<I>): McpDenial | undefined => {
+export const enforceMcp = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
+): McpDenial | undefined => {
   const evaluation = evaluate(policy, args);
   if (evaluation.allowed) return undefined;
   return {
@@ -103,7 +109,7 @@ export const enforceMcp = <I>(policy: Policy<I>, args: EvaluateArgs<I>): McpDeni
 
 export type SurfaceDenial = HttpDenial | LiveDenial | JobDenial | McpDenial;
 
-type Adapter = <I>(policy: Policy<I>, args: EvaluateArgs<I>) => SurfaceDenial | undefined;
+type Adapter = <I, R>(policy: Policy<I, R>, args: EvaluateArgs<I, R>) => SurfaceDenial | undefined;
 
 const adapters: Readonly<Record<Surface, Adapter>> = {
   http: enforceHttp,
@@ -113,14 +119,17 @@ const adapters: Readonly<Record<Surface, Adapter>> = {
 };
 
 /** Dispatcher for code that is generic over surfaces (the action projector). */
-export const enforce = <I>(
+export const enforce = <I, R = unknown>(
   surface: Surface,
-  policy: Policy<I>,
-  args: EvaluateArgs<I>,
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
 ): 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 => {
+export const assertAllowed = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: EvaluateArgs<I, R>,
+): PolicyEvaluation => {
   const evaluation = evaluate(policy, args);
   if (!evaluation.allowed) throw forbidden(policy.label, reason(evaluation));
   return evaluation;

package/src/test-kit.ts

@@ -27,15 +27,22 @@ export interface PolicyMatrix {
   toTable(): string;
 }
 
-export interface MatrixArgs<I> extends Omit<EvaluateArgs<I>, 'actor'> {
+/** Everything `evaluate` takes except the actor — `row` included, so a row rule is testable. */
+export interface MatrixArgs<I, R = unknown> extends Omit<EvaluateArgs<I, R>, 'actor'> {
   readonly actors: readonly NamedActor[];
 }
 
-export const policyMatrix = <I>(policy: Policy<I>, args: MatrixArgs<I>): PolicyMatrix => {
+export const policyMatrix = <I, R = unknown>(
+  policy: Policy<I, R>,
+  args: MatrixArgs<I, R>,
+): PolicyMatrix => {
   const rows = args.actors.map((entry): MatrixRow => {
+    // Every field but the actor is forwarded verbatim: a matrix that dropped `row` would
+    // report a row rule as denying everyone, and the table would lie.
     const evaluation = evaluate(policy, {
       input: args.input,
       actor: entry.actor,
+      ...(args.row === undefined ? {} : { row: args.row }),
       ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
     });
     return {