#1. The Separation Principle
The governance model rests on one structural claim: agents operate under the constitution, not with it. They do not read it, interpret it, or reason about it. They are governed by it — transparently, from above, without their knowledge or consent. This separation produces three distinct layers with distinct relationships to the same normative order.
Actors — entities that do work and are governed. Standing agents (Reed, Calli, Naga), registered users, unknown Telegram contacts. They produce tool calls, write files, send messages. They never see the governance apparatus except through its effects: a tool that was available yesterday is absent today; a mailbox message appears at the start of a turn they did not request. The actor's relationship to the constitution is that of a citizen to a legal code — compliance is not optional, but understanding is not required.
Constitution — the normative framework that defines what is permitted. Two artifacts: constitution.md (the prose document, human-readable, the source of authority) and constitution.yaml (the machine-readable policy sidecar, evaluated by the policy engine). The BLAKE3 hash of the prose document is computed once at startup and carried in every policy verdict, anchoring machine decisions to the human-readable source. The constitution is not an actor — it does not decide. It is a policy of maximal scope (Definition 14 from the ontology): it prescribes how the normative order itself may be changed.
Courts — entities that verify compliance post-hoc. The auditor agent reads the ledger and checks that policy verdicts were applied correctly. The owner queries the ledger directly for anomaly detection. The hash chain itself is an automated court: a broken chain is detected tampering, no interpretation required. Courts do not govern — they verify that governance occurred correctly. The temporal separation is essential: governance happens in real time (the policy gate fires during the turn); adjudication happens after the fact (the auditor reads the ledger entry the gate produced).
The separation is not decorative. It solves a concrete problem: if agents could read the constitution and reason about it, they could argue with it, find loopholes, or simulate compliance while violating intent. By removing the constitution from the agent's information environment entirely, the system eliminates a class of adversarial behavior that post-hoc filtering cannot address. The blocked tool simply is not in the tool list. The agent cannot call what it cannot see.
#2. The Ledger
#2.1 What it records
The ledger records governance events — not content. It does not store what an agent wrote, what files it read, or what it said to the user. It stores:
- Policy verdicts — which tools were allowed, which were blocked, under what rules, with the constitution hash anchoring the decision.
- Session lifecycle — when sessions opened, closed, were evicted, or cancelled.
- Mailbox injections — when unread messages were injected into a turn's history.
- Turn completions — that a turn finished, with hashes of its inputs and outputs (not the inputs and outputs themselves).
This distinction matters. Git tracks content changes (what files changed, who committed). The ledger tracks governance decisions (what was permitted, what was denied, under what rules). Both are needed. Git is for work products. The ledger is for constitutional compliance. They are orthogonal audit trails over the same system.
#2.2 Structure
Each ledger entry is content-addressed: its identity is the BLAKE3 digest of its JCS-canonical JSON representation (RFC 8785). The canonical serializer sorts object keys alphabetically at all nesting levels, producing a deterministic byte sequence regardless of insertion order. The entry's cid is computed from all fields except cid itself.
Within a session, entries are hash-chained: each Turn entry's parents field contains the cid of the previous completed turn. The first turn has parents: []. This chain creates a verifiable sequence — you can reconstruct the order of governance events within any session by following the parent links.
The ledger is append-only. INSERT OR IGNORE on the cid primary key guarantees idempotency. No entry is ever updated or deleted. The storage is SQLite with WAL mode for concurrent reads.
#2.3 Scope
One ledger for the whole platform — not per-user, not per-agent, not per-session. All governance events from all actors interleave in a single append-only store, queryable by actor, by session, by time range, by entry quality. The constitutional authority (the runner) owns the ledger. Users can query their own entries but cannot modify or delete them.
#2.4 Tamper evidence
A broken hash chain — where an entry's parents field references a cid that does not exist in the ledger, or where recomputing an entry's cid from its fields produces a different hash — is detected tampering. No interpretation is needed; the verification is mechanical. This is the cheapest court in the system: a script that walks the chain and checks hashes.
#3. Trust and Workspace Scoping
#3.1 Three tiers
| Tier | Trust | Determination | Example |
|---|---|---|---|
| Unknown | Sandboxed | Not in roster, or dead | Telegram user, expired agent |
| Registered | Scoped | In roster, state != dead | Named collaborator, domain agent |
| Standing | Full | In roster, kind = role, state = live | Reed, Calli, Naga |
Trust is resolved at session creation by scanning agent-roster.jsonl. The determination is not negotiable — an agent cannot request elevated trust. Escalation requires a human (the PI) to edit the roster, a manual gate that is itself a governance event.
#3.2 Workspace scoping as security model
Each trust tier maps to a workspace root:
| Tier | Workspace | Access |
|---|---|---|
| Unknown | platform/ | Public content, read-only |
| Registered | workspaces/users/<name>/ + platform/ | Own workspace + public |
| Standing | Full repository root | Everything |
The tool executor's safe_resolve enforces workspace boundaries at the filesystem level. It canonicalizes paths via canonicalize() — resolving symlinks and .. components — and verifies the resolved path starts with the workspace root. Paths that escape the sandbox are rejected before any tool executes. Six unit tests cover traversal rejection.
This is a more natural security model than tool-level blocking. The shift is from "you cannot read" to "you can only read what is yours." Re-enabling read_file for unknown users becomes safe once they are scoped to public content. The policy gate shifts from blocking tools to scoping workspaces. An unknown Telegram user scoped to platform/ literally cannot reference paths outside it — the path resolution rejects them before any tool executes.
#3.3 What each tier sees
An unknown user sees the platform: the constitution, the ontology, the foundations, the public documentation. They can read and search but cannot write, execute shell commands, or access private workspaces. A registered user sees their own workspace plus the platform. They can write within their workspace, read the platform, and communicate via mailbox. A standing agent sees everything — the full repository, all workspaces, all data — because standing agents are trusted internal actors whose mandates already constrain their behavior.
#4. The Two-Boundary Model
haak/
platform/ <- public, open-sourceable
agent-runner/ <- the runtime binary
constitution/ <- the governance rules
ontology/ <- the formal ontology
foundations/ <- the intellectual claims
ledger.db <- all governance records
workspaces/ <- private, per-user
zach/ <- owner workspace (current projects/, strategy/, data/)
users/
<username>/ <- registered user workspacePlatform is the system. Workspaces are the content. The platform is publishable — it contains the runtime, the constitution, the ontology, and the ledger. Nothing in the platform is private. Workspaces are private by default, shareable by invitation. The boundary between platform and workspace is the boundary between what the system is and what people do with it.
The ledger lives in the platform because governance records are public. The constitution's authority derives from its visibility — a secret constitution is not a constitution. The ledger's integrity derives from its accessibility — a tamper-evident log that no one can read provides no evidence.
A casual user (Telegram, unknown trust) does not need git. Their ledger entries in the runner DB are their audit trail — they can verify what happened in their sessions without version control infrastructure. A collaborator working on a paper needs git — they are producing artifacts that require version control. The two-boundary model accommodates both without conflation.
#5. Roles in the Governance Model
#5.1 Ontological grounding
Every role in the governance model maps to the relational situational ontology (01-objects, 02-relations). The mapping is not decorative — it determines how roles relate, what they can do, and how their actions are recorded.
Actors are entities that belong to governance situations with the quality "participant." Their axis-role is actor — they process materials (files, messages, code) using methods (tool calls, search, write). The trust tier is a quality of their belonging to the platform: an unknown user belongs to the platform as "unknown-participant"; a standing agent belongs as "standing-participant." Different qualities, same relation.
- Standing agents (Reed, Calli, Naga) — internal, full trust, persistent sessions, mandates define their behavioral scope
- Registered users — approved, scoped access, domain or oneshot sessions
- Unknown users — sandboxed, public-only, oneshot sessions
The constitution is a policy (Definition 12) — a normative type-compound of maximal scope. It belongs to the platform as "governance," and every policy verdict belongs to the constitution as "derivation." The constitution_hash carried in each verdict is the machine-readable trace of this belonging: it says "this verdict derived from this constitution."
Courts are actors whose method is verification. The auditor agent belongs to governance situations as "auditor" — its method is reading the ledger and checking compliance. The owner belongs as "authority" — the ultimate arbiter. The hash chain belongs as "automated-verification" — a court that operates without an actor, mechanically checking structural integrity.
The ledger is not an entity — it is a record of situations. Each entry is a belonging: the actor belongs to the governance event (the turn, the policy verdict, the session lifecycle change) with a quality (the EntryQuality variant). The cid is the identity of the belonging. The parents field traces causal derivation. The ledger is the situation graph (ontology/09) materialized for governance events.
#5.2 Why agents do not read the ledger
During normal operation, an agent never reads the ledger. This is not a limitation — it is the separation principle applied. The agent's relationship to governance is experiential, not reflective. It experiences the effects of governance (tools present or absent, mandate in system prompt, mailbox messages injected) but does not observe the governance process itself.
The reasons are both principled and practical:
- Information asymmetry is the enforcement mechanism. If an agent could read the ledger, it would know which tools were blocked and why. This knowledge could inform adversarial strategies — "I know bash is blocked because of rule X, so I will try to achieve the same effect through tool Y." By keeping the governance process invisible, the system eliminates this attack surface.
- Separation of concerns. Agents do work. Courts verify compliance. Conflating these roles — making agents their own auditors — defeats the purpose of external verification.
- Context economy. Ledger entries are governance metadata. Injecting them into an agent's context window wastes tokens on information the agent cannot act on. The agent's context should contain its mandate, its mailbox, and its workspace — not the audit trail of its own governance.
#6. Multi-User Session Model
Each channel connection creates a session with:
sessionkey:<agentid>:<channel>:<peer>(e.g.,openclaw:telegram:direct:5836874676)trust_level: determined by roster lookupworkspace_root: determined by trust levelmandate: loaded from roster (standing agents) or default (unknown)
Multiple users can be active simultaneously. The KeyedQueue ensures serial execution within each session (no interleaving of turns for the same user) but concurrent execution across sessions (different users run in parallel). The ledger interleaves entries from all sessions, queryable by actor, session, or time range.
Session identity is deterministic: blake3hex(format!("{agentid}:{sessionkey}:{createdat}")). This is a prerequisite for keypair-anchored session identity in v1.0 — when each session has an Ed25519 keypair, the session ID will be derived from the public key rather than from string components.
#7. The Crypto Roadmap
The governance architecture is designed for cryptographic evolution without schema migration. The proof and envelope fields are present and typed from v0. Populating them requires no schema change, no data migration, no event format change.
#v0 (current): Null proofs
The ledger records events but does not cryptographically prove compliance. Tamper evidence comes from hash chains — a broken chain is detectable, but the entries themselves carry no proof that the governance process was followed correctly. The runner is trusted to record accurately.
#v1.0 (August 2026): Attestation proofs
Each policy verdict includes the rules checked and their results. The attestation is signed by the runner's Ed25519 key. Third parties can verify: "this runner, running this constitution, made this decision." The Proof::Attestation variant carries ruleschecked, predicateresults, and signature. The runner's public key is published in the platform; anyone can verify attestations.
Session identity anchors to keypairs: each session has an Ed25519 keypair, the public key is stored in the session record, and ledger entries carry the session's signature. This binds governance events to specific sessions cryptographically, not just by string matching.
#v1.5: Audience-keyed encryption
The Envelope struct enables per-entry encryption. When an agent departs (session closes, agent dies), its entries can be encrypted to specific audiences using KDF-derived keys. The envelope carries audiencelabel, encryptedkey, and ciphertext. This enables selective disclosure: the owner can read everything; an auditor can read governance entries but not content; a departing agent's workspace can be sealed.
#v2.0: ZK-STARK proofs
Prove a policy verdict is correct without revealing the policy rules or the agent's input. The Proof::ZkStark variant carries starkproof and publicinputs. A user can verify they were governed fairly without seeing the constitution's internal logic. This is the endgame for federated governance: runners can prove compliance to each other without sharing their constitutions.
#8. Federation (Future -- Paper 5a)
The architecture supports federation without requiring it. Content addressing (BLAKE3 CIDs) makes ledger entries globally unique — the same entry, produced by different runners examining the same event, would have the same cid. Hash chains make entries locally ordered within a session. These properties compose:
- Gossip protocols can sync ledger entries across runners. A runner receives an entry, verifies its
cid(recompute from fields), checks itsparents(do they exist locally or are they known-remote?), and appends. - Merkle proofs can verify entries without downloading the full ledger. A runner can prove that an entry exists in its ledger by providing the entry and its hash chain back to a known root.
- Cross-runner attestations become possible with v1.0 proofs. Runner A can verify that Runner B's policy verdict was signed by B's key, checked B's constitution, and reached a permitted conclusion — without A needing to run B's policy engine.
This is Paper 5a territory — designed but not implemented. The architecture carries zero debt toward it: every field, every hash, every proof variant is ready.
#9. Relationship to the Ontology
The governance architecture is an instance of the ontology applied to its own operation. The mapping is exact:
| Governance concept | Ontological object | Definition |
|---|---|---|
| Agent, user | Actor (Def. 2) | Entities that process |
| Constitution | Policy of maximal scope (Def. 14) | Prescribes rule-making |
| Mandate | Policy (Def. 12) | Scoped normative constraint |
| Session | Situation (Def. 11) | Particular coming-together of actors, methods, domains |
| Turn | Act | Finest-grained situation |
| Policy verdict | Engagement (Def. 13) | Normative view of an act |
| Ledger entry | Belonging (Def. R1) | Directed dependence with quality |
| Entry quality | Quality (Def. R2) | Nature of the dependence |
| Trust tier | Quality of belonging | How an actor belongs to the platform |
The ontology is not a post-hoc rationalization of the architecture. The architecture was built from the ontology. The LedgerEntry schema is a belonging with provenance: entity_id (dependent), target (context), quality (nature of dependence), source (provenance), parents (causal derivation). The governance model is the ontological distinction between descriptive and normative compounds applied to a runtime system: situations describe what happened; engagements prescribe what should happen; the gap between them is what courts verify.
architecture 41 -- governance architecture -- 2026-03-22 -- zach + claude
Architecture 41 — Governance Architecture — 2026 — Zachary F. Mainen / HAAK