Files

glm-5.1 6b5f32bad4 Add ACL graph architecture spec with principal-agent framework

- 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

2026-05-31 07:11:59 +00:00

2.9 KiB

Raw Permalink Blame History

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:

Inheritance model — Agents "inherit" permissions from principals, with overrides
Intersection/delegation model — Each delegation narrows scope; effective scope is the intersection of the entire chain
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 DelegatesEdges
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 graph architecture specification
Hub agent-roles: /workspace/@alkdev/hub/docs/architecture/agent-roles.md
Operations Identity: /workspace/@alkdev/operations/src/types.ts

2.9 KiB Raw Permalink Blame History