Diagrams

Ai Governance Sequence

diagram-ai-governance-sequence · canon/diagrams/ai-governance-sequence.mmd

sequenceDiagram
participant User
participant Identity
participant Agent
participant Policy
participant Approval
participant Tool
participant Evidence

User->>Identity: Authenticate
Identity->>Agent: Delegate
Agent->>Policy: Request Action
Policy->>Approval: Approval?
Approval-->>Policy: Approved
Policy->>Tool: Execute
Tool->>Evidence: Record
Evidence-->>User: Audit Available

Ampriot Planes

diagram-ampriot-planes · canon/diagrams/ampriot-planes.mmd

%% Ampriot — the six-plane model in one product. Truth in MariaDB; everything else
%% derived via the NATS event spine, truth-outward; Control gates the rest.
flowchart TB
    M[("MariaDB — Truth Plane<br/>identities · ownership · orders · rights · settlements")]
    N["NATS JetStream — event spine"]
    R["Redis — Acceleration Plane<br/>locks · queues · rate limits · cache"]
    G["Graph — Projection Plane<br/>relationship read model"]
    Rec["Recommendations — Intelligence Plane<br/>deterministic discovery"]
    Mod{{"Module registry — Control Plane<br/>kill switches"}}
    M -->|"truth-outward events"| N
    N --> R
    N --> G
    G --> Rec
    Mod -.->|"gates"| R
    Mod -.->|"gates"| G
    Mod -.->|"gates"| Rec

Capban Degraded Mode

diagram-capban-degraded-mode · canon/diagrams/capban-degraded-mode.mmd

%% CapBan — degrade toward safety, recover deterministically. It keeps protecting
%% the system while its own dependencies fail, and restores itself without heroics.
flowchart TB
    EV["Events"] --> SW["Score windows"] --> DEC["Decisions"] --> ENF["Enforce bans"]
    SW -. "store down" .-> BUF["Degraded mode:<br/>buffer events (memory ring)<br/>keep enforcing cached bans"]
    BUF -. "store recovers" .-> RPL["Replay buffered events"]
    ENF -. "enforcer fails 3×" .-> CB["Circuit breaker opens:<br/>alert · manual-ban via API"]
    CB -. "enforcer recovers" .-> REAP["Re-apply missed bans"]
    RST["On restart"] --> REC["Reconcile bans vs firewall<br/>(idempotent · remove orphans)"]

Capban Pipeline

diagram-capban-pipeline · canon/diagrams/capban-pipeline.mmd

%% CapBan — security as a typed pipeline, not a bolt-on. Dangerous capability
%% (firewall mutation) confined to one idempotent, validated seam.
flowchart LR
    E["Event<br/>(typed at the boundary)"]
    I["Normalized Identity"]
    POL["Policy<br/>allowlist → denylist → score"]
    D["Decision<br/>carries its evidence"]
    EN["Enforcement<br/><b>single confined seam</b><br/>idempotent · validated · no shell"]
    A["Audit<br/>structured JSON → SIEM"]
    NFT[("nftables / k8s<br/>(only reachable here)")]

    E --> I --> POL --> D --> EN --> A
    EN -->|"idempotent apply"| NFT

Capdb Replication

diagram-capdb-replication · canon/diagrams/capdb-replication.mmd

%% CapDB — truth replicated without ever forking. Physical WAL streaming,
%% read-only replicas, generation fencing (no split-brain).
flowchart LR
    C["Clients"]
    P[("Primary<br/>authoritative truth")]
    RA[("Replica A<br/>read-only")]
    RB[("Replica B<br/>read-only")]
    F["Generation fencing:<br/>reject segments whose<br/>generation < local<br/>(a deposed primary cannot resume)"]

    C -->|"writes"| P
    P -->|"WAL frames — physical, byte-for-byte"| RA
    P -->|"WAL frames — physical, byte-for-byte"| RB
    RA -->|"reads"| C
    RB -->|"reads"| C
    RA -. enforces .-> F
    RB -. enforces .-> F

Control Fabric Components

diagram-control-fabric-components · canon/diagrams/control-fabric-components.mmd

flowchart LR
Client-->Gateway
Gateway-->Identity
Gateway-->Delegation
Gateway-->Policy
Policy-->Approval
Approval-->Execution
Execution-->Evidence
Evidence-->Audit
Audit-->Analytics

Control Fabric Deployment

diagram-control-fabric-deployment · canon/diagrams/control-fabric-deployment.mmd

flowchart LR
Users-->Gateway
Gateway-->Identity
Gateway-->Policy
Gateway-->Delegation
Gateway-->Approval
Gateway-->Evidence
Gateway-->Audit
Policy-->Redis
Identity-->Postgres
Evidence-->OpenSearch
Audit-->ObjectStore

Edda Pillars

diagram-edda-pillars · canon/diagrams/edda-pillars.mmd

flowchart LR
A[Identity]-->B[Delegation]
B-->C[Policy]
C-->D[Approval]
D-->E[Execution]
E-->F[Evidence]
F-->G[Observability]
G-->H[Governance]

Evidence Chain

diagram-evidence-chain · canon/diagrams/evidence-chain.mmd

sequenceDiagram
participant User
participant Agent
participant Policy
participant Approval
participant Tool
participant Evidence

User->>Evidence: request_received
Agent->>Evidence: delegation_used
Policy->>Evidence: policy_evaluated
Approval->>Evidence: approval_recorded
Tool->>Evidence: tool_invoked
Tool->>Evidence: result_recorded

Federation

diagram-federation · canon/diagrams/federation.mmd

flowchart LR
A[Org A Control Fabric] <-- Assertions --> B[Org B Control Fabric]
A --> APolicy[Policy]
A --> AEvidence[Evidence]
B --> BPolicy[Policy]
B --> BEvidence[Evidence]

Governance Lifecycle

diagram-governance-lifecycle · canon/diagrams/governance-lifecycle.mmd

flowchart TD
A[Register Agent]-->B[Delegate Authority]
B-->C[Evaluate Policy]
C-->D[Approval]
D-->E[Execute]
E-->F[Capture Evidence]
F-->G[Audit]
G-->H[Review]

Intelligence Plane

diagram-intelligence-plane · canon/diagrams/intelligence-plane.mmd

%% Intelligence Plane — derived, provisional, non-authoritative. It proposes;
%% the Control Plane disposes; the action is recorded in Truth.
flowchart LR
    T[("Truth")] --> F["Features / evidence"]
    PRJ[("Projections")] --> F
    F --> M["Model / ranking"]
    M --> P["Proposal + confidence<br/>(provisional)"]
    P --> G{{"Control Plane gate"}}
    G -->|"approved"| A["Action → recorded in Truth"]
    G -.->|"low confidence / no approval"| H["Suppress · escalate to human"]

Observation Plane

diagram-observation-plane · canon/diagrams/observation-plane.mmd

%% Observation Plane — a lossy, derived account of behavior. Explains the system;
%% never the authoritative record of a business fact (that lives in Truth).
flowchart LR
    B["Every plane's behavior"] -->|"sampled · lossy"| OBS["Logs · Metrics · Traces"]
    OBS --> D["Dashboards / SIEM<br/>explain behavior · retention-bounded"]
    AF["Accountable facts<br/>(who approved what)"] -->|"NOT telemetry"| TR[("Truth Plane<br/>immutable record")]

Projection Plane

diagram-projection-plane · canon/diagrams/projection-plane.mmd

%% Projection Plane — a read-optimized, rebuildable view of truth. Owns no facts;
%% lags truth (eventual consistency); rebuildable but expensively.
flowchart LR
    T[("Truth Plane")] -->|"events"| PR["Projector"]
    PR --> RM[("Read model<br/>index · view · graph")]
    Q["Queries"] --> RM
    RM -.->|"lags truth<br/>(eventual consistency)"| T
    T -.->|"full rebuild — expensive, engineered"| RM

Risk Approval Flow

diagram-risk-approval-flow · canon/diagrams/risk-approval-flow.mmd

flowchart TD
A[Request] --> B[Evaluate Identity]
B --> C[Evaluate Delegation]
C --> D[Evaluate Policy]
D --> E{Risk Level}
E -->|Low| F[Execute]
E -->|Medium| G[Step-up Auth]
E -->|High| H[Human Approval]
G --> F
H --> F
F --> I[Record Evidence]
I --> J[Emit Audit]

Runtime Topology

diagram-runtime-topology · canon/diagrams/runtime-topology.mmd

flowchart LR
Ingress-->Gateway
Gateway-->Identity
Gateway-->Policy
Gateway-->Approval
Gateway-->Evidence
Gateway-->Audit
Gateway-->NATS
NATS-->Workers
Evidence-->OpenSearch
Identity-->Postgres
Policy-->Redis
Audit-->S3

Service Map

diagram-service-map · canon/diagrams/service-map.mmd

flowchart LR
Gateway-->Identity
Gateway-->Delegation
Gateway-->Policy
Gateway-->Approval
Gateway-->Evidence
Gateway-->Audit
Gateway-->Registry
Policy-->Bus[NATS/Event Bus]
Evidence-->Search[OpenSearch]
Audit-->Storage[Object Store]

Six Planes

diagram-six-planes · canon/diagrams/six-planes.mmd

%% The Six Planes — one home for truth; five derive from it without becoming it.
flowchart TB
    CP{{"Control Plane<br/>identity · policy · approval · orchestration · kill switches<br/>(enforces; owns nothing)"}}
    subgraph TRUTH[" "]
      T[("Truth Plane<br/>identity · ownership · money · rights · audit · irreversible facts<br/>ONE authoritative home")]
    end
    AP["Acceleration Plane<br/>caches · counters · locks · rate limits<br/><i>disposable — rebuilt in ms</i>"]
    PP["Projection Plane<br/>search indexes · read models · graphs<br/><i>rebuildable, but expensively</i>"]
    IP["Intelligence Plane<br/>recommendations · embeddings · AI reasoning<br/><i>provisional — proposes, never disposes</i>"]
    OP["Observation Plane<br/>logs · metrics · traces · telemetry<br/><i>lossy account — explains, never decides</i>"]

    T -->|"events, truth-outward"| AP
    T -->|"events, truth-outward"| PP
    T -->|"events, truth-outward"| IP
    T -.->|"described by"| OP
    CP -.->|"enforces facts in"| T
    CP -.->|"gates"| AP
    CP -.->|"gates"| PP
    CP -.->|"gates"| IP