Make a Policy say what it grants, instead of multiplying two lists

[xmap]

Part 1 of the authorization work planned after #761. It is a prerequisite for migrating the background watchers onto the in-process door, and it stands alone.

The problem

Policy held permitted_principal_ids and permitted_commands as two independent sets, and evaluate checked membership in each separately. That grants every listed principal every listed command: the full N x M cross-product.

  what a rulebook looks like it says     what it actually said
  ─────────────────────────────────      ─────────────────────
    RunWitness  →  record a run            {every principal}
    Debriefer   →  write a note                   ×
    Ingestor    →  truncate a run          {every command}

Already live: the backdoor rulebook deployed at 2-BM on 2026-09-01 says InHouseCautionDrafter may TruncateRun, though its code only ever calls AppendInferences. Not exploitable, since the surface gate still bounds who can reach that rulebook at all, but the rulebook grants strictly more than the code it governs. At full fleet the gap is roughly 20 principals x 35 commands = 700 nominal grants against about 48 real ones.

It also blocked the watcher migration: adding the run supervisor's AbortRun to a shared rulebook would have handed AbortRun to the read-only status page feed.

What ships

Policy.grants, a frozenset of (principal_id, command_name) pairs. permitted_principal_ids and permitted_commands survive as derived properties, so every existing reader keeps working and neither can disagree with grants because both are computed from it.

This is a no-op for every policy that already exists. A PolicyDefined written before pairs carries the two lists and no grants key; _grants_from_payload cross-products them at the deserialization boundary, the same place a legacy event's missing surface_id already gets its default. Moving the multiplication from the check to the fold changes where it happens, never what it yields. Six tests pin that, one by exhaustive evaluation rather than by rebuilding the same cross-product the implementation builds, so it stays honest if the fold is ever rewritten.

POST /policies and the define_policy MCP tool accept either an exact grants mapping or the two cross-producted lists, exactly one required. Both refused rather than resolved: the pair form grants materially more than an equivalent-looking mapping, and an agent asking for one and receiving the other is the exact over-grant this removes. DefinePolicy.from_cross_product is the named constructor for callers who do mean everyone-gets-everything.

Two things the work found that review would not have

The precision was untested. Reverting evaluate to the union check left all 682 trust tests green. Every existing case used one principal or a shared command list, where both designs agree; only a policy whose principals have different command sets can tell them apart. Two tests now catch that mutation. (A third split-policy test asserts an Allow and cannot catch it, since a union check permits a superset of what a pair check permits. It is kept because a narrowing that denied what a policy permits would be its own bug, but it is not evidence of precision.)

It was a real performance regression. The authz-latency benchmark hung: evaluate read the derived permitted_principal_ids on every authorization, rebuilding a set from 2,048 tuples per decision on a 64-principal policy. evaluate now settles the permitted case with one hash lookup and pays the scan only when choosing which refusal to report, so the happy path is faster than before. That benchmark passes in 10.8s.

A pre-existing export bug, surfaced but deliberately not fixed

PolicyDefined.grants is force-overridden to drop:opaque in the disposition generator. tuple[tuple[UUID, str], ...] is a collection of pairs, but _classify erases the outer collection and emits the single-positional-record rule; _redact_tier1 then zips two dispositions against a list of N pairs, which raises for any N except 2 and silently mis-redacts at 2 (independently reproduced during review, including the OMITTED sentinel leaking into the output list).

PartitionRule.partition_parameters has the identical shape and the identical latent defect. Fixing the generator and redactor changes what published records disclose for a second, unrelated aggregate, and deserves its own reviewed diff rather than riding inside a Trust change.

The cost is admitted, not glossed: an exported policy record now discloses nothing about its grants, where before it showed pseudonymised principals with no commands beside them. Fail-closed, and a narrowing.

Process

Designed and implemented by Opus, then handed to a Sonnet subagent with instructions to refute the claims above rather than confirm them. It found one factual error (I had written "three tests turn red" where two do) and three weaknesses, all closed in the second commit: legacy folds no longer emit duplicate pairs; the "exactly one grant shape" rule now lives in one shared place instead of being duplicated across the two surfaces that could drift; and the test helper raises on both-shapes like the production surfaces do. The review also independently reproduced the redaction bug above, confirming it is real rather than a convenient pretext for the override.

Verification

52,581 unit + architecture + contract, 1,367 integration, all green. ruff, pyright, tach, make docs-build clean. OpenAPI and the disposition table regenerated by their own generators, not hand-edited.

Mutation-verified: the exact pair check, the legacy cross-product fold, both route-validator branches, and the shared shape rule's ABSENT-vs-EMPTY distinction each turn exactly their paired tests red.

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
apps/api/src/cora/trust/aggregates/policy
events.py
evolver.py
state.py
apps/api/src/cora/trust/features/define_policy
_grant_shape.py
command.py
decider.py
route.py
tool.py					54-55
Project Total

This report was generated by python-coverage-comment-action