feat(#575): the audience floor and capability grants (phase 2)

[Weegy]

Unblocked by #726. The Phase-0 spec sequences this explicitly — "#333 must land before #575 Phase 2", because the floor intersects entitlements and ChatParticipant carries none. #333 phases 1–3 are on main, so this is now buildable.

This is the first module in the cluster that decides something. #333 produces Principals and says what they are entitled to; this consumes them and answers "given who is present, what may happen in this room?".

One intersection function, three guards

Spec §5.2 warns that planning "the audience floor" as a single interception point is the most common way to get it wrong, because what it guards has three different correctness requirements:

What is guarded	Where it must be evaluated	Why not per-turn
Egress (tool calls)	per call	a turn-start snapshot is a TOCTOU hole — the audience can change before the call fires
Context / memory retrieval	per retrieval, per recipient	the rendered context differs per recipient by definition
File / credential handles	at handle resolution	the handle outlives the turn

So the intersection ships as a pure, cheap function the three guards share — cheap precisely so per-call evaluation is affordable — rather than as a hook.

Mid-turn joiners follow §5.3 / D4, split by reversibility: a floor is a value, not a subscription. Rendered context cannot be un-sent, so the context guard snapshots; an unfired call can still be refused, so the egress guard re-computes.

Everything fails closed, because the intersection of nothing is everything

This is the trap the whole design is shaped around, and it is live today, not hypothetical:

ChatParticipantsProvider: "Returning an empty array is a valid unknown / unavailable state"

An empty roster already means unknown. Reading it as "the room is empty, so nothing is restricted" is what §5.1 calls a silent full-permission grant. So:

• an unknown audience — including an empty roster — permits nothing;
• one unresolvable participant closes the whole room, because bounding only the people you could identify is not bounding the room;
• a known audience with no members is refused explicitly rather than left to a reduce that would yield "no constraints".

closed is deliberately not the same as open with an empty capability set. Both permit nothing, but the first is an outage and the second is policy — an operator staring at a blocked workflow needs to tell them apart. Same reasoning as partial on #333's role lookups, which is carried through: a partial role lookup produces no capability set at all, because a lower bound is indistinguishable from a deliberate policy once it is just a Set.

Capabilities are not roles

Intersecting role labels would be wrong in a way that looks right: two people with different roles may well share a right, and {'admin'} ∩ {'approver'} is empty while both can do the thing. Capabilities are opaque tokens; the role→capability mapping is the grant store's.

Within one principal capabilities union (two roles give you both); across the audience they intersect. The two directions live in separate modules with the reasoning stated in both, because confusing them is a privilege bug either way.

Ordering relative to the two gates already on the path (§5.4)

1. Org security postures with provenance-labelled input screening #579 inbound screening — on the way in, before anything is trusted
2. Audience floor — before an effect is produced or context rendered
3. Privacy Shield — at the data-plane boundary, on whatever survives

The floor precedes Privacy Shield because it decides whether an effect happens; Privacy Shield decides what a permitted effect may carry. Reversing them would mean minimizing data for a call that should never have been made.

Blast radius

Surface	Effect
Published plugin contract	none — additive exports only
Runtime behaviour	none — no guard is wired yet; the three guard sites are the next cut
Database	none — InMemoryGrantStore ships; a persistent store is separate

Verification

• Full suite: 6625 tests, 0 fail, 0 cancelled (19 new)
• npm run typecheck ✅ · npm run lint ✅
• Epic: Integrated dev platform — isolated per-job runners that clone, develop, test, and ship PRs #470 ratchet 3294 ✅ · npm run typecheck never typechecks middleware/test/ #573 ratchet 406/406 ✅

Mutation checks

Mutation	Result
remove the empty-members guard	killed — 1
ignore unresolved members	killed — 2
treat an empty roster as a known empty room	killed — 1
drop the partial-role guard in grants	killed — 2, incl. the end-to-end case

The end-to-end pair is the one that matters: a directory outage closes the floor with a reason, while its healthy-source control twin still opens it — so the test measures the guard rather than an unrelated side effect.

Refs #575

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}