gov arch w ocaps

Governance Architecture with Endo Object Capabilities

Core thesis

Authority is a reference. A steward holds a capability — an unforgeable Endo object reference — not a database role flag. This is the Dr. SES model of object references as electronic rights. Handing someone authority means passing them a Remotable reference. Revocable authority is handed out through a CareTaker wrapper; revoking it disables the wrapper's target so that all later calls through that wrapper fail. Merely dropping a local reference does not revoke copies held elsewhere.

Layers

┌───────────────────────────────────────────┐
│            Governance UI                   │
│  CLI, web — whatever makes governance      │
│  legible to stewards                       │
├───────────────────────────────────────────┤
│         Audit Layer (Horton)               │
│  Proxy/stub interposition for who-blame    │
│  attribution across delegation chains      │
├────────────────────┬──────────────────────┤
│  Capability Layer  │   Value (ERTP)        │
│  (Endo Far/makeExo)│   Purses, Mints,      │
│  Roles, Facets,    │   Payments, Escrow    │
│  CareTaker revoc'n │                      │
├────────────────────┴──────────────────────┤
│        Persistence Layer                   │
│  Pet daemon formula graph (gov records)    │
│  + GnuCash SQLite (ledger)                │
└───────────────────────────────────────────┘

Each layer is a dependency of the one above it. Implementations build them bottom-up, then exercise them top-down.

Capability patterns for governance

OCap pattern	Governance use
Facet — restricted interface	Steward role that can only review, not appoint
CareTaker — revocable wrapper	Revoke a delegation; downstream calls fail
Sealer/Unsealer — attestation	Gift-wrap identity attribution (Horton)
Petname — local, personal name	"my domain steward" not "Alice's DN"
Synergy — combine designation + bearer token	GitHub username + OAuth → mergePR() session
Bearer token — unguessable URL is the capability	Charlie URL bootstrap, session cookie; see Magic Link and Pre-Signed URLs

All authority in the system is a capability — including external accounts. A GitHub session is a bearer capability for mergePR(), pushCommit(), etc. A mailbox session is a bearer capability for readMessage(id), listMessages(), etc. Handing someone a governance role is the same operation as emailing them a Charlie URL: you're sending a capability reference through an existing bearer channel.

For background, see Capability Patterns and Endo.

Audit (Horton)

OCap systems are anonymous by default — a reference carries no "who." Horton adds attribution by interposing proxy/stub pairs between mutually suspicious parties. Each proxy logs outgoing messages tagged with the sender's identity; each stub logs incoming messages tagged with the recipient's. Sealer/unsealer gift-wrapping prevents blame forgery.

Our decision recording and chain-of-delegation stories use Horton interposition between every pair of steward roles.

Value (ERTP)

Contribution attribution, bounty escrow, and treasury operations all use ERTP — the same ocap discipline applied to digital assets. ERTP purses are governed by capability references: a DepositFacet (widely shareable) lets anyone deposit; the Purse itself (closely held) is needed to withdraw.

This makes bounty escrow a smart contract: software-enforced rights exchange among parties that may not otherwise trust each other. An initial implementation can build on the existing ertp-ledgerguise layer (GnuCash-backed ERTP), then upgrade to full Endo ERTP with real purses and mints.

Bootstrap (there is no identity layer)

There is no separate identity system. All authority is a capability:

• A GitHub session is a bearer capability for mergePR(), pushCommit(), etc. The session is produced by Synergy: account + OAuth token → session.
• A mailbox session is a bearer capability for readMessage(id), listMessages(), etc. Produced by Synergy: username + password → session.
• A governance role is an Endo reference capability for approveDeliverable(), delegateRole(), etc.

An email address is a designation — it names the mailbox but exercises no authority. Same for a GitHub username. In ocap terms, a designation is just data; the capability is the session that lets you act.

Bootstrap is capability hand-off between bearer domains using the Charlie URL pattern:

1. Lead steward creates a governance capability for Bob (an Endo Far reference)
2. Wraps it in a bearer token (Charlie URL)
3. Emails the URL to Bob. The email channel provides confidentiality — only Bob's mailbox session can readMessage(id) to see it
4. Bob opens the URL; the governance capability deposits into Bob's session
5. Bob now holds the governance capability

Bob's ability to read the message at his mailbox is the proof. No PKI, no OAuth ceremony — the mailbox session capability is the authentication.

Over time, petnames accumulate: "bob's governance cap" is a local label we assign after the hand-off. See petnames in awesome-ocap.

Charlie URL pattern

The Charlie URL (bearer token URL) is a standard ocap bootstrap pattern: generate a high-entropy random string, encode it in a URL, and send it via a channel the recipient already controls. The URL is the capability: whoever holds it exercises the authority. The email channel provides the confidentiality guarantee that only the intended recipient receives it.

This is isomorphic to bobMailboxSession.readMessage(emailId) — the mailbox session is the capability, the email ID is the argument. The Charlie URL is the payload inside that message.

Persistence

Two stores:

• Endo pet daemon formula graph — immutably records governance events (appointments, delegations, attributions). Content-addressed SHA-512 DAG. Source of truth.
• GnuCash SQLite — double-entry ledger for balances. Derived view of the formula graph for accounting purposes.

See design/persistence. An initial implementation can use the flat-file fallback and GnuCash SQLite, then introduce the formula graph.

How / Why DAG

If story S motivates design issue D — i.e., D is the technical approach for achieving S — then:

• D answers How do we do S? — D is the architectural reasoning that shows how to build the behavior S calls for
• S answers Why do we do D? — S is the customer-visible goal that motivates the design work D captures

The full chain from vision to code, reading top-down (How?) and bottom-up (Why?):

Vision
  ↑ Why? ↓ How?
Milestone
  ↑ Why? ↓ How?
  Stories  ←→  Design issues
  ↑ Why? ↓ How?
    Implementation tasks

Top-down reads "how": How does this milestone deliver a working slice? Bottom-up reads "why": Why does the initial slice use ertp-ledgerguise?