feat(#333): role sources + pluggable role→holder resolution (phases 2 and 3)

[Weegy]

Phase 1 (#724) answered who a turn's caller is. This answers the other half of the question the Phase-0 spec (§6) assigns to #333 — "and what are they entitled to?" — as the pluggable registry over role/attribute sources (Entra groups, Odoo HR) that the spec's artifact table calls for, generalizing auth/providerRegistry.ts.

Nothing here evaluates a permission. These are facts; #575 turns them into decisions. The boundary stays exactly where the spec drew it:

#333 produces Principals. #575 consumes Principals and produces decisions.

Conductor's RoleResolver becoming external is phase 3 and is deliberately not in this cut — 4 files, reviewable.

The property everything else hangs on: absence is a type

rolesFor never returns a bare array:

Outcome	Means
resolved, roles: []	the source knows this principal and confers nothing — a real, trustworthy answer
unavailable	we could not find out

Collapsing the two is an authorization bug in whichever direction the caller guesses:

• read as "this user has no roles", an unreachable Entra tenant quietly strips every entitlement — a self-inflicted outage that looks like policy;
• read as "unknown, so allow", it is a silent full grant.

AggregateRoleLookup.partial carries that distinction through the merge, so a half-answered lookup cannot pass for a complete one. The dangerous case is not the empty result — it is a non-empty result that is silently missing a source, which a caller glancing at roles alone would accept. Same reasoning that made ScopeId's unscoped and Principal's undefined types rather than values.

Three further deliberate behaviours

The catalog/registry split is mirrored from ProviderRegistry — and matters more here. That file's rationale is that "a compromised admin can never enable a provider the operator didn't intend". An auth provider decides whether you get in; a role source decides what you are once inside. Registering one silently is privilege escalation with no login event to notice, so the two-tier gate is mandatory rather than decorative.

A throwing source degrades to unavailable instead of rejecting. One misbehaving directory must not fail a turn — but it must not vanish either, so it still lands in bySource and still sets partial. Sources are queried concurrently; they are independent network reads on a turn's hot path, and serialising them would add every directory's latency together.

A role: principal short-circuits with no source consulted. Asking what roles a role has is a category error — a role is an indirection over holders, not a subject with entitlements — and answering it would invite a source to invent role nesting that #575 has not specified. It resolves partial: false: a complete answer, not a failed one.

Role keys are canonicalized with phase 1's role rule (trim only, case preserved). Lowercasing would stop matching the mixed-case keys createRole writes verbatim.

Blast radius

Surface	Effect
Published plugin contract	none — additive exports only
Runtime behaviour	none — nothing constructs a registry yet; this is the seam, its consumers come with #575
Database	none
Existing call sites	none touched

Verification

• Full suite: 6590 tests, 0 fail, 0 cancelled (16 new)
• npm run typecheck ✅ · npm run lint ✅
• Epic: Integrated dev platform — isolated per-job runners that clone, develop, test, and ship PRs #470 core-decoupling ratchet: held at 3294 ✅
• npm run typecheck never typechecks middleware/test/ #573 test/scripts typecheck ratchet: 406 known, no regressions ✅

Mutation checks

Mutation	Result
an unavailable source no longer sets partial	killed — 3 tests
remove the role: short-circuit	killed — 1 test
activate admits an uncatalogued id	killed — 1 test

Refs #333

---

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

[Weegy]

Phase 3 pushed onto this branch

The PR now carries both remaining #333 phases. Phase 2 (role sources) is described above; phase 3 completes the artifact the spec assigns to #333 — Conductor's RoleResolver becoming external, which roleStore.ts:22 has called "a follow-up" since US5.

Phase 3 is a security fix, not just a seam

Holders used to come only from conductor_role_assignments, so a partially known holder list could not exist. Making holders pluggable creates that state — and two decisions built on the list turn out to fail open once it can be incomplete:

Decision	With a shrunken list
authorization gate (is this responder a holder?)	rejects a genuine holder	fail-closed, left unchanged
quorum='all' completeness	completes with too few approvals	fail-open → fixed
"no holder → take the fallback"	skips the human step entirely	fail-open → fixed

The quorum case is the sharp one: every holder still visible may have answered while the people an unreachable directory knows about were never asked, so a four-eyes approval silently becomes two-eyes. The pre-existing required.length > 0 guard covers only the empty list — the partial one is dangerous precisely because it looks legitimate.

Both now fail closed: the quorum refuses to complete and the run stalls to its deadline fallback, and openHumanAwait parks the await rather than bypassing the approval.

No behaviour change until someone opts in

With no external source configured there is exactly one source and partial is never true, so today's deployments are byte-for-byte unchanged. The local assignment table is registered as an ordinary RoleHolderSource rather than special-cased — one merge path, and it gets the same throw-becomes-unavailable handling as any remote directory. An external source may not claim the reserved conductor-local id; that would substitute its own approver list, so it is a boot-time collision.

Verification

• Full suite 6606 tests, 0 fail, 0 cancelled (30 new across both phases)
• Typecheck ✅ · 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 check: removing the partial guard from the quorum kills exactly the new REFUSES to close when the holder list is partial test and nothing else — its partial: false control twin still closes, so the test is measuring the guard rather than an unrelated side effect.

Existing executor fixtures were updated to the richer resolver shape; they had been injecting bare arrays.