# Axiom Executive Technical Specification

**AI-native operations platform for regulated, sensor-rich industries**

---

| Property | Value |
|----------|-------|
| Version | 1.1 |
| Last Updated | 2026-03-26 |
| Status | Active Development (v0.4.0) |
| Authors | Benjamin Booth, UT Computational NE |

---

> For strategic context, see the [Executive PRD](../requirements/prd-executive.md).

---

## Architecture Overview

Axiom is a domain-agnostic platform for industries where **operational data is fragmented, regulatory compliance is mandatory, and AI must be trustworthy**. It provides the infrastructure and agent framework; domain-specific functionality is layered on top by downstream products.

**Target domains:** Nuclear energy, process manufacturing, defense test ranges, pharmaceutical production, critical infrastructure operations — any environment with time-series sensor data, regulatory audit requirements, human-in-the-loop safety constraints, and heavy reliance on simulation and modeling.

Axiom is a modular Python platform where **everything is an extension**. The core provides infrastructure (LLM gateway, event bus, state management, CLI registry); all domain functionality ships as extensions.

```mermaid
flowchart TB
    subgraph CLI["axiom CLI"]
        Registry["cli_registry.py<br/>discovers extensions<br/>via TOML manifests"]
    end

    subgraph Infra["Core Infrastructure"]
        GW["LLM Gateway<br/>multi-provider routing"]
        EC["Export Control<br/>classification + audit"]
        SS["State Store<br/>hybrid file + PostgreSQL"]
        PF["Provider Framework<br/>pluggable infrastructure"]
    end

    subgraph Extensions["Extension Primitives"]
        direction LR
        Agents["Agents (10)<br/>signal · assistant · steward<br/>diagnostics · publisher<br/>analyst · planner · compliance<br/>reviewer · coach"]
        Tools["Tools (11)<br/>rag · data · model · simulate<br/>pub · export · audit<br/>notify · eval · db · demo"]
        Utils["Utilities (9)<br/>settings · status · connect<br/>infra · update · test<br/>migrate · backup · log"]
        Svc["Services (6)<br/>gateway · serve · daemon<br/>worker · scheduler · stream"]
    end

    subgraph Downstream["Downstream Products"]
        NOS["axiom<br/>Nuclear energy"]
        Mfg["Future domains<br/>Manufacturing · Defense<br/>Pharma · Infrastructure"]
    end

    CLI --> Infra
    Infra --> Extensions
    Extensions --> Downstream

    style CLI fill:#e3f2fd,color:#000000
    style Infra fill:#fff3e0,color:#000000
    style Extensions fill:#f3e5f5,color:#000000
    style Downstream fill:#e8f5e9,color:#000000
    linkStyle default stroke:#777777,stroke-width:3px
```

**Key design principles** (detailed in [CLAUDE.md](../../CLAUDE.md)):
- Everything is an extension (3-tier discovery: project → user → builtin)
- Domain-agnostic core; domain-specific via downstream products and external extensions
- Offline-first (queue locally, sync on restore)
- Human-in-the-loop for safety-adjacent writes
- Model-agnostic, cloud-agnostic, IDE-agnostic, BI-provider-agnostic

---

## Extension Primitives

Axiom has four extension kinds. Every piece of functionality — shipped or community-built — is one of these four primitives. Together they form the complete surface area of the platform.

### Implementation Reference

Shipped agents use internal project names (WALL-E characters). The archetype names below are the role descriptions used in specs and PRDs.

| Archetype | Internal Name | Extension Directory | CLI Noun |
|-----------|--------------|-------------------|----------|
| Signal | EVE | `eve_agent/` | `axiom signal` |
| Assistant | Axi | `axi_agent/` | `axiom chat` |
| Steward | M-O | `mo_agent/` | `axiom mo` |
| Diagnostics | D-FIB | `dfib_agent/` | `axiom doctor` |
| Publisher | PR-T | `prt_agent/` | `axiom pub` |

The `mirror_agent/` extension (GitHub mirror sensitivity gate) is reclassified as a **utility**, not an agent archetype.

### Agents (LLM autonomy — perceive, reason, act)

Agents have persistent identity, maintain state across sessions, and can invoke tools autonomously within human-in-the-loop guardrails.

| Agent | CLI Noun | Description | Status |
|-------|----------|-------------|--------|
| **Signal** | `axiom signal` | Event ingestion — scans external sources, extracts structured data, maintains situational awareness | ✅ Shipped |
| **Assistant** | `axiom chat` | Interactive LLM — Q&A, tool use, RAG, per-turn routing | ✅ Shipped |
| **Steward** | `axiom mo` | Resource lifecycle — retention enforcement, cleanup, cost optimization, system hygiene | ✅ Shipped |
| **Diagnostics** | `axiom doctor` | Platform health — troubleshooting, self-healing, connectivity checks, performance profiling | 🔲 Partial |
| **Publisher** | `axiom pub` | Document lifecycle — draft, generate, review, route for approval, version control | ✅ Shipped |
| **Analyst** | `axiom analyze` | Automated data analysis — anomaly detection, trend identification, root cause analysis, drift monitoring | 🔲 Planned |
| **Planner** | `axiom plan` | Operational planning — resource allocation, scheduling, conflict detection, what-if scenarios | 🔲 Planned |
| **Compliance** | `axiom comply` | Regulatory monitoring — obligation tracking, gap detection, evidence generation, audit readiness | 🔲 Planned |
| **Reviewer** | `axiom review` | Quality gates — review workflows, approval chains, change validation, peer review automation | 🔲 Planned |
| **Coach** | `axiom coach` | Knowledge transfer — onboarding, guided training, competency assessment, contextual help | 🔲 Planned |

### Tools (capabilities invoked by agents or CLI)

Tools are stateless operations. They do one thing well. Agents compose tools to accomplish complex tasks.

| Tool | CLI Noun | Description | Status |
|------|----------|-------------|--------|
| **rag** | `axiom rag` | Semantic search, corpus management, knowledge maturity pipeline | ✅ Shipped |
| **data** | `axiom data` | Lakehouse access — query, schema discovery, pipeline status, lineage | 🔲 Planned |
| **model** | `axiom model` | Model registry — version, search, validate, pull, training provenance | 📋 Spec'd |
| **simulate** | `axiom sim` | Simulation job management — submit, monitor, retrieve results, compare runs | 📋 Spec'd |
| **pub** | `axiom pub generate` | Document generation engine — markdown → output format → publish endpoints | ✅ Shipped |
| **export** | `axiom export` | Evidence packages, data export, regulatory report generation | 🔲 Planned |
| **audit** | `axiom audit` | Audit trail query — chain verification, forensic reconstruction, evidence assembly | 🔲 Planned |
| **notify** | `axiom notify` | Notification routing — escalation policies, on-call routing, channel management | 🔲 Planned |
| **eval** | `axiom eval` | Quality assurance — model evaluation, prompt regression testing, accuracy benchmarking | 🔲 Planned |
| **db** | `axiom db` | Database lifecycle — up, down, migrate, status | ✅ Shipped |
| **demo** | `axiom demo` | Guided onboarding walkthroughs | ✅ Shipped |

### Utilities (platform plumbing)

Utilities manage the platform itself. They don't operate on domain data — they operate on configuration, connectivity, and infrastructure state.

| Utility | CLI Noun | Description | Status |
|---------|----------|-------------|--------|
| **settings** | `axiom settings` | Configuration management — get/set/reset, global + project scope | ✅ Shipped |
| **status** | `axiom status` | System health — providers, connections, services, pipelines | ✅ Shipped |
| **connect** | `axiom connect` | Connection registry — credential resolution, health checks, managed service lifecycle | ✅ Shipped |
| **infra** | `axiom infra` | Infrastructure services — init profiles, provider connectivity, deployment diagnostics | 🔲 Planned |
| **update** | `axiom update` | Self-update with restart preservation | ✅ Shipped |
| **test** | `axiom test` | Test orchestration — unit, integration, red-team, prompt evals | ✅ Shipped |
| **migrate** | `axiom migrate` | Data and schema migration — version upgrades, format conversion, backfill | 🔲 Planned |
| **backup** | `axiom backup` | Manual backup triggers, restore operations, verification | 🔲 Planned |
| **log** | `axiom log` | Log query — forensic analysis, incident reconstruction, structured search | 🔲 Planned |

### Services (long-running processes)

Services are daemons that run continuously. They provide the runtime substrate that agents, tools, and utilities depend on.

| Service | Description | Status |
|---------|-------------|--------|
| **gateway** | API gateway — routing, rate limiting, authentication, request transformation | 🔲 Planned |
| **serve** | Web application — dashboards, interactive UIs, WebSocket endpoints | 📋 Spec'd |
| **daemon** | Background processing — signal ingestion, event bus consumer, scheduled sweeps | 🔲 Planned |
| **worker** | Async task execution — pipeline runs, batch transforms, simulation jobs, model training | 🔲 Planned |
| **scheduler** | Job scheduling — cron-like triggers, dependency-aware execution, retry policies | 🔲 Planned |
| **stream** | Real-time event processing — Kafka/Flink consumer/producer, Bronze layer streaming writes | 🔲 Planned |

### Core Infrastructure (shared by all extensions)

| Component | Spec | Status |
|-----------|------|--------|
| **LLM Gateway** | [Model Routing Spec](spec-model-routing.md) | ✅ Shipped |
| **Export Control Router** | [Model Routing Spec §4](spec-model-routing.md) | ✅ Shipped |
| **Hybrid State Store** | [State Management Spec](spec-agent-state-management.md) | ✅ Shipped |
| **Routing Audit Log** | [Model Routing Spec §11](spec-model-routing.md) | ✅ Shipped |
| **Provider Framework** | [ADR-012: Provider Identity](../requirements/adr-012-provider-identity.md) | ✅ Shipped |

---

## Infrastructure Services

Axiom provides a vetted, tested infrastructure stack that downstream products consume as a deployment unit. Every infrastructure service is **provider-backed** — the same interface works whether the deployment target is a private HPC cluster, a cloud account, or a hybrid of both.

**Authoritative specs:** Individual service specs linked below. Operational policies (backup, retention, DR, encryption) are defined in [Data Architecture Spec § 9](spec-data-architecture.md#9-backup-retention--archive-policy).

### Provider Abstraction

All infrastructure services follow the same provider contract established by `ProviderBase` (see [ADR-012](../requirements/adr-012-provider-identity.md)). Each service category defines an interface; concrete providers implement it for a specific backend. Deployments select providers via `infrastructure.toml`.

```mermaid
flowchart LR
    subgraph Interface["Service Interfaces"]
        OBJ["ObjectStorageProvider"]
        SEC["SecretProvider"]
        OBS["ObservabilityProvider"]
        MSG["StreamingProvider"]
        ALR["AlertProvider"]
        IDN["IdentityProvider"]
        AUZ["AuthorizationProvider"]
        CRT["CertProvider"]
    end

    subgraph SelfHosted["Self-Hosted (TACC)"]
        Ceph["ceph — Ceph/Rook"]
        Bao["openbao — OpenBao"]
        PLG["plg — Prometheus<br/>+ Loki + Grafana"]
        Kafka["kafka — Apache Kafka<br/>(KRaft) + Flink"]
        AM["alertmanager — Alertmanager"]
        Kratos["kratos — Ory Kratos"]
        FGA["openfga — OpenFGA"]
        CM["certmanager — cert-manager"]
    end

    subgraph AWS["Cloud (AWS)"]
        S3["aws_s3 — S3 / Glacier"]
        KMS["aws_kms — KMS"]
        CW["aws_cloudwatch — CloudWatch"]
        Kinesis["aws_kinesis — Kinesis"]
        SNS["aws_sns — SNS"]
        Cognito["aws_cognito — Cognito"]
        AWSIAM["aws_iam — IAM"]
        ACM["aws_acm — ACM"]
    end

    subgraph GCP["Cloud (GCP)"]
        GCS["gcp_gcs — Cloud Storage"]
        GKMS["gcp_kms — Cloud KMS"]
        GM["gcp_monitoring — Cloud Ops"]
        PS["gcp_pubsub — Pub/Sub"]
        GNA["gcp_alerting — Cloud Alerting"]
        GID["gcp_identity — Identity Platform"]
        GIAM["gcp_iam — IAM"]
        GCRT["gcp_cas — Certificate Authority"]
    end

    OBJ --> Ceph
    OBJ --> S3
    OBJ --> GCS
    SEC --> Bao
    SEC --> KMS
    SEC --> GKMS
    OBS --> PLG
    OBS --> CW
    OBS --> GM
    MSG --> Kafka
    MSG --> Kinesis
    MSG --> PS
    ALR --> AM
    ALR --> SNS
    ALR --> GNA
    IDN --> Kratos
    IDN --> Cognito
    IDN --> GID
    AUZ --> FGA
    AUZ --> AWSIAM
    AUZ --> GIAM
    CRT --> CM
    CRT --> ACM
    CRT --> GCRT

    style Interface fill:#e3f2fd,color:#000000
    style SelfHosted fill:#e8f5e9,color:#000000
    style Cloud fill:#fff3e0,color:#000000
    linkStyle default stroke:#777777,stroke-width:2px
```

### Service Catalog

Every self-hosted provider is pure open-source (Apache 2.0, MPL 2.0, LGPL 2.1, or PostgreSQL License). No BSL or source-available dependencies.

| Service | Interface | Self-Hosted | AWS | GCP | Status |
|---------|-----------|------------|-----|-----|--------|
| **Object Storage** | `ObjectStorageProvider` | [Ceph/Rook](https://rook.io/) (S3 API) | S3 | Cloud Storage | 📋 Spec'd |
| **Cold-Tier Archive** | `ObjectStorageProvider` (lifecycle) | Ceph storage classes | S3 Glacier | Archive class | 📋 Spec'd |
| **Secrets & Encryption** | `SecretProvider` | [OpenBao](https://openbao.org/) | KMS | Cloud KMS | 🔲 Planned |
| **Observability** | `ObservabilityProvider` | [Prometheus](https://prometheus.io/) + [Grafana](https://grafana.com/oss/) + [Loki](https://grafana.com/oss/loki/) | CloudWatch | Cloud Monitoring + Logging | 🔲 Planned |
| **Streaming** | `StreamingProvider` | [Apache Kafka](https://kafka.apache.org/) (KRaft) + [Flink](https://flink.apache.org/) | Kinesis + Flink | Pub/Sub + Dataflow | 📋 Spec'd |
| **Alerting** | `AlertProvider` | [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) | SNS | Cloud Alerting | 🔲 Planned |
| **Identity** | `IdentityProvider` | [Ory Kratos](https://www.ory.sh/kratos/) | Cognito | Identity Platform | 🔲 Planned |
| **Authorization** | `AuthorizationProvider` | [OpenFGA](https://openfga.dev/) | IAM (or OpenFGA on EKS) | IAM (or OpenFGA on GKE) | 🔲 Planned |
| **Certificates** | `CertProvider` | [cert-manager](https://cert-manager.io/) | ACM | Certificate Authority Service | 🔲 Planned |
| **Operational DB** | Direct | [PostgreSQL 16](https://www.postgresql.org/) (Helm) | RDS PostgreSQL | Cloud SQL PostgreSQL | ✅ Running |
| **Vector Store** | Direct | [pgvector](https://github.com/pgvector/pgvector) (same PG) | Same | Same | ✅ Running |
| **Block Storage** | Kubernetes PVC | [Ceph RBD](https://docs.ceph.com/en/latest/rbd/) | EBS | Persistent Disk | 📋 Spec'd |
| **Container Platform** | Kubernetes | [K3s](https://k3s.io/) / K3D | EKS | GKE | ✅ Running (dev) |
| **Terraform State** | Terraform backend | PostgreSQL (`pg`) | S3 + DynamoDB | GCS + Firestore | 📋 Spec'd |

**Foundation governance:**

| Provider | Governing Body |
|----------|---------------|
| Ceph / Rook | Linux Foundation / CNCF Graduated |
| OpenBao | Linux Foundation |
| Prometheus / Alertmanager | CNCF Graduated |
| Grafana / Loki | Grafana Labs (AGPL 3.0 — no SaaS restriction for self-hosted) |
| Apache Kafka / Flink | Apache Software Foundation |
| Ory Kratos | Ory (committed open-source; Apache 2.0) |
| OpenFGA | CNCF Incubation |
| cert-manager | CNCF Graduated |
| K3s | CNCF Sandbox (SUSE/Rancher) |

**Licensing policy:** Axiom's self-hosted stack uses only permissive or copyleft open-source licenses (Apache 2.0, MPL 2.0, LGPL 2.1, AGPL 3.0, PostgreSQL License). No BSL or source-available dependencies.

### Configuration

Providers are selected per-deployment in `runtime/config/infrastructure.toml`. Each entry follows the standard provider contract (`ProviderBase`): `type` selects the backend, `name` is the display name, `uid` is auto-generated on first load and persisted for forensic traceability.

```toml
# runtime/config/infrastructure.toml

[[infra.object_storage]]
type = "ceph"                           # or "aws_s3"
name = "Primary Object Storage"
endpoint = "https://ceph.tacc.utexas.edu"
bucket = "axiom-lakehouse"
region = ""                             # empty for self-hosted
# uid = "auto-generated"

[[infra.secrets]]
type = "openbao"                        # or "aws_kms"
name = "Production Secrets"
endpoint = "https://openbao.tacc.utexas.edu:8200"

[[infra.observability]]
type = "loki"                           # or "aws_cloudwatch"
name = "Facility Observability"
loki_endpoint = "https://loki.tacc.utexas.edu:3100"
prometheus_endpoint = "https://prometheus.tacc.utexas.edu:9090"
grafana_endpoint = "https://grafana.tacc.utexas.edu:3000"

[[infra.streaming]]
type = "kafka"                          # or "aws_kinesis"
name = "Event Streaming"
brokers = ["kafka-0.tacc.utexas.edu:9092"]

[[infra.alerting]]
type = "alertmanager"                   # or "aws_sns"
name = "Facility Alerts"
endpoint = "https://alertmanager.tacc.utexas.edu:9093"

[[infra.identity]]
type = "kratos"                         # or "aws_cognito"
name = "Facility Identity"
endpoint = "https://kratos.tacc.utexas.edu:4433"

[[infra.authorization]]
type = "openfga"
name = "Facility Authorization"
endpoint = "https://openfga.tacc.utexas.edu:8080"

[[infra.certificates]]
type = "certmanager"                    # or "aws_acm"
name = "Cluster Certificates"
issuer = "letsencrypt-prod"             # or "internal-ca"
```

### Deployment Profiles

A deployment profile is a pre-configured set of provider selections. Axiom ships with three profiles; operators can define custom profiles.

| Profile | Object Storage | Secrets | Observability | Streaming | Identity | Use Case |
|---------|---------------|---------|---------------|-----------|----------|----------|
| **`self-hosted`** | Ceph/Rook | OpenBao | Prometheus + Loki + Grafana | Apache Kafka (KRaft) + Flink | Ory Kratos + OpenFGA | TACC, air-gapped facilities, HPC clusters |
| **`aws`** | S3 + Glacier | KMS | CloudWatch | Kinesis + Flink | Cognito (or Kratos on EKS) + IAM | AWS cloud deployments |
| **`gcp`** | Cloud Storage + Archive | Cloud KMS | Cloud Monitoring + Cloud Logging | Pub/Sub + Dataflow | Identity Platform (or Kratos on GKE) + IAM | GCP cloud deployments |

Profiles are applied via `axiom infra init --profile self-hosted`, which generates `infrastructure.toml` with the correct provider types and placeholder endpoints.

### Operational Policies

Backup, retention, archive, disaster recovery, and encryption policies are centralized in [Data Architecture Spec § 9: Backup, Retention & Archive Policy](spec-data-architecture.md#9-backup-retention--archive-policy). Policies are provider-agnostic — they define _what_ (e.g., "7-year cold-tier archive") and the selected provider implements _how_ (e.g., Ceph lifecycle policy vs. S3 Glacier transition rule). Downstream products may extend retention tiers for regulatory requirements.

---

## Data Architecture

**Authoritative spec:** [Data Architecture Spec](spec-data-architecture.md)

**Medallion pattern:** Bronze (raw append-only) → Silver (cleaned, validated) → Gold (aggregated, business-ready). Domain-specific schemas are defined by downstream products; Axiom provides the generic framework, tooling, and operational policies.

**Retention:** Configurable via `runtime/config/retention.yaml`. M-O enforces automatically. See [State Management PRD](../requirements/prd-agent-state-management.md).

---

## Security Architecture

**Authoritative specs:**
- [Security & Access Control PRD](../requirements/prd-security.md)
- [Model Routing Spec §7-8-10](spec-model-routing.md)
- [Connections Spec §8](spec-connections.md)

| Layer | Description | Status |
|-------|-------------|--------|
| **Physical boundary** | VPN / private network isolates EC data | ✅ Enforced |
| **Query classification** | Keyword + Ollama SLM, 3 sensitivity levels | ✅ Shipped |
| **Tier-aware routing** | Gateway routes to public or private endpoint | ✅ Shipped |
| **Routing audit** | JSONL log of every routing decision (no plaintext) | ✅ Shipped |
| **Chunk sanitization** | Strip injection patterns before LLM context | 🔲 Planned (Phase 1) |
| **Response scanning** | Scan EC responses at network boundary | 🔲 Planned (Phase 1) |
| **System prompt hardening** | Non-negotiable security instructions for EC sessions | 🔲 Planned (Phase 1) |
| **Security event log** | PostgreSQL `security_events` table with HMAC | 🔲 Planned (Phase 1) |
| **Store quarantine** | EC content in public RAG → quarantine + alert | 🔲 Planned (Phase 2) |
| **Authorization (OpenFGA)** | ReBAC/RBAC/ABAC via OpenFGA | 🔲 Planned (Phase 3) |

**Principle:** Classification decides WHAT; authorization decides WHO. Both pass independently.

---

## Infrastructure & Deployment

See § Infrastructure Services above for the full service inventory.

**Helm chart:** `infra/helm/charts/axiom/` — deploys PostgreSQL, Signal server, web API.

**Bootstrap:** `source scripts/bootstrap.sh` → venv, pip install, direnv, K3D, Ollama, git hooks.

---

## Extension System

Extensions are discovered via `axiom-extension.toml` manifests. Three tiers:
1. **Project-local:** `.axiom/extensions/` (highest priority)
2. **User-global:** `~/.axiom/extensions/`
3. **Builtin:** `src/axiom/extensions/builtins/`

Four extension kinds (see § Extension Primitives above for the full catalog):
- `agent` — LLM autonomy, persistent identity, state across sessions
- `tool` — Stateless capability invoked by agents or CLI
- `utility` — Platform plumbing, operates on config/connectivity/infra
- `service` — Long-running daemon

**Extension builder contract:**
- Declare connections in TOML → platform handles credentials ([Connections Spec](spec-connections.md))
- Use `get_credential()` for auth → never hardcode tokens
- Use `LockedJsonFile` or `get_state_store()` for state → never raw `json.loads` ([State Spec](spec-agent-state-management.md))

---

## Integration Points

**Authoritative spec:** [Connections Spec](spec-connections.md)

Five integration patterns, unified under the **Connection** abstraction:

| Pattern | Examples | Status |
|---------|----------|--------|
| **API** | Anthropic, GitHub, GitLab, MS Graph | ✅ Working |
| **Browser** | Teams (Playwright), OneDrive | ✅ Built |
| **MCP** | Claude Code ↔ Axi tools (stdio) | ✅ Working |
| **CLI** | Ollama, Pandoc, kubectl, git | ✅ Working |
| **A2A** | Inter-facility agent federation | 📋 Designed |

Credential resolution: env var → settings → keychain → file → browser → prompt.

---

## Model Registry (Model Corral)

**Authoritative spec:** [Model Corral Spec](spec-model-corral.md)

Model Corral is Axiom's registry for simulation models, trained surrogates, and validation datasets:

| Component | Description | Status |
|-----------|-------------|--------|
| **Model registry** | PostgreSQL metadata + S3-compatible object storage | 📋 Spec'd |
| **Manifest schema** | `model.yaml` validation (JSON Schema) | 📋 Spec'd |
| **Surrogate extension** | Training provenance, performance tier assignment | 📋 Spec'd |
| **Git sync** | Optional bidirectional Git integration | 📋 Spec'd |
| **Validation framework** | Schema, file, syntax checking | 📋 Spec'd |
| **CLI** | `axiom model` (search, add, pull, validate) | 📋 Spec'd |
| **Web UI** | Catalog browser, upload wizard, lineage graph | 📋 Spec'd |

**Model types:** High-fidelity simulation input decks, trained surrogates (WASM, ONNX), validation datasets, configuration packages. Domain-specific model types (e.g., nuclear physics codes) are registered by downstream products.

**Access tiers:** `public` (open benchmarks) and `facility` (facility-specific). Tiers control deployment visibility, not export control classification.

---

## Simulation Hosting

**Authoritative spec:** [Simulation Hosting Spec](spec-digital-twin-architecture.md)

Simulation Hosting provides execution infrastructure for computational models — from real-time surrogates to high-fidelity offline runs:

| Component | Description | Status |
|-----------|-------------|--------|
| **Surrogate tiers** | Tiered by latency: real-time (<100ms), interactive (seconds), planning (minutes), offline (hours) | 📋 Spec'd |
| **High-fidelity execution** | Calibrated full-physics code runs for validation and V&V | 📋 Spec'd |
| **WASM runtime** | Uniform surrogate execution with capability-based security | 📋 Spec'd ([ADR-008](../requirements/adr-008-wasm-extension-runtime.md)) |
| **Run tracking** | `dt_runs`, `dt_run_states`, `dt_run_validations` | 📋 Spec'd |
| **Provider interface** | Domain-specific simulation adapters (registered by downstream products) | 📋 Spec'd |
| **Validation framework** | Surrogate vs high-fidelity comparison, prediction vs measurement | 📋 Spec'd |
| **CLI** | `axiom sim` (run, compare, validate) | 📋 Spec'd |
| **Web UI** | Run dashboard, comparison view | 📋 Spec'd |

Model Corral and Simulation Hosting work together — models stored in Corral, executed via Simulation Hosting. Domain-specific adapters (e.g., nuclear physics codes, CFD solvers) are registered by downstream products via the provider interface.

---

## Architecture Decision Records

| ADR | Decision | Status |
|-----|----------|--------|
| [ADR-001](../requirements/adr-001-polyglot-monorepo-bazel.md) | Monorepo (Bazel dropped → pure Python) | Accepted (modified) |
| [ADR-002](../requirements/adr-002-hyperledger-fabric-multi-facility.md) | Hyperledger Fabric for tamper-proof audit | Accepted |
| [ADR-003](../requirements/adr-003-lakehouse-iceberg-duckdb-superset.md) | Iceberg + DuckDB lakehouse | Accepted |
| [ADR-004](../requirements/adr-004-infrastructure-terraform-k8s-helm.md) | Terraform + K8S + Helm | Accepted |
| [ADR-005](../requirements/adr-005-meeting-intake-pipeline.md) | Meeting intake → Signal pipeline | Accepted |
| [ADR-006](../requirements/adr-006-mcp-agentic-access.md) | MCP server for IDE integration | Accepted |
| [ADR-007](../requirements/adr-007-streaming-first-architecture.md) | Streaming-first architecture | Accepted |
| [ADR-008](../requirements/adr-008-wasm-extension-runtime.md) | WASM surrogate runtime | Proposed |
| [ADR-009](../requirements/adr-009-promote-media-internalize-db.md) | Media Library + internalize DB | Accepted |
| [ADR-010](../requirements/adr-010-cli-architecture.md) | CLI as agentic terminal (noun-verb, slash commands, terminal monitoring) | Accepted |

---

## Platform Positioning

### Why Open Lakehouse (Not Databricks/Snowflake)

| Factor | Managed Platform | Open Lakehouse |
|--------|-----------------|----------------|
| **Data sovereignty** | Vendor control plane has access | Full control over data residency |
| **Regulatory compliance** | Complex data residency requirements | On-premise, air-gappable, provider-agnostic |
| **Cost trajectory** | Per-compute pricing scales with usage | Fixed infrastructure allocation; marginal cost ~$0 |
| **Customization** | Limited to platform APIs | Full access for simulation and domain integration |
| **Lock-in risk** | High switching costs | Portable Iceberg format |

Detailed analysis: [Platform Comparison](../research/platform-comparison-databricks.md)

### Relationship to INL DeepLynx

DeepLynx and Axiom are **complementary peer platforms**, not competing:

- **DeepLynx** optimizes for relationship traversal (graph-based engineering data)
- **Axiom** optimizes for time-series analytics and agent-driven workflows

Integration via shared identifiers and APIs. Detailed analysis: [DeepLynx Assessment](../research/deeplynx-assessment.md)

---

## Research Documents

| Document | Topic |
|----------|-------|
| [State Backend Whitepaper](../research/whitepaper-state-backend-comparison.md) | Flat file vs PostgreSQL: benchmarks, token efficiency, failure modes |
| [Platform Comparison](../research/platform-comparison-databricks.md) | Axiom vs Databricks positioning |
| [DeepLynx Assessment](../research/deeplynx-assessment.md) | INL DeepLynx peer-platform analysis |
| [User Personas](../research/user-personas.md) | Operator, researcher, admin personas |

---

## Test Coverage

| Area | Tests | Status |
|------|-------|--------|
| Signal pipeline | 372 | ✅ Passing |
| Publisher | 237 | ✅ Passing |
| M-O + retention | 70 | ✅ Passing |
| State management | 64 | ✅ Passing |
| Routing + red-team | 124 | ✅ Passing |
| RAG | 36 | ✅ Passing |
| Infrastructure | 38 | ✅ Passing |
| **Total** | **~1,600** | **✅ All passing (v0.4.0)** |

Red-team framework: `tests/routing/export_controlled_prompts.txt` + `public_prompts.txt` → parametrized classifier accuracy tests across all sensitivity levels.

---

## Version History

| Version | Date | Milestone |
|---------|------|-----------|
| 0.1.0 | 2026-01 | Initial platform: docflow, CLI, GitLab sensor |
| 0.2.0 | 2026-02 | Extension system, demo, chat TUI, setup wizard |
| 0.3.0 | 2026-02 | Extension refactor, publisher consolidation, review framework |
| 0.3.2 | 2026-03 | Export control router, settings, RAG, model routing |
| **0.4.0** | **2026-03** | **State management, hybrid backend, routing Phase 2a, UX overhaul, sense→signal rename** |
