Appendix A - 4. Role-typed dispatch

The Structure of Role-typed dispatch — its shape at a glance:

The role is a small closed enum. Each value maps to one policy tuple (model, isolation, gates), and downstream enforcers refuse a call whose declared role doesn't match.

flowchart LR
  Dispatch[/--role r/] --> Enum{{Role enum}}
  Enum -->|maps to| Tuple["Policy tuple<br/>model · isolation · gates"]
  Tuple --> Enforcer{Enforcer at gated op}
  Enforcer -->|role matches| Run([Operation proceeds])
  Enforcer -->|role mismatch| Deny([Refused])

Accessible description: a dispatch declares a role drawn from a closed enum; the enum maps to one policy tuple of model, isolation, and gates; an enforcer at each gated operation lets the call proceed when the role matches and refuses it when it does not.

Projected from the catalogue entry context-and-dispatch / Role-typed dispatch.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Dispatch every agent under a typed role (sonnet-active / opus / lint-runner / commit-slave) that determines its LLM, isolation mode, permissions, and which gates apply, so those choices are policy-by-type, not a per-dispatch judgment call.

Motivation

Every dispatch bundles several correlated decisions: which LLM (Opus for architecture, Sonnet for mechanical work), whether the agent runs in an isolated worktree or on main, and which compute gates it must respect. Made ad hoc, these decisions drift apart from the work: a Sonnet gets pointed at an architecture change whose incorrect output would cause an incident; a commit agent runs in a worktree when it needs to be on main for the hook to fire; a resource-hungry agent runs the aggregate lint it should never trigger. The failure recurs on every dispatch and is invisible until the wrong-tier output ships or the gate is bypassed.

Applicability

• A role registry: the closed enum plus its policy tuple. Free-form role strings reintroduce the drift the mechanism removes.
• Enforcers that read the role at each gated operation (via an env var like ADA_TOOL_AGENT_ROLE), so a mis-roled agent is refused rather than merely mislabeled.
• A dispatch wrapper that is the sole way to set the role, so it cannot be set inconsistently.

Structure

The Structure diagram appears at the top of this page.

Sample Code

A role is a typed enum bound to one policy tuple. Declaring the role once binds the whole bundle; an enforcer at each gated operation reads the declared role and refuses a mismatch, so the correlated choices cannot silently diverge.

from dataclasses import dataclass
from enum import Enum

class Role(Enum):
    WORKER = "worker"       # mechanical, isolated
    ARCHITECT = "architect" # design/RCA, isolated
    LINT_RUNNER = "lint"    # may run the aggregate sweep
    COMMITTER = "committer" # runs on the main line so the commit hook fires

@dataclass(frozen=True)
class Policy:
    model: str
    isolated: bool
    may_run_aggregate_lint: bool

POLICY = {
    Role.WORKER:      Policy("small", isolated=True,  may_run_aggregate_lint=False),
    Role.ARCHITECT:   Policy("large", isolated=True,  may_run_aggregate_lint=False),
    Role.LINT_RUNNER: Policy("small", isolated=True,  may_run_aggregate_lint=True),
    Role.COMMITTER:   Policy("small", isolated=False, may_run_aggregate_lint=False),
}

def enforce_aggregate_lint(role: Role) -> None:
    if not POLICY[role].may_run_aggregate_lint:      # the gate refuses the wrong role outright
        raise SystemExit(f"role {role.value} may not run the aggregate lint")

Consequences

• A closed enum is rigid. A task that fits no role forces a mis-fit or a new role. The enum's virtue (no per-dispatch drift) is also its cost (no per-dispatch flexibility).
• The role leaks. ADA_TOOL_AGENT_ROLE propagates into subprocesses; the build-pool agent must not export it or it trips the role guard in a downstream deploy. The type that fixes dispatch policy also becomes ambient state that has to be special-cased.
• Declaring ≠ matching. A role fixes LLM/isolation/gates but does not verify the work suits the role: a Sonnet mis-dispatched onto an architecture change still ships. Routing judgment (Opus vs Sonnet) stays with the human; the role only makes the choice legible and enforceable, not correct.
• Bypassable via the orchestrator-check escape (audit-logged).

Example use within DocAble

• The four roles above (sonnet-active / opus / lint-runner / commit-slave).
• The aggregate lint runner's role-enforcement policy gate that refuses sonnet-active.
• A dispatch rule: commit-slave operates on main directly (no isolation), unlike every other role.
• Build-pool exception: the build-pool agent must not export ADA_TOOL_AGENT_ROLE (it would propagate into deploy subprocesses and trip the role guard), a documented edge of the same enforcement.

Related Patterns

• Consumer — pre-commit-hook: the commit path consumes the role fixed at dispatch; the commit-slave role is shaped precisely so the hook fires.
• See also (complement) — brief-linting: checks the brief carries the isolation marker the role implies.
• See also (complement) — dynamic-context-injection: the other dispatch-time input (content), where role is the dispatch-time policy.