REL-CAP-HUM: Capability ↔ Human

Stable ID: REL-CAP-HUM
Entities: CAP (Capability) ↔ HUM (Human)
Relationship status: implemented

Audited relationship

Human capabilities are derived from group-role membership.

Design

Canonical Subject edge. Humans are the Subject of the permission system — the only entities that hold Capabilities. Cardinality: M:N — one Human holds many Capabilities (the union across every Role they have via every Group they join), one Capability is held by many Humans (every Human in a Group whose Role bundles it).

Mechanism is transitive (Human → joins Group → carries Role → bundles Capability), but the Subject fact is direct: "this Human has this Capability." Agents do not hold Capabilities — they are the Resource the permission system governs, not the Subject. Tools check against the Subject (the Human triggering the invocation), never against the Agent executing it. Effective Capabilities are identical across every Agent on the Server — no per-Agent narrowing.

Implementation

Canonical path in code: users → group_members → groups → group_roles → roles → role_capabilities → capabilities. Runtime entries in packages/trust/src/queries.ts:

• getUserCapabilities(userId) → string[] — union across every Group the user is in; sole source for buildEnvelope.
• findUsersWithCapability(capabilitySlug) → userId[] — server-wide lookup; used by routeApproval to resolve prove_it approvers (every Human holding approve_destructive_actions).
• findUserHighestRoleSlug(userId) → slug | null — display / legacy actorRole; ranks across all Group memberships.

Every Human — including the owner — walks the Capability path through buildToolPolicyFromCapabilities. The owner Role's seeded bundle carries the full release-current Capability catalogue, so the owner's toolPolicy map covers the full catalogue.

Verification state

This article remains at the original relationship granularity for AI and maintainer use. Its current-versus-target classification was reconciled before migration; public code-anchor verification remains in progress against Nautilo 4b3ea604.