# #21–#22 — Truth and Sovereign Tiers: the BFF-by-BFF interface catalog
Scope: How an operator reaches the platform through four tiers — the runtime BFF, the truth-graph engine, the edge API, and the console. What capability each tier exposes, what guards every interface, and where the tiers call each other. Methodical capability descriptions, not a file or data-model inventory. Audience: operator + developer. Status: As of 2026-11-09. Sources (cited inline throughout): platform tier split + truth-graph routes; truth-graph master index; edge-API README and route surface; console zero-trust guidance; identity/vault design guide. Code and product-map paths appear only in citations.
1. How the tiers divide the work
The platform is deliberately split so each tier has one job (source: platform tier split in the operating guide; edge-API README).
| Tier | Where it runs | Premise |
|---|---|---|
| Agent (runtime) BFF, port 3030 | Container runtime | Long-running work: messaging, conversational sessions, attestation, truth proxying, workflow dispatch. |
| Truth BFF, port 3031 | Container runtime | Graph and governance engine: graph CRUD, traversal, search, scope checks, claim lifecycle coordination. |
| Sovereign API, port 3040 | Edge (serverless) | Stateless edge: authentication, tenants, vault health observations. Local Surreal endpoints are not reachable from the edge — a public endpoint is required for edge deployment (source: operating guide). |
| Sovereign Console, port 10300 | Edge (static SPA) | The operator's browser: two configurable endpoints (edge API and runtime BFF) so the console can talk to whichever tier owns a capability (source: tier split; console zero-trust guidance). |
For an operator, the rule of thumb is: if it needs to wait, stream, or coordinate, it lives on the runtime tier; if it needs to answer immediately without state, it lives on the edge. The truth proxy (Section 5) is the one explicit bridge between the two philosophies.
2. Agent BFF (port 3030) — interfaces by capability
The runtime tier is the product surface. Each row below is one capability group: what the operator or integrator can do, and the guard that stands in front of it (source: operating-guide key-routes table; ready/protocol posture).
| Capability group | Purpose for the operator / integrator | Guard |
|---|---|---|
| Manifests + CNS catalog | Discover what a provider or workspace can do; resolve effective permissions and egress; verify that a requested interface is lawful. | Dev/session auth; local dev may use the dev_<user> bearer form. |
| PoCE governance paths + envelopes | Start a path session, record a step, finalize and retrieve the signed evidence envelope; verify chains and sweep governance state. | Governance checks + proof-of-execution recording; failures logged, never silently approved. |
| Dialog sessions | Create a session, answer prompts, submit — the conversational contract. | Session auth middleware. |
| Segments sync + leases | Authorize, snapshot, catch up, and revoke segment leases for offline-capable clients. | Lease authorization enforced server-side. |
| Subscriptions | Authorize access gated by a live commercial-subscription check. | Commercial billing status must be current. |
| Commerce + billing | Subscription lifecycle, subscribers, notices, products, invoices; parties, payment methods, provider webhooks and customer sync. | Billing gate (financial checks) before downstream actions. |
| Sovereign accounts | Register and read sovereign accounts. | Session auth. |
| Federation registry + sync | List federation peers, sync records, report publish status. | Federation policy checks. |
| Virtual paths | Browse and traverse virtual path hierarchy. | Traversal guards. |
| Attestation (AaaS) | Capabilities, sessions, human-in-the-loop, scoring, registration, callouts. | Attestation session rules; inbox intentionally unimplemented where the capability is not yet contracted. |
| FSM command plane (Mayet) | Manage finite-state definitions, bindings, mandates, and transitions; verify signatures. | FSM execute mode dispatch (enqueue locally, connect to the engine when configured). |
| Standing orders | Create, read, tick inventory, trigger orders; JetStream consumer management. | Trigger path requires PoCE evidence where governed. |
| Vault BBS+ (credentials) | Store encrypted file credentials, present and share them, verify presentations, back up secrets; public grantee verification. | Zero-knowledge handling; server holds blind ciphertext only. |
| Core subsystem | Day-to-day operations for users, organizations, teams, agents, affiliations, security sessions, notifications, attachments, and PoCE-bridged lifecycle events. | Role/permission checks plus PoCE bridging for governed transitions. |
| Compliance gates + geo publisher | Register and evaluate declarative compliance gates; publish geo-targeted events, manage regions, boundary checks, and standing orders. | Gate evaluation must pass before regulated actions proceed. |
| Truth proxy | Forward all truth-graph calls to the engine tier (Section 5). | Vault-scope + transit-trail headers required (Section 5). |
Operational notes for the runtime tier
- Fail closed. Any failure reaching infrastructure (messaging fabric, databases, workflow engines, solver services) returns a server error or refusal — never a synthetic success object. Contract mismatches return a client error (source: operating-guide mandates).
- Event-driven, not polled. Background work is queued as durable events and published through the messaging fabric; sweep endpoints exist only as dev recovery (source: operating guide).
- Declarative configuration. Lookups, templates, and scenarios are served from the message fabric's key-value store at runtime; disk files are only read by the offline seeder (source: declarative-first mandate). Runtime services must never read lookup/template files from the filesystem.
- No bespoke stores. Domain entities are expressed through the canonical primitives; an entity that cannot be expressed must stop for human review rather than inventing a new store (source: zero-bespoke-tables mandate).
- No synthetic data. UI cards and metrics must come from live backends or render an honest empty state — never invented numbers or placeholder payloads (source: no-synthetic-payloads mandate).
- Observability. The runtime tier registers platform metrics middleware; proof-of-execution tracing modules ship alongside it, and the engine tier exposes health probes (edge health, cross-node health, and the kernel-trail health probe) (source: operating guide; engine route surface).
3. Truth BFF (port 3031) — interfaces by capability
The truth tier is the graph and governance engine. Base path names the truth-graph version family; every truth interface sits under it (source: truth-graph master index).
| Capability group | Purpose | Guard |
|---|---|---|
| Graph node lifecycle | Create, patch, and delete nodes — the atomic unit of knowledge. | Vault scope + transit trail (below). |
| Graph edge lifecycle | Create edges with strength, evaluation mode, conditions, and canonical naming. | Vault scope + transit trail; canonical names resolve through the naming registry. |
| Traverse + subgraph | Walk the graph in an explicit direction ("outgoing", "incoming", or "both") with depth and strength bounds; extract bounded subgraphs. | Vault scope; expired leases stop traversal at the boundary. |
| Semantic search + indexing | Search meaning, index nodes for retrieval, and geo-search via coordinate + haversine distance. | Vault scope; retrieval respects scope boundaries. |
| Mutation queue + sweep | List pending graph mutations, drain them, and sync the search index after claim/node/edge changes. | Sweep is idempotent; processing happens in the sweep, never inside event bodies. |
| Governance sweeps + verification | Sweep callouts and the platform, verify authority chains, enumerate invariant checks. | Authority-chain verification is bounded and fail-closed. |
| Vault access checks | Answer, for a given scope claim, whether access is granted — including lease validation. | Scope headers (below). |
| Claim lifecycle | Create, transition, and finalize claims with proof-of-execution attachment; list lifecycle events. | Transit trail for federated mutations. |
| Blueprint install + search | Install declarative blueprints that wire subsystems to scopes; search installed blueprints. | Governance approval where the blueprint requests it. |
| Template + plugin evaluation | Apply templates and evaluate named plugins over graph state. | Scoped execution, rate limited. |
| DDE-adjacent (query exec, classify, catalog) | Powerful read/classify paths for governed consumers. | Same guard chain as graph interfaces. |
| Meta registry + health probes | Describe the registry surface and report engine health in three dimensions (base, cross-node, kernel trail). | Unauthenticated probes; sensitive surfaces remain guarded. |
Guard chain (applies in sequence to every graph request)
- Rate limiting on traversal and commerce paths (source: engine route surface).
- Vault scope — the target vault is named by
X-Vault-Scope; the caller's scope (X-Caller-Scope) defaults to the target and is required when it differs; all graph operations require the target scope (source: vault-scope middleware; operating guide). - Jurisdiction guard — geo/policy constraints evaluated before execution.
- Transit trail — federated or cross-scope mutations must carry a valid verification trail; local development and tests may skip only with an explicit skip flag (source: transit-trail guard). The guard also examines distributed-trace headers and provenance/upward-chain headers and enforces a minimum trust grade.
Search and index posture
The index supports semantic search and nearest-neighbour retrieval at high dimension, with an on-demand graph index for efficient lookup and a brute-force cap when the graph index is not yet built (source: truth-graph master index). Geographic search uses coordinates plus a manual haversine computation; the database engine in use does not support a native spatial index type, so that path is intentionally manual. Blueprint installation and subsystem wiring are delivered capabilities: installing a blueprint can provision subsystems, evaluate scope rules, and materialize them declaratively. Vault leases govern traversal: a traversal stops when it crosses a scope without a live lease.
Event and relay posture
Graph mutations are staged as durable events and drained by a sweep that syncs the index; the messaging outbox relays them to the fabric for durable subscribers (source: truth-graph master index). Inline event bodies may only append a durable record — they cannot call custom logic — so all real processing happens in the sweep and the relay.
4. Sovereign API (port 3040) — the stateless edge
The edge owns exactly three product families; everything long-running is a 404 with a pointer to the runtime tier (source: edge-API README and route surface; tier split).
| Capability group | Purpose | Guard |
|---|---|---|
| Authentication + tenants | Register, log in, read the caller's profile, list tenants. | Local development uses database credentials; cloud uses a bearer token; queries bind parameters safely (source: README). |
| Vault health (AfiyaLink) | Sessions, observations, documents, FHIR export, professional sharing. | Strict-encryption mode rejects weak stubs and requires audited encrypted envelopes; the edge proxies heavy sync to the runtime tier by default (source: console zero-trust guidance; operating guide). |
| Zero-trust data collaboration (ZTDS) | Create encrypted collaboration series; grant read/write leases; append-and-make-current versions; manage escrow and delegate/proxy leases; handle blind access requests and a sealed inbox (drop-off and claim). | Append-only audit; encrypted payloads validated before storage; strict mode guards clinical payloads. |
| Supporting surfaces | Claim schemas, employment, travel, object storage, and a low-level client surface. | Tenant-scoped access. |
| Identity design (UIC + BBS+) | Sealed minting, endorsement, revocation, anchoring, threshold co-signing, selective-disclosure presentations; information-vault file/share/verify; attestation co-mint with passphrase backup and a public verifier UI. | Cryptographic threshold and pairing-based verification; server stores no key material. |
Zero-trust contract (health): the browser encrypts before anything reaches a server — the server stores metadata plus an opaque ciphertext envelope only; session key registration is the single bridge to the runtime tier (source: console zero-trust guidance). Collaboration contract (ZTDS): a series owner grants write access via a lease; each grantee append preserves immutability and is audited; escrow implements a dead-man's switch with heartbeat, guardian release, and cancel; delegate leases allow proxy signing (source: operating guide; edge route surface).
5. Console (port 10300) — the operator's browser
The console is a static single-page application. Two environment variables connect it to the two API tiers (VITE_API_URL for the edge, VITE_AGENT_BFF_URL for the runtime tier) (source: tier split).
What it does, methodically:
- Health capture — vitals and medical documents are encrypted client-side (key wrapping, Shamir threshold recovery shapes, credential-enforcement and delegation helpers) before any data reaches a server (source: console zero-trust guidance; crypto package layout).
- Vault verification — a public verifier surface lets a holder present and a grantee verify credentials without trusting the presenter (source: identity/vault design guide).
- Operator workflows — claim design, workflow design, dashboards rendered strictly from live backend responses (no hardcoded metrics).
- Delivery shape — development binds a local name only, so the address used is the local name rather than a numeric loopback (source: operating guide).
6. Critical cross-calls
Truth proxy (runtime → engine). Every truth-graph request the runtime tier serves is proxied to the engine tier (docs/commercialization-adjacent operating guide: truth proxy; engine guards). Two headers are load-bearing:
X-Vault-Scope— required on every truth operation. It names the vault the request is allowed to touch.X-Caller-Scope— optional, defaults to the target scope; required when it differs, so a cross-scope call must declare itself.
Federated mutations additionally require a valid transit trail X-Transit-Trail; without it (and without the explicit local skip flag) the engine refuses. The engine composes its guards in order — rate limit, vault scope, jurisdiction, transit trail — and the commerce path reuses that same chain (source: engine route surface; transit-trail guard).
Edge → runtime syncs. The edge proxies observation/chunk sync and session-key registration to the runtime tier by default, so encrypted health data lands where the long-running machinery lives (source: operating guide; zero-trust guidance).
Event spine. Durable outbox records are published to the message fabric and consumed by durable consumers (audit, PoCE staging, standing orders) — no polling loops anywhere in the happy path (source: truth-graph master index; operating guide).
7. Open items (honest gaps)
- The engine's dedicated API-description file is thin and points at a shared description rather than documenting every interface; several governed-route families are inventoried but not individually detailed (source: engine README; route surface).
- The edge tier's full clinical-service surface was reviewed only through its zero-trust guidance and route families; additional implied endpoints are not asserted.
- Precise sweep frequency and index-build scheduling are operational details outside the cited sources.
- Whether the edge owns a dedicated API-description file at all could not be verified from the reviewed materials.