Why was this refused?

Every decision access.can returns carries reason beside allowed, and rule or missing where one applies, and a screen reads those three to tell a customer why an action is off.

Turning an acl refusal into what the screen says

The Edit button under a question is off, and the customer wants to know why. A button that says “Not allowed” for every allowed: false tells a customer whose row is still loading that they may never edit their own question.

allowed is still the only field a handler gates on, as Can this user do this? sets out. reason, rule and missing decide the label. The policy below carries a deny rule, written with p.deny, which refuses whenever it matches and outranks the allow, and .id(name) gives that rule the name a decision reports:

import { policy } from '@evanion/acl';
import type { Decision } from '@evanion/acl';
 
type Question = { askedBy: string; status: string };
 
const access = policy<{ id: string }, { question: Question }>()
  .for('question', (p) =>
    p
      .allow('update', p.eq('object.askedBy', 'subject.id'))
      .deny('update', p.eq('object.status', 'locked'))
      .id('locked-question'),
  )
  .build();
 
/** What the Edit button under a question says. */
function editLabel(decision: Decision): string {
  if (decision.allowed) return 'Edit';
  if (decision.reason === 'denied') return `Locked (${decision.rule})`;
  if (decision.reason === 'unevaluable') return 'Checking';
  return 'Not your question';
}
 
const asker = { id: 'customer-41' };
const ask = (row: Partial<Question>) =>
  access.can(asker, 'question', 'update', row);
 
editLabel(ask({ askedBy: 'customer-41', status: 'open' })); // -> 'Edit'
editLabel(ask({ askedBy: 'customer-41', status: 'locked' })); // -> 'Locked (locked-question)'
editLabel(ask({ askedBy: 'customer-92', status: 'open' })); // -> 'Not your question'
 
// The list query did not select `status`, so the deny rule could not be read.
const partial = ask({ askedBy: 'customer-41' });
editLabel(partial); // -> 'Checking'
partial.rule; // -> 'locked-question'
partial.missing; // -> ['object.status']

editLabel reads allowed first and then reason. denied means a deny rule matched, and rule names it, because .id('locked-question') gave the rule that name. The last call passed a row without status, so the deny rule could not be read: the decision is unevaluable, missing names object.status, and the button says Checking while the screen fetches that one field.

The seven reasons an acl decision carries

reason takes one of seven values, and each one tells a screen something different:

reason, rule and missing are output only, and no part of the library reads them back. A screen branches on reason to pick a label. A handler that branches on it to allow something has written a rule of its own beside the policy.

stale-contract comes from a document another service published. The service holding a copy tells parseMatrix, the call that adopts a foreign document, when it last fetched that copy, as fetchedAt. The document states how long a copy stays good, as maxStale in milliseconds, and past that bound every key answers stale-contract. A fresh fetch repairs it, and How long a consumer may keep deciding on an acl contract sets out the bound.

When the acl clock decides unusable-clock

can, canMany, canFields and capabilities take now as a trailing argument: an ISO 8601 string, epoch milliseconds or a Date. Omit it and the call reads the wall clock. A rule built with p.after or p.before compares that instant against a boundary, so p.after('now', '2026-10-01T09:00:00Z') holds once the call’s instant passes the boundary. The third type argument names place as an action of preorder, because the default actions are create, read, update and delete:

import { policy } from '@evanion/acl';
 
// Preorders for a new game open at one instant.
const access = policy<
  { id: string },
  { preorder: { game: string } },
  { preorder: 'place' }
>()
  .for('preorder', (p) =>
    p
      .allow('place', p.after('now', '2026-10-01T09:00:00Z'))
      .id('preorders-open'),
  )
  .build();
 
const shopper = { id: 'customer-41' };
const place = (now: string | number) =>
  access.can(shopper, 'preorder', 'place', undefined, now);
 
place('2026-10-02T12:00:00Z').allowed; // -> true
place(Date.parse('2026-09-30T12:00:00Z')).reason; // -> 'no-rule-matched'
 
// A header that was never a date. The rule that compared the clock is named.
const garbled = place('next tuesday');
garbled.reason; // -> 'unusable-clock'
garbled.rule; // -> 'preorders-open'
'missing' in garbled; // -> false

A now that does not parse never throws. The permission refuses with unusable-clock, names the rule that compared the clock, and carries no missing, because no refetch repairs it. Fix the value the call passes.

rule, the acl rule that decided

allow, denied and unusable-clock always carry rule. An unevaluable carries it only when a deny rule was unreadable: one deny rule refuses on its own, so the engine names it. When the unreadable rules were allow rules, any one of them could have granted, so no single rule is named.

The name comes from one of two places:

• A rule the author named reports that name. A policy written with policy() names a rule with .id(name) after the allow or deny that wrote it.
• A rule nobody named reports a derived id, the side it sits on and a hash of its conditions, such as allow-53eebf50.

Store a name the author wrote, and never store a derived one. A release of this library that changes how a condition is represented changes every derived id, so an audit row holding allow-53eebf50 stops matching its rule with nothing to report it.

Treat rule as a log line and a support answer, such as “denied by locked-question”. Never branch on it: two rules can grant the same thing, and which one matched is not a fact the app should depend on.

When the answer is unevaluable

unevaluable says the engine never reached an answer, because a rule read an object.* path the row did not carry. allowed is already false, so nothing leaks, and missing names exactly what to fetch. A caller meets it with no row at all, as a create button does, or with a projection, a row loaded with only some of its columns. Can this user do this? works the refetch through.

Both sides’ unreadable paths arrive in one missing, so one query settles the permission however many rules read the row. Every operator treats an absent object.* path as unevaluable, including ne (not equal) and not-in, because “not equal to locked” states no fact about a field nobody read. An absent subject.* path fails its condition instead, because the server resolves the subject whole and never projects it.

What to do with an acl unevaluable

Deciding before the row is loaded works the last row through.

Explaining one field of an acl field decision

canFields decides each field of a write separately, as Which fields may they write? covers, and gives every field a state and a FieldReason. A read-only input names its reason the way a refused button does:

Which fields may they write? builds a policy that produces allow, not-listed, transition-failed and missing-field, and Field permissions is the reference.