glm-5.1
6b5f32bad4
- New acl.md: AclGraph Module definition (PrincipalNode, ResourceNode, DelegatesEdge, ScopesEdge, MemberEdge), principal-agent hierarchy with no-escalation invariant, setup-time vs runtime separation, multi-parent aggregation rules, cycle detection, scope semantics - ADR-034: ACL as metagraph (not domain-specific tables) - ADR-035: Actors become PrincipalNode entries, standalone table removed - ADR-036: Principal-agent as DelegatesEdge with scope narrowing - ADR-037: Setup-time definitions seed graph types, runtime instances are separate graphs - Resolve OQ-03 (actors table design) — actors become ACL nodes - Add OQ-20 through OQ-25 (delegation expiration, evaluator location, graph instance lifecycle, BelongsToEdge derivation, identityId references, scope string semantics) - Update README.md and overview.md to reflect new doc and ADRs - Note: multi-tenancy / graph scoping problem (no ownerId/scopeId on graphs table, no identity tables at this level) still needs resolution — identity and org tables will likely need to be added at this level for referential integrity
44 lines
2.9 KiB
Markdown
44 lines
2.9 KiB
Markdown
# ADR-036: Principal-Agent Relationships as Delegation Edges
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The principal-agent framework from legal theory maps directly to the hub's access control model:
|
|
- A principal delegates authority to an agent
|
|
- Liability flows upward (the principal is responsible for the agent's actions)
|
|
- Permissions flow downward (an agent's effective permissions are a subset of the principal's)
|
|
- No escalation: an agent cannot have higher privilege than any ancestor in the delegation chain
|
|
|
|
In the hub, this maps to: a coordinator (principal) spawning an implementation specialist (agent), or a human (principal) delegating scope to an LLM session (agent).
|
|
|
|
Three modeling approaches:
|
|
1. **Inheritance model** — Agents "inherit" permissions from principals, with overrides
|
|
2. **Intersection/delegation model** — Each delegation narrows scope; effective scope is the intersection of the entire chain
|
|
3. **Capability model** — Each principal directly grants a set of capabilities to each agent, no chain traversal needed
|
|
|
|
## Decision
|
|
|
|
Principal-agent relationships are modeled as `DelegatesEdge` edges in the ACL graph, using the **intersection/delegation model**. Each edge carries `narrowedScopes` (and optionally `narrowedResources`) that represent the subset of the principal's authority transferred to the agent.
|
|
|
|
Effective scope computation: starting from the root principal, traverse the delegation chain, intersecting `narrowedScopes` at each step. The result is always a subset of the root principal's scopes, guaranteeing the no-escalation invariant.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- The no-escalation invariant is structurally guaranteed by the intersection algorithm — it's impossible for a leaf node to exceed a root node's authority
|
|
- Delegation chains are auditable — you can trace any agent's authority back to the root principal by following `DelegatesEdge`s
|
|
- The same graph structure supports multi-level delegation (user → coordinator → implementer → subagent) without special-case logic
|
|
- Compatible with the hub's existing `sessions.parentId` model — a session's parent is the principal's session, and the delegation edge in the ACL graph records what was delegated
|
|
- `narrowedScopes` on the edge provides explicit, auditable delegation records — you can answer "what did principal P delegate to agent A?" by reading one edge
|
|
|
|
**Negative:**
|
|
- Chain traversal at call time: computing effective scopes requires walking the delegation chain. For deep chains this could be slow. Mitigation: cache effective scopes per identity per graph, invalidate on edge mutation.
|
|
- The delegation chain must be acyclic. Cycle detection is enforced at edge creation time (consistent with `allowSelfLoops: false` in AclGraph Config).
|
|
|
|
## References
|
|
|
|
- [acl.md](../acl.md) — ACL graph architecture specification
|
|
- Hub agent-roles: `/workspace/@alkdev/hub/docs/architecture/agent-roles.md`
|
|
- Operations Identity: `/workspace/@alkdev/operations/src/types.ts` |