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

Disposable Artifact Lifecycle

diagram-disposable-artifact-lifecycle · canon/diagrams/disposable-artifact-lifecycle.mmd

%% Disposable Artifact Lifecycle — source owns meaning; generated outputs are replaceable evidence
%% and publication surfaces. Stale copies are removed before publication.
flowchart LR
    S[("Source of record<br/>canon units · projection sources · pipeline code")]
    B["Reproducible build<br/>render · export · archive · copy"]
    A[["Disposable artifact<br/>HTML · JSON · zip · report · deployed tree"]]
    V{"Artifact contract<br/>links · scope · schema · boundary"}
    R["Review evidence<br/>release notes · validation report · human gates"]
    P["Publication copy<br/>clean replace<br/>no source mirror"]
    X["Stale artifact"]

    S -->|"governed inputs"| B
    B -->|"generates"| A
    A -->|"validated by"| V
    V -->|"passes"| R
    R -->|"may publish"| P
    P -.->|"must not author"| S
    X -.->|"removed before copy"| P
    A -.->|"delete and rebuild"| B

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]

Edge As Data

diagram-edge-as-data · canon/diagrams/edge-as-data.mmd

%% Edge As Data — authoritative relationship facts have lifecycle and provenance;
%% reverse/traversal views are derived projections, not second truth homes.
flowchart LR
    A["Endpoint A"]
    E[("Relationship edge<br/>type · direction · provenance<br/>created_at · expires_at · state")]
    B["Endpoint B"]
    T[("Truth home<br/>relational row · event · audit record")]
    G[["Graph projection<br/>forward traversal<br/>derived reverse edges"]]
    Q["Traversal queries<br/>who follows me? · what depends on this?"]
    R["Rebuild job"]

    A -->|"source"| E
    E -->|"target"| B
    E -->|"authored and versioned in"| T
    T -->|"truth-outward events"| G
    G --> Q
    T -->|"replay edge facts"| R
    R -->|"rebuilds"| G
    G -.->|"does not author edge truth"| T

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

Evidence Eligibility State Flow

diagram-evidence-eligibility-state-flow · canon/diagrams/evidence-eligibility-state-flow.mmd

%% Evidence Eligibility State Flow - source material must pass admission, snapshot,
%% freshness, approval, sensitivity, and permitted-use checks before it can ground reasoning.
flowchart LR
    I["Source intake<br/>retrieval · feed · upload · tool result"]
    A{"Admission decision<br/>may enter this context?"}
    X["Rejected material<br/>not evidence for this use"]
    S[("Source snapshot<br/>source id · hash · fetch date · excerpt")]
    F["Freshness state<br/>fresh · stale · unknown · expired"]
    P["Approval state<br/>approved · pending · rejected"]
    L["Use boundary<br/>sensitivity · license · permitted purpose"]
    E{"Evidence eligibility<br/>usable for this actor and claim?"}
    G["Retrieval-grounded reasoning<br/>cites eligible evidence"]
    B["Block or route review<br/>refusal · data request · approval task"]
    D[["Preserved derivation<br/>evidence bundle · decision record"]]

    I --> A
    A -->|"no"| X
    A -->|"yes"| S
    S --> F
    S --> P
    S --> L
    F --> E
    P --> E
    L --> E
    E -->|"eligible"| G
    E -->|"not eligible"| B
    G --> D
    B --> D

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