Architecture — Design Thesis and Planes (Developer Concept Doc)

Status: 2026-11-09. Audience: engineers deciding where new logic lives and how it composes. Reading contract: every capability below is stated as PROBLEM → MECHANISM → INTERFACES → INVARIANTS so a reviewer can challenge the decision, not just the prose. Facts are preserved from the commercialisation design set and operational memory, recast as design responsibilities. (Source: Doc 02 Headless Composable Mesh; Doc 10 One Platform Composition v1.0 dated 2026-11-06; Doc 32 Cross-Domain Event Spine v1.0.0 dated 2026-11-07; Doc 36 Claims Orchestration Capability Plan v1.9.0 dated 2026-11-08; Platform Master Plan v2.0 dated 2026-05-19; Deployment Topology v1.0 dated 2026-05-18.)

0. Thesis — headless-first composable platform

PROBLEM — vertical sprawl defeats reuse. Teams repeatedly build bespoke front-to-back verticals with their own tables, glue code, and delivery paths. Each vertical then owns its own identity, lifecycle, proof, and integration story, and cross-vertical collaboration becomes point-to-point wiring that cannot be governed or audited as one platform. (Source: Doc 02 thesis.)

MECHANISM — logic lives in headless engines; surfaces are optional. All durable logic — identity, claims, leases, escrows, optimisation, event delivery — runs in headless background engines. Customers keep their existing frontends and consume through narrow, stable interfaces: REST, GraphQL, WebSocket, WhatsApp, or USSD. Turnkey mobile, web, aviation slate, and health reference clients are optional consumers of those interfaces, never owners of the logic. (Source: Doc 02 Headless Composable Mesh.)

INTERFACES — one composition path, many entry styles. Fragments, ceilings, break-glass controls, federation, proof, and evidence export compose through one declared path: versioned fragments are merged by hierarchy and quorum rules, overridden by ceiling policy, materialised as declarative configuration in durable key-value planes, executed by workflow and protocol engines, then sealed with a proof receipt, a federation event, and a transactional outbox before any evidence export. The same path is reached whether the caller is a headless API client, a conversational channel, or a reference client. (Source: Doc 10 One Platform Composition.)

INVARIANTS — compose-first, declarative-first, fail-closed. Prefer seeding and composing shipped engines — organisation, affiliation, resource, proof path specifications, workflow engine, protocol engine, declarative packs — over creating new capabilities. Coding is reserved for generalised processors or genuinely impractical cases; persistence of delivery, event binding, subject routing, and handler dispatch must stay declarative. When an engine is unavailable the platform fails closed with a typed error and never returns a synthetic success, and hot-path numbers are never hardcoded on cards or dashboards. (Source: Doc 36 §0.1 compose-first rule; operational memory mandates on declarative-first, fail-closed, and no synthetic payloads.)

1. Identity plane — who is acting, in which scope

PROBLEM — identity scatters across every vertical. Without a single identity owner, each app invents its own membership, role, and isolation model. A user is then a different principal per vertical, tenant isolation drifts, and scoped authority cannot be checked consistently. (Source: Doc 02 identity ownership; operational memory stratum order.)

MECHANISM — the identity plane owns federation, organisation, delegation, and effective permissions, and nothing else owns them. It owns federated identity with phone linkage, resource linkage, universal claim linkage, device fingerprint, and trust level; canonical organisations and their memberships; the scope-delegation chain that expresses who may act for whom up to a bounded depth; the applications permissions framework that resolves roles, direct grants, scopes, features, and admin standing into one effective decision; and external opaque authorisation with tenant isolation by scope filtering and per-tenant cryptographic keys. (Source: Doc 02; operational memory identity strata and permissions framework.)

INTERFACES — authentication and effective-permission resolution. Authentication sessions, authorisation checks, and permission resolution are exposed as narrow decision interfaces over the same delegation chain. Callers ask what may this principal do in this scope and receive a resolved answer; they never re-implement membership or role logic. (Source: Doc 02 gateway description; permissions framework resolve operation.)

INVARIANTS — scope is the isolation boundary, delegation depth is capped. Tenant isolation is by scope filtering, not by forked data models. Delegation depth is hard-capped at ten hops in both scope configuration and delegation records, and authority is verified through a bounded chain check rather than ad-hoc scope tests in presentation code. (Source: Doc 02; scope governance specification.)

2. Claims plane — the system of record

PROBLEM — facts, assets, contracts, orders, and incidents need one durable reference. If each domain keeps its own ledger semantics, cross-domain lineage, proof, and billing cannot agree on what happened, when, or under which type. (Source: Doc 02 four-primitives statement.)

MECHANISM — the claims plane owns the canonical claim as the universal fact primitive, typed by one name system (CNS). Any fact, asset, contract, order, or incident is represented as a claim addressed by a canonical name under the claim type hierarchy with traits, for example a construction parent with governed and tracked traits and budgeting, escrow-linked, inspectable, sequential, funded, assignable, time-bounded, pass-fail, sequential, funded, assignable, time-bounded, pass-fail, certifiable, and disputable children under the construction family. A transitional lifecycle helper exists only as a thin wrapper that must dual-map to the canonical claim through a deterministic universal name and a mint path, with no domain-specific extension fields ever added. (Source: Doc 02; Doc 36 §0 transitional helper rule.)

INTERFACES — claim lifecycle operations. Clients perform guarded transitions between lifecycle states, finalisation with a proof receipt, and timeline reads. Every transition is checked against declarative policy before it is applied, and finalisation requires evidence. (Source: Doc 36 minimal pilot sequence.)

INVARIANTS — claim-first, no domain columns. Think claim-first: new domain content is expressed by choosing or registering a claim type and traits, never by adding columns or sibling structures to the helper layer. If content cannot be mapped to the canonical primitives, the design stops and asks rather than extending the plane. (Source: operational memory zero-bespoke mandate; Doc 36 §0.)

3. Truth fabric — lineage, provenance, hierarchy, attestation

PROBLEM — provenance must survive across claims, scopes, and systems. A single fact without its ancestry cannot be trusted, traversed, or governed. Hierarchies and attestations must be navigable as a graph, not reconstructed from ad-hoc references. (Source: Doc 02 lineage graph; Platform Master Plan §7.)

MECHANISM — the truth fabric owns a directed graph of nodes and typed edges that carries lineage, provenance, parent-child hierarchy, and attestation. The graph's create, index, and sweep behaviours are declared complete and are not to be replanned; the plane's ongoing job is to keep index and traversal consistent with mutations that arrive through the event fabric. (Source: Platform Master Plan §7 Done boundary; Doc 02.)

INTERFACES — traversal and search. Callers walk the graph from a start reference in an explicit direction up to a bounded depth with a strength floor and an explicit relation filter; empty filters match nothing by design. Semantic discovery and index maintenance keep the same graph queryable without owning the claims record itself. (Source: Platform Master Plan truth traversal contract; operational memory traversal rules.)

INVARIANTS — the claims record and the graph are dual-mapped, not alternatives. Every claim-eligible entity exists as a claim and is linked into the graph; graph typing and claim typing must agree. Mutation propagation is fenced: durable mutations emit delivery anchors first and index synchronisation follows as a consequence, never as the record itself. (Source: operational memory dual-map contract and graph reactivity fence.)

4. Verification layer (PoCE) — proof that the declared path was followed

PROBLEM — governed actions need evidence of correct execution, not mere execution. A transition that happened is not proof that the authorised path was followed. Auditors need a tamper-evident trail bound to the path specification, the stage sequence, and the result. The PoCE layer owns that trail. (Source: Doc 10 governance receipt; proof-of-correct-execution definition.)

MECHANISM — the verification layer owns a verification machine: declared path specification, per-request session, append-only stage steps, and a final receipt. A governed action emits a hash-chained governance path receipt pinned to its path specification identifier, specification version, chain head, and root hash, so any verifier can recompute the chain and confirm the result binding. (Source: Doc 10 §1 flow shape; operational memory proof bridge.)

INTERFACES — start, step, finalise, verify, export. Callers start a session from a path specification, record one stage per executed step, finalise into a receipt bound to a result claim and result hash, verify a session chain, and export evidence. Stage events travel as first-class events on their own subject family. (Source: Doc 10 flow; operational memory proof lifecycle and stage routing.)

INVARIANTS — proof is append-only and version-pinned. Steps cannot be edited or reordered after the fact; finalisation binds the root to exactly one result. A break-glass elevation or a compliance gate does not by itself create proof — the machine must be started explicitly. (Source: Doc 10 receipt contents; operational memory lifecycle bridge.)

5. Event spine — delivery and interest-based routing

PROBLEM — direct calls couple every producer to every consumer. Verticals cross-collaborate through custom glue only because there is no shared delivery contract. Failures then vanish into synchronous call chains and cannot be retried, replayed, or governed. (Source: Doc 02 gateway rule; Doc 32 spine scope.)

MECHANISM — the event spine owns one canonical envelope plus an interest-based subject fabric and a transactional outbox. Producers write delivery anchors transactionally; a relay publishes them; consumers subscribe by interest rather than by point-to-point address. The fabric is aligned to social-hierarchy ceilings, tiered evaluation, and explicit playbook publisher and consumer declarations. Sense and command inputs are normalised before they enter the fabric, enriched with geo cell, trait hydration, entitlement snapshot, and presence, matched, then only after a match fires are solver stages and fulfilment engines invoked, ending in a durable write with proof. (Source: Doc 32 §§1–5.)

INTERFACES — envelope, criteria subjects, playbook contracts. Producers emit the canonical envelope on criteria-style subjects; playbooks declare what they emit, consume, enrich, and solve for, with correlation and security bounds. Consumers validate against declarative allowlists and resolve packs before dispatching declared handlers. (Source: Doc 32 playbook contract.)

INVARIANTS — never direct-publish as the record. The durable store remains the record plus a bounded vocabulary; it is not a live evaluator. Delivery is transactional first and published second, and background work uses events rather than polling, with sweeps reserved for recovery only. (Source: Doc 32 durable-store rule; operational memory events-not-polling rule.)

6. Integration plane — protocol translation without authority

PROBLEM — external systems speak different protocols and require different certificates and signatures. If the brain itself speaks SOAP, XML, and EDI with per-partner credentials, every new partner rewrites the core and blurs who authorised the call. (Source: operational memory protocol gateway design.)

MECHANISM — the integration plane owns stateless translation only: unmarshal, translate, execute, marshal. It subscribes through queue groups so replicas scale round-robin, translates one canonical shape to the partner protocol, executes the external call with per-organisation mutual certificates, and returns the response. It holds no authorisation state, no durable record access, and no proof creation. (Source: operational memory protocol gateway architecture.)

INTERFACES — egress and ingress families. Outbound traffic enters on an egress family specific to the partner; inbound returns on the corresponding response, failure, and error families. The calling layer resolves capability names against the interface catalogue and fails closed on downstream failure. (Source: Doc 02 gateway capability resolution; operational memory gateway routing and fail-closed rule.)

INVARIANTS — translation is not permission. Authentication, rate limiting, and proof recording stay with the caller before dispatch. The plane is stateless and loaded behind an explicit compliance profile; it must never invent fallback data when a partner is unreachable. (Source: operational memory gateway boundaries and fail-closed mandate.)

7. Money side — billing, desks, and proof of value

PROBLEM — billing logic hardcodes itself into verticals. Revenue splits, wallet credits, and subscription gates then drift per vertical, and evidence of commercial fairness cannot be exported independently of fulfilment. (Source: Doc 36 §0.1 money ownership; Doc 32 pack contract.)

MECHANISM — the money side owns commerce subscriptions, financial desks, and the billing catalogue as consumed packs. Revenue-split profiles and wallet credits are configured declaratively rather than coded per vertical. Proof of billing fairness is produced by evidence export and proof verification, not by the fulfilment path itself. (Source: Doc 36 §0.1; Doc 32 pack contract.)

INTERFACES — billing and evidence surfaces. Clients interact with subscription and billing decision points and request evidence packages that can be verified independently. Money subjects travel on their own families distinct from lifecycle subjects. (Source: Doc 32 money subject families; Doc 36 pack consumption.)

INVARIANTS — configuration over code, honesty over completeness. Split and wallet rules are data in declarative planes, versioned and auditable. A soft or composed capability never reports a live gate as met merely because the configuration exists. (Source: operational memory declarative-first and honesty mandates; Doc 36 honesty gaps.)

8. Where a new feature MUST live if it's new (which plane owns it)

Choose the owning plane first; the feature must live in that plane. If the question is who may act and in which scope, the feature lives in the identity plane; it extends federation, organisation, delegation, or permission resolution and inherits scope isolation. (Source: Doc 02 identity ownership.) If the question is what durable fact or contract are we recording, it lives in the claims plane; it chooses or registers a claim type and reuses the guarded transition and finalise operations. (Source: Doc 02; Doc 36.) If the question is how does this relate to what came before, it lives in the truth fabric; it adds nodes or typed edges and reuses traversal with scope and lease gates. (Source: Doc 02; Platform Master Plan §7.) If the question is how do we prove the authorised path was followed, it lives in the verification layer; it declares or reuses a path specification and records session steps. (Source: Doc 10.) If the question is who needs to know and when, it lives in the event spine; it declares a playbook publisher or consumer and routes through the envelope and outbox. (Source: Doc 32.) If the question is how do we speak the partner's protocol, it lives in the integration plane; it adds configuration and routing, not authority. (Source: operational memory gateway.) If the question is how is this billed, split, or credited, it lives in the money side; it configures packs and catalogue entries. (Source: Doc 36 §0.1.) Choosing a plane is the design decision; everything after that is configuration within the plane.

9. Pack rule — do not add a vertical branch, add a pack

PROBLEM — branches fork the platform per vertical. A motor-only, medical-only, or benefits-only code path doubles every future plane change and makes federation and proof non-uniform. (Source: Doc 36 compose-first rule; Doc 10 single-path composition.)

MECHANISM — declare a pack that composes shipped engines; do not fork a vertical branch. A pack declares its claim types and traits, its panels and affiliations, its proof path specification, its declarative lookup sets, its scenario bindings, and its event subjects. The runtime resolves the pack at event time and executes the same guarded transition, quorum, evidence, and external-assertion sequence for every pack. (Source: Doc 36 minimal pilot; Doc 32 playbook contract.)

INTERFACES — pack declaration as the feature interface. New behaviour is reviewed as pack configuration — which types, thresholds, panels, and subjects it declares — plus the planes it consumes. (Source: Doc 36 §0.2 pack and lookup keys.)

INVARIANTS — parallelism by declaration, not by duplication. The following are the canonical examples of the rule: a motor claim, a medical claim, a home claim, a government benefit claim, a government compensation claim, and a community ticket are all expressed as pack declarations over the same planes with per-type subject overrides and per-type panel, SLA, and quorum lookups; adding a new vertical means adding a pack whose scenarios, panels, and subjects are seeded declaratively, while the transition, proof, and delivery machinery stays shared. A new vertical that needs a new plane must stop and ask before forking structure. (Source: Doc 36 §0.2 and operational memory zero-bespoke mandate.)

Gaps and honesty limits

The ceiling digest is not yet carried in the proof receipt and approved-digest recomputation is not yet in the seeder; the six-stage promotion lifecycle from draft through live to retired has dual control documented but no single running workflow for every fragment; break-glass elevation does not yet open proof or file corrective action and stays bounded by short time-to-live and expiring roles; the customer-held seal, customer certification, and customer-held signing root are not yet enforced; stakeholder brief language overclaims where capability is still being wired declaratively and no live gate exists; and the orchestration facade remains proposed optional ergonomics over existing engines rather than shipped code. Master-plan pillars beyond the declared Done boundary — enterprise messaging, commercial operations, notarisation, trade, lifecycle mesh, and parts of external engines — remain gaps and must not be inferred as shipped. Operational memory is not a verified live inventory. (Source: Doc 10 §2 gaps; Doc 36 §§0, 3.2, 5; Platform Master Plan §3 gaps and §7 Done boundary.)

Interface summary