2. The Two Products and the One Contract
Story moment
The boundary readers should remember
GLoops is where the organization does governed work. Ralph is where the executive understands what changed. The Capability API is the only door between them.
Executive Summary
What this chapter establishes
GLoops owns operational truth; Ralph owns executive understanding; the Capability API is the only crossing point.
A clean boundary prevents Ralph from becoming a runtime and GLoops from becoming an executive dashboard.
The API invariants exist but the wire spec and product integration do not.
Many consumers read and invoke one GLoops substrate through four nouns: Capability, Evidence, Receipt, Authority.
Specify the wire contract, expose a dry-run capability, then admit the first consumer.
The mission requires two distinct things that must never collapse into one product.
One sentence: GLoops is where the organization does governed work; Ralph is where the executive meets the organization that does it.
2.1 The boundary, in one table
Section titled “2.1 The boundary, in one table”| GLoops | Ralph | |
|---|---|---|
| Owns | Operational truth | Executive understanding |
| Primary user | The Operator (governs work) | The Executive (directs the organization) |
| Core question | “Can the organization do this, and did it?” | “What’s happening, what matters, what should I decide?” |
| Speaks in | Capabilities, realizations, evidence, receipts, authority, runtime | Organizations, decisions, perspectives, dissent, scenarios, strategy |
| Output | Governed actions + evidence + receipts | Understanding + prepared decisions |
| North star | Intent → governed operational capability | “I am meeting with my organization” |
| Failure mode to avoid | Becoming a GitHub/PR-review point tool | Becoming a dashboard / reporting product |
The Operator and the Executive may be the same person or different people. In a small organization one human is both (today, Zach is both). The architecture serves both cases.
2.2 The Capability API — the one crossing point
Section titled “2.2 The Capability API — the one crossing point”Everything that crosses the boundary crosses here; nothing reaches around it. The Capability API speaks exactly four nouns and deliberately hides every implementation primitive (no loops, realizations, runners, leases, adapters, webhooks).
| The four nouns | Meaning | Owner |
|---|---|---|
| Capability | A durable operational ability, defined by intent + contract, not implementation | GLoops |
| Evidence | Addressable, inspectable proof of what influenced or resulted from an action (grounded / informed / contradicted) |
GLoops |
| Receipt | The immutable record of one decision about an action — the trust substrate | GLoops |
| Authority | Earned, scoped, revocable, auditable permission to act | GLoops mechanics; granted/revoked via Ralph |
A consumer can discover capabilities, read their state (health, readiness, authority), invoke one, consume its evidence and receipts, and express authority. The load-bearing subtlety:
“Invoke” means ask and authorize, never perform. The consumer (Ralph, or the Portfolio Steward) submits intent plus the granting executive’s authorization. The governed execution, the authority check, and the receipt all happen inside GLoops. This is what reconciles “Ralph invokes capabilities” with “Ralph never executes”: invocation is an authorized request; execution is GLoops’.
Five lenses — The Capability API
| Lens | |
|---|---|
| ▣ Current Reality | The invariants are defined (the four nouns, invoke-means-authorize, direction of dependency) in PORTFOLIO_STRATEGY.md §9. There is no wire spec yet, and no integration between the products. |
| ◇ Target State | One stable contract; GLoops evolves capabilities/domains behind it; Ralph (and any second consumer) evolves over it; they synchronize only here. |
| → Migration Path | Write the wire spec as a portfolio decision (transport, sync/async, receipt-update delivery, per-consumer authority scoping, versioning) → ship a dry-run capability behind it → admit the first consumer. |
| ⚖ Executive Implication | A new application — a CLI, a mobile executive app, an MCP integration — is a new client of one API, never a new runtime. The portfolio scales without redrawing the boundary. |
| ☼ Operator Experience | You ask for what you want done in organizational terms; you never learn what a “loop” or a “runner” is. If you do, the API has leaked and it is a bug. |
2.3 What must never leak across the boundary
Section titled “2.3 What must never leak across the boundary”This is the single most important rule for preventing erosion (it has already been violated once — see §2.4).
- GLoops implementation terms never appear in Ralph’s executive language. The executive never sees
loop,realization,ExecutionRequest,runner,lease,adapter,webhook,dry-run. Ralph translates (“the organization reviewed 12 changes,” not “the pr-review loop produced 12 ExecutionRequests”). - Ralph’s executive concepts are never implemented inside GLoops. GLoops emits operational truth; it does not editorialize it for an executive.
- Ralph runs no operational execution runtime. Governed execution is GLoops’ job.
- GLoops makes no executive decisions. It escalates; the judgment of “what should the organization do” belongs to the executive, surfaced through Ralph.
2.4 The honest boundary — and the #1 debt
Section titled “2.4 The honest boundary — and the #1 debt”▣ Current Reality. The boundary is a target, not built software. GLoops and Ralph have no integration and no Capability API between them. Ralph contains its own full operational execution runtime — Foundry (
ralph/foundry/plus theralph/autonomy/stack: sandbox, charter sealing, dispatch, judge panel, gates, run receipts, durable-execution backbone). Foundry is exactly the governed-execution role this manual assigns to GLoops, living in the wrong repo. It is the portfolio’s #1 architectural debt.
→ Migration Path (the convergence gate — concrete, so an agent can act on it). Migrating an operational function out of Foundry into GLoops is authorized only when all hold: (a) GLoops exposes the equivalent capability through the Capability API; (b) that capability is proven on real evidence at receipt parity with Foundry; (c) the cutover is reversible. The defined first step is not a migration — it is for GLoops to ship a “deliver a scoped code change” capability in dry-run, producing receipts behind the Capability API, to establish the parity baseline. Until then, Foundry is tolerated debt — shrink it, never extend it. No new operational-runtime surface goes into Ralph that a generalized GLoops could own.
Chapter closeout
Decision ledger
Key Decisions
- Invoke means ask and authorize, never perform.
- Foundry remains tolerated debt until evidence-gated convergence.
Open Questions
- Capability API wire-level design remains the foundational question.
Related Chapters
- Concept Map - Capability API
- Ch. 5 - Runtime Architecture
- Source Map - Portfolio Strategy