# Five Rings

## Ring 1: Kernel

**Zero external dependencies.** The kernel defines the type system that every other ring builds on.

- **`WorldDAG`** — Directed acyclic graph with cycle detection, topological sort, d-separation (Bayes-Ball algorithm), backdoor adjustment set computation, and path enumeration.
- **`Entity`** — Frozen dataclass representing a DAG node. Fields: `entity_id`, `name`, `causal_role`, `variable_type`, optional bounds and description.
- **`CausalEdge`** — Frozen dataclass representing a directed causal mechanism. Fields: `source`, `target`, `mechanism`, `confidence`, `soliton_score`, `provenance`.
- **`AuditLog`** — Hash-chained append-only log. Each entry links to the previous via SHA-256. Supports tamper detection and search by action/actor.
- **Crypto** — `hash_sha256`, `generate_token`, `constant_time_compare`. All built on `hashlib` and `secrets`.

## Ring 2: Credit Risk

Domain-specific credit risk modeling built on the World DAG.

- **Ontology** — 19 variables covering macroeconomic indicators (GDP, unemployment, interest rates), borrower characteristics (income, credit score, DTI), and loan performance (delinquency, default). Organized into CCAR, CECL, CFPB, and macro regulatory groups.
- **Causal PD Model** — Probability of default model fitted along causal paths in the DAG. Supports observational and interventional prediction.
- **CECL Engine** — Expected credit loss with dynamic forecast horizons, per-segment breakdown, and confidence bands.
- **Scenario Engine** — Stress testing with baseline, adverse, and severely adverse scenarios (CCAR/DFAST compliant).
- **Fair Lending** — Causal path decomposition of protected-attribute effects. Separates direct discrimination from indirect effects through legitimate mediators.
- **Synthetic Data** — Generates data that respects causal ordering and interventional semantics.

## Ring 2: Data Fabric

Data infrastructure for ingestion, validation, and lineage.

- **Connectors** — CSV, JSON, and dict-based data ingestion with schema validation.
- **Schema** — Column definitions with types, bounds, nullability, sensitivity levels, and allowed values.
- **Profiler** — Statistical profiling (mean, std, percentiles, null counts, unique counts) per column.
- **Quality Gates** — Composable predicates: completeness, bounds, type, uniqueness, freshness, and custom. Pipeline runs all gates and produces pass/fail report with scores.
- **Lineage** — Tracks data provenance as edges in the World DAG. Supports upstream/downstream tracing and impact analysis.
- **Catalog** — Dataset registry with tagging, search, and summary.

## Ring 3: Intelligence

Causal discovery and validation algorithms.

- **PC Algorithm** — Constraint-based discovery. Phase 1: build skeleton via conditional independence tests. Phase 2: orient edges using Meek's rules (collider detection, acyclicity).
- **GES Algorithm** — Score-based discovery. Forward phase adds edges to optimize BIC. Backward phase prunes edges that don't improve the score.
- **Consensus Engine** — Runs PC and GES, includes edges where a configurable threshold of algorithms agree. Optional bootstrap stability scoring.
- **Independence Testing** — Partial correlation with recursive formula and Fisher z-transform for significance.
- **D-Separation Tester** — Tests all d-separation implications of a DAG against observed data. Reports violations sorted by p-value.
- **Refutation Suite** — Placebo test (permute treatment, check if effect vanishes) and subset stability test (cross-validation across data subsets).

## Ring 4: Orchestration

Task scheduling and agent coordination. Currently in progress.

## Ring 5: Experiences

User-facing interfaces.

- **CLI** — `orxaq` command with subparsers for every operation. `--json` flag on all commands for machine-readable output.
- **API Server** — Local HTTP server (stdlib `http.server`) with 8 JSON endpoints wrapping the OrxaqEngine facade.
- **Gamma Observatory** — Self-contained HTML dashboard with D3.js force-directed DAG visualization, bento tile metrics, stress test display, fair lending analysis, and audit trail table.
