Skip to content
Tribunus

Architecture Decision Records

Architecture Decision Records capture the rationale behind every significant design choice in Tribunus Compute. Each ADR is a self-contained document that states the context, the decision, and the consequences.

Scope

Section titled “Scope”

ADRs in this section cover backend abstraction layers, runtime pipeline topology, plugin loading strategies, protocol wire formats, concurrency models, and resource governance. They are the authoritative source of truth for why Tribunus is built the way it is.

ADR Register

Section titled “ADR Register”

  • ADR 0034 — Compiled Backend Inference Architecture: Every inference path is decided before the first token is generated. The compiler owns placement, memory layout, kernel selection, and fallback policy. This eliminates runtime branching in the hot path and enables forward‑declared autotuning.

  • ADR 0037 — Backend Realization Contract: Each backend implements a shared Realizer trait that exposes compile, load, admit, and execute phases. The RealizerError 11‑type taxonomy covers every failure mode from compilation through runtime replay, ensuring that no backend error escapes unclassified.

  • ADR 0038 — Numerical Governance and Autotuning: Apple Silicon FP32 serves as the golden reference for numerical accuracy. A 4‑tier oracle (Exact, Approximate, Heuristic, Unverified) establishes ground truth per operation, per backend, and gates candidate kernels during admission. Autotuning produces a ranked kernel cache keyed on operation signature, dtype, and memory layout.

  • ADR 0039 — Tribunus Datacenter Control Plane (Dharma): Semi‑trusted peer networks for mutual‑aid inference with quorum‑verified execution. Dharma nodes exchange ACP frames over a NATS mesh, challenge each other’s results via cryptographic attestation, and settle disputes through a configurable quorum policy. The design favours Byzantine fault tolerance over raw throughput.

  • ADR 0040 — Runtime Inference Pipelines: Six precompiled pipeline stages (Ingest, Prepare, Execute, Admit, Aggregate, Emit) form a deterministic state machine for inference. Each stage is a compiled kernel group; stage transitions are data‑driven and never block on dynamic dispatch. Pipelines are assembled at compile time and serialised into the compute image.

  • ADR 0041 — Memory Architecture and Weight Staging: Memory management strategies for compute image execution, covering weight residency (on‑device vs. host‑pinned), staged loading across PCI‑e or UMA, and transparent fallback from VRAM to system memory under pressure. The architecture guarantees that weights are ready before the pipeline reaches the Execute stage.

Lifecycle

Section titled “Lifecycle”

Each ADR passes through Proposed, Accepted, Superseded, and Deprecated states. Superseded records link to their replacement and preserve the chain of reasoning. This makes the archive navigable both as a reference and as a historical log of how the architecture evolved.

Source-Backed

Section titled “Source-Backed”

Every ADR is generated from structured metadata stored alongside the codebase. When the corresponding implementation changes, the ADR is updated or flagged for review — the records do not drift from what the code actually does.