Angel Architecture¶

This is the canonical, current description of the Magi Angel libraries: what an Angel is, the disciplines every Angel obeys, the live build status, the island-clean dependency graph, and the per-Angel technical blueprints. It consolidates and supersedes the earlier scattered notes; where this document and an older note disagree, this document is correct.

What an Angel is¶

An Angel library satisfies two conditions at once:

Load-bearing inside Magi: Magi does not function fully without it.
Independently deployable: droppable into any project, with any CI system, with no Magi dependency, delivering value on its own.

Angels are named after the Angels in Neon Genesis Evangelion. They are a different naming domain from the MAGI supercomputers (Melchior, Balthasar, Casper), which are the platform's evaluation / protection / delivery pillars, not libraries.

The disciplines¶

Every Angel obeys four laws. They are not style preferences; they are what make an Angel an Angel.

1. Island discipline¶

An Angel has ZERO dependency on any other part of the ecosystem, including peer Angels. "Magi" here means the whole contextual ecosystem, everything we build, not just the Melchior / Balthasar / Casper pillars. An Angel may use third-party OSS directly (CUE, Automerge, wasmtime, tree-sitter, Firecracker, Quinn, and so on). It must not import a peer Angel's library. Conceptual reuse is fine: two Angels can both validate with CUE. Library coupling is not: neither imports a "Ramiel" package.

This is what lets any Angel ship now, on its own timeline, before the ecosystem is complete. Inter-Angel dependencies would block you (you could not ship Sachiel until Ramiel existed) and defeat the entire point.

This law retires an earlier design: the 2026-05-27 blueprints had Sachiel / Gaghiel / Tabris / Zeruel "use Ramiel" and shared an Automerge / WASM substrate across Angels. That coupling is gone. Each Angel embeds its own OSS-based validation / CRDT / plugin logic. The corrected dependency graph has 13 nodes and zero Angel-to-Angel edges, only Angel-to-OSS edges. There is no build-order constraint.

2. The LLM is an add-on, never the engine¶

Every Angel has a deterministic core: same input, same output, no model, no network in the hot path. An LLM may sit on top as an optional, off-by-default seam (narrate a finding, author a contract, label an inferred schema). It is never the thing doing the work. This mirrors every other piece of real machinery: the model is an accessory bolted to a deterministic mechanism.

3. Right tool, not default language¶

Choose the language and substrate by performance and fitness for the specific job, never by comfort or reputation. Two mirrored reflexes to avoid:

Do not default to Python because it is comfortable. Leliel's single largest performance gain was its full-Julia rewrite.
Do not default to Rust because it is the safe, "correct", swiss-army-knife answer. Reaching for Rust on reputation is the same reflex as Python, badged as correctness. Rust is not automatically right or performant.

The positive rule, the right factory: performance is a first-class priority. Do not build bloated infrastructure in the name of correctness when the right specialized tool for performant heavy-lifting is in front of you.

Numerical / linear-algebra / quantum heavy-lifting: Julia (Leliel's core).
Time-tested, reliable, bulletproof infrastructure / policy / CLI binaries: Go (single static binary, zero interpreter dependency, battle-tested). The host language for a tree-sitter analyzer is not the heavy lift; the C grammar is. Pick the language that ships a clean bulletproof binary.

State, at every build, why the chosen tool is the right factory for that job's performance and fitness profile.

4. The standard¶

A component qualifies as an Angel when it answers YES to all of:

Can it be installed into a non-Magi project without pulling in Magi dependencies?
Does it have a documented standalone deployment path?
Is its integration point CI-system agnostic?
Does it deliver standalone value before Magi is involved?
Can it be versioned and released independently?

Live status¶

Release stages (dev-aligned, not marketing labels):

pre-alpha: designed or blueprinted, not yet built (or built but not yet functional)
alpha: built, the core works, narrow feature set, not hardened
beta: functionally complete for real use, under testing and hardening
stable: production-ready, meets the Angel standard in full

Angel	Role	Stage	Language	Repo
Ireul	Docs infrastructure	stable (meets the standard)	Python / MkDocs (pip-from-URL)	Cloudflare Pages
Leliel	Knowledge / retrieval engine	beta (packaging gap only)	Julia	rtsko/leliel
Arael	Static auditor	alpha	Python today, flagged to reconsider Go	rtsko/arael
Ramiel	Policy / contract enforcer	alpha	Go	rtsko/ramiel
Sachiel	Signal normalizer	pre-alpha (build queue #3)	undecided (schema/Arrow heavy)	-
Shamshel	Connection manager	pre-alpha (build queue #4)	undecided (QUIC, Quinn is Rust)	-
Gaghiel	Protocol bridge	pre-alpha	-	-
Israfel	Fan-out coordinator	pre-alpha	-	-
Sandalphon	Ephemeral env manager	pre-alpha	-	-
Matarael	Fault injector	pre-alpha	-	-
Sahaquiel	Progressive delivery	pre-alpha	-	-
Bardiel	Extension protocol	pre-alpha	-	-
Zeruel	Load generator	pre-alpha	-	-
Armisael	Reconciliation engine	pre-alpha	-	-
Tabris	Contract mock server	pre-alpha	-	-

Notes on status:

Leliel: schema-agnostic ingest is real and proven (run independently on arbitrary corpora with no Melchior-formatted data and no Melchior dependency). The remaining gap to the standard is PACKAGING, not coupling: a thin client / SDK, standalone deployment docs with no Jenkins or Melchior mention, and a standalone Docker Compose.
Arael shipped in Python by the comfort reflex. Per discipline 3, its substrate is flagged for reconsideration toward Go: a tree-sitter analyzer's heavy lift is the C grammar, so the host's job is to ship a clean single binary, which is Go's lane, not a reason to reach for Rust.
Ramiel is the first Angel built to discipline 3: Go, because CUE is Go-native and Go ships a single bulletproof binary.

Build queue¶

Per the island-clean re-blueprint, there is no build-order constraint; each Angel ships on its own timeline. The working priority is:

Arael (tree-sitter + CST walk) - alpha. Scope: struct-field-coverage rule + a secret/PII pattern bank as findings, runnable as an isolated CI job. The field-coverage rule catches a real defect class no off-the-shelf tool catches (a struct grows a field, a copy/rebuild site silently omits it, the type is still valid, no test fails). LLM seam: narrate a finding only.
Ramiel (CUE) - alpha. Scope: single-pass all-violations report, bidirectional boundary validation, content-hashed version-diff classification (the enforceable-manifest ingest contract). LLM seam: author or explain contracts.
Sachiel (schema trie + Apache Arrow + CUE). Alpha scope: runtime schema inference + a KL-divergence drift envelope {schema_id, confidence, drift_flags, payload}. Directly relevant to Leliel's own Angel-graduation gap (schema-agnostic ingest). LLM seam: label inferred schemas.
Shamshel (QUIC via Quinn + OTLP). Alpha scope: a published connection state machine + circuit breaker + app-level health probe. The clean LLM-optional-often-absent exemplar (no natural LLM role).

OSS backbone¶

Verified real, maintained, and license-clean as of May 2026: CUE, Extism, Quinn, Turmoil, Firecracker, Nix, Automerge 2.0, Smithy 2.0, tree-sitter, Aya / eBPF-tc, Apache Arrow.

One fit-correction: Extism is a plugin runtime, not the full WASM Component Model. For Angels that need WIT-world capability typing (Bardiel, Israfel), drop to wasmtime + wit-bindgen rather than Extism. They remain island-clean (each embeds its own host). Turmoil's alternative is madsim.

Per-Angel technical blueprints¶

Each design avoids industry-standard tooling in favor of a bespoke approach over an OSS substrate, and each embeds its own substrate (no peer-Angel import).

Sachiel: Signal Normalizer¶

Unsolved problem: every ingest layer requires declaring the expected schema before data arrives. Sachiel infers schema at runtime from observation, no pre-registration.

Schema trie: a prefix tree of observed field paths; each node records the type-distribution across payloads and emits the maximum-likelihood type per path.
Normalization: coerces each value to its canonical type with a confidence score; near-tied types are emitted as a tagged union, not a coerced scalar. Sachiel does not discard data.
Drift detection: a KL-divergence check on the per-field type distribution; a field diverging beyond threshold from its baseline emits a drift event atomically with the normalized payload.
Internal representation: Apache Arrow columnar state for cache-friendly high throughput.
Output envelope: {schema_id, confidence, drift_flags, payload}, schema_id being a content hash of the trie snapshot so consumers can cache decoders by version.

Key property: drift detection (telling you the schema changed before you realize you need to update) does not exist in Avro / Protobuf schema registries.

Shamshel: Connection Manager¶

Unsolved problem: TCP keepalives detect dead connections but give no structured state model. Shamshel gives a typed event for every transition.

Transport: QUIC via Quinn (0-RTT resumption, stream multiplexing, connection migration).
State machine with published transitions: Embryonic to Connecting to Healthy to Degraded to Recovering to Terminated, each transition emitting a structured event (reason, latency-at-failure, retry count, backoff, fingerprint).
Observability: events as OpenTelemetry spans; any OTLP collector receives them with no custom integration.
Circuit breaker lives inside the state machine; Degraded applies exponential backoff with jitter; threshold moves to Terminated and emits circuit_open as an event, not an exception.
Health checking: application-level ping/pong over a dedicated QUIC stream, catching semantically dead connections that transport keepalives miss.

Ramiel: Contract Enforcer (alpha, Go)¶

Unsolved problem: JSON Schema validation short-circuits on first failure and throws. Ramiel collects all violations in one pass and returns a structured report.

Contract language: CUE. Its constraint model is a lattice: a value is simultaneously a value and a constraint, and constraints compose by unification (intersection). Contracts compose by unifying, with no inheritance or merge logic.
Validation pass: every field against every applicable constraint at once; each violation is a structured record {field_path, constraint_kind, expected, observed, severity}.
Bidirectional enforcement: validate both directions at every boundary (request in, response out), so a server that violates its own contract is caught before the client sees malformed data.
Contract versioning: each contract is content-addressed; Ramiel diffs versions and classifies every change as additive, breaking, or compatible, so CI can gate on contract-breaking changes.

As shipped (rtsko/ramiel): Go, CUE-native via cuelang.org/go, single static binary, island-clean (only direct dep is CUE), LLM-optional, value-withholding secret detector, synthetic fixtures.

Gaghiel: Protocol Bridge¶

Unsolved problems: existing bridges require declaring both sides before deployment; bridging sync callers to async backends loses the back-pressure signal.

Protocol fingerprinting: sample wire bytes and match against probabilistic signatures (HTTP/1.1, HTTP/2, gRPC, WebSocket, AMQP, NATS); custom protocols register as WASM plugins implementing a fingerprinting interface.
Translation graph: once both sides are identified, select a translation path from a directed graph of WASM-plugin translators, loadable at runtime, choosing the shortest path that preserves the caller's declared semantics.
Canonical IR: CloudEvents, making the translator library O(N) not O(N^2).
Back-pressure: credit-based flow control; with no credit the sync caller receives 429 with a computed Retry-After rather than blocking. The replenishment rate is exposed as a metric.

Israfel: Fan-out Coordinator¶

Unsolved problem: parallel-work libraries handle split / execute / collect but not lock-step checkpoints where partial completion is a rollback, not a partial success.

Worker substrate: WASM components (its own wasmtime host), run locally or remotely over QUIC.
Checkpoint barriers: every worker must emit a typed result before any worker proceeds; on failure, three configurable strategies: rollback (rewind via registered inverse), halt, or replace.
Mandatory rollback handler: a worker without a rollback handler is rejected at registration time.
State between checkpoints: an Automerge CRDT document (vendored independently); a replacement worker initializes from the convergent view of successful workers' partial progress.

Sandalphon: Ephemeral Environment Manager¶

Unsolved problem: ephemeral environments leak and can refuse teardown. Sandalphon provides unconditional lifecycle management with formal isolation.

Isolation: Firecracker microVMs (boot under 125ms, under 5 MiB overhead, KVM-isolated, destroyed by terminating the VM process so the workload cannot refuse to die).
Environment spec: a Nix derivation, content-addressed and reproducible bit-for-bit.
Lifecycle: Requested to Provisioning to Active to Draining to Terminated, with a hard deadline set at provision time and unconditional destruction at deadline (no extension mechanism).
Credential injection: secrets delivered via virtio-vsock at provision time, never baked into the Nix store or any content-addressed artifact.

Matarael: Fault Injector¶

Unsolved problem: chaos tools inject independent failures; real incidents are compound. Matarael models failure as a composition with timing dependencies.

Level 1 (simulation): Turmoil deterministic single-process network simulation, wrapped with a fault composition language (A then B, A while B, B triggers when A.at_steady_state, A repeats every N seconds with jitter J). Every run is byte-for-byte reproducible.
Level 2 (kernel-level, black-box): eBPF programs on the tc subsystem injecting packet drop / delay / corruption / reset with sub-millisecond precision, compiled from a fault definition to bytecode.
Gradual degradation: every fault has a ramp (linear, sigmoid, step) so a latency fault looks like a real degrading network.

Key property: deterministic, replayable, commitable-as-a-test simulation, which Chaos Monkey and Gremlin (non-deterministic by design) do not provide.

Sahaquiel: Progressive Delivery Coordinator¶

Unsolved problem: canary systems gate on point-in-time thresholds. Sahaquiel gates on the posterior probability of health.

Bayesian gate: each stage runs a sequential Bayesian hypothesis test; the gate advances when the posterior probability of health exceeds a credible-interval threshold and halts when failure probability exceeds the abort threshold.
Stage sizing via Thompson sampling: deeply healthy stages get larger next steps, marginal stages smaller steps and longer windows.
Metric input: OTLP, any compatible source.
Irrevocable commit: the 100% Body stage is a separate explicit commit(); Sahaquiel never auto-commits.

Bardiel: Extension Protocol¶

Unsolved problem: every extensible application reinvents the plugin protocol. Bardiel is the protocol itself, portable and formally specified.

Plugin substrate: WASM components, with WIT as the interface definition language (wasmtime + wit-bindgen for capability typing). A plugin implements a WIT interface; the host is language-agnostic.
Capability model: each plugin declares required capabilities in its WIT world; a mismatch against what the host grants is rejected at load time (structural, not string-based).
Hook registry: publishers declare named WIT-interface hooks; consumers register ordered handlers; a panicking handler is caught by the WASM sandbox and surfaced as a structured error.

Zeruel: Load Generator¶

Unsolved problem: load generators produce fixed rates or step ramps; real traffic arrives as a distribution. Zeruel models arrival stochastically and reports the capacity that would have prevented each break.

Arrival model: a parameterized stochastic process (Poisson by default, Pareto for bursty, or fit to a recorded trace and replayed at any scale factor).
Progressive layer testing: latency stability, then error-rate inflection, then throughput ceiling, each reported separately.
Capacity planning: an M/G/1 queueing model translates inflection points into provisioning targets ("to handle 10,000 req/s at your p99 target you need about 2.4x current capacity at the bottleneck").

Arael: Static Auditor (alpha)¶

Unsolved problem: static analysis runs inside the build pipeline, which can suppress it. Arael runs in isolation and uses structural analysis, not text matching.

Parse engine: tree-sitter (one library, consistent S-expression queries across many languages).
Rule categories: structural patterns (tree-sitter queries), dependency-graph rules, secret-entropy rules (Shannon entropy on string literals), and contract-surface rules.
Flagship rule struct-field-coverage: extracts the field set at a struct definition and the assigned-field set at each constructor / copy / rebuild site, then flags the set-difference. This catches a defect class no off-the-shelf tool catches (tree-sitter alone cannot do the cross-node set difference; semgrep is partial; type checkers catch a different class). It is the exact bug shipped twice during Leliel development.
Output: structured findings naming category and location, never the matched value.

As shipped (rtsko/arael): the field-coverage rule + a secret/PII pattern bank, generic detectors in the committed source and org-specific patterns loaded at runtime from a gitignored local file. Language flagged for reconsideration toward Go per discipline 3.

Armisael: Reconciliation Engine¶

Unsolved problem: diff tools produce a list of changes, not a merge. Armisael produces a CRDT document representing both views with a convergent result.

Substrate: Automerge (vendored independently); non-conflicting changes merge automatically, conflicts preserve both values as concurrent operations for caller resolution.
The double helix: every reconciliation produces a forward transform and its inverse at once, so the rollback path is a first-class output computed from the operation log.
Structural pre-pass: a Difftastic-inspired tree-sitter parse maps semantically equivalent content (renamed field, reordered set-equal array, restructured nesting) to identity operations before merge, so a rename is not treated as delete-plus-insert.

Tabris: Contract Mock Server¶

Unsolved problem: mock servers let you return anything, training clients on data the real server would never produce. Tabris enforces the contract in both directions.

Contract language: Smithy (operations with typed inputs / outputs plus trait annotations); the Smithy model generates both the mock server and the validation logic.
Bidirectional enforcement: incoming requests validated against the input shape (a malformed request gets a structured violation report, not a 500); outgoing responses validated against the output shape before sending (an invalid mock configuration is rejected at configuration time). Both validations embed CUE directly (no Ramiel import).
Property-based generation: for operations without a fixture, responses are sampled from the output shape's constraints, exercising the client across the full range of valid responses.
Trait enforcement: @idempotent (repeated requests produce the same response) and @readonly (the handler cannot mutate state).

Provenance¶

This document consolidates: the Angel definition and island discipline (memory: project_angel_libraries), the full per-Angel blueprints (memory: project_angel_libraries_architecture, 2026-05-27, corrected here for island discipline), and the current-truth corpus findings principle-angel-island-discipline, principle-llm-is-an-addon-not-the-engine, charter-right-tool-not-default-python, result-implementation-lens-angel-reblueprint, milestone-arael-shipped, and milestone-ramiel-angel2-shipped-go.