Glossary

Glossary

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CHANGELOG.md
• CONTRIBUTING.md
• Makefile
• README.md
• cmd/axis/testdata/summary_corrupt_state.golden
• cmd/axis/testdata/summary_empty_state.golden
• cmd/axis/testdata/summary_live_snapshot.golden
• docs/current-state.md
• docs/integrations/agent-hooks-and-mcp.md
• docs/phase1_spec.md
• docs/white_paper_v1.md
• hack/lifecycle-check.go
• hack/pr-review-cycle.sh
• hack/refresh-current-state.sh
• hack/test-lint-failclosed.sh
• internal/buildinfo/version.go
• internal/daemon/daemon.go
• internal/daemon/daemon_test.go
• internal/daemon/daemon_testmain_test.go
• internal/discovery/discovery.go
• internal/execution/guarded.go
• internal/execution/guarded_test.go
• internal/facts/local.go
• internal/facts/parsers_test.go
• internal/facts/remote.go
• internal/facts/turboquant.go
• internal/facts/turboquant_test.go
• internal/llmrouter/adapter.go
• internal/llmrouter/adapter_test.go
• internal/llmrouter/engine.go
• internal/mcp/server.go
• internal/mcp/server_tools_test.go
• internal/models/memory.go
• internal/models/memory_test.go
• internal/models/types.go
• internal/models/types_test.go
• internal/multipath/prober.go
• internal/placement/infer.go
• internal/placement/placement_test.go
• internal/placement/ranker.go
• internal/placement/selector.go
• internal/reservation/ledger.go
• internal/reservation/ledger_test.go
• internal/safety/blocker.go
• internal/safety/blocker_test.go
• internal/safety/structured.go
• internal/safety/structured_bench_test.go
• internal/safety/structured_test.go
• internal/snapshotview/overlay.go
• internal/transport/ssh.go
• internal/transport/ssh_config_test.go
• internal/transport/ssh_lifecycle_test.go
• internal/transport/ssh_security_test.go
• internal/turboexec/plan.go
• internal/turboexec/plan_test.go
• internal/workload/classifier.go
• internal/workload/requirements.go
• internal/workload/requirements_test.go

This page defines the core technical terms, abbreviations, and domain concepts used throughout the AXIS codebase. AXIS is a multi-layered cluster substrate designed for deterministic task placement and guarded execution.

Core Concepts & Data Models

NodeFacts

The fundamental unit of telemetry in AXIS. It represents a single point-in-time observation of a machine's hardware, software tools, and current load.

• Implementation: NodeFacts struct in internal/models/types.go:143-200.
• Key Fields: Resources (CPU/RAM/GPU), Tools (installed binaries), ResidentModels (currently loaded LLMs), and Status (Complete, Partial, Unreachable).
• Source: Collected via LocalCollector internal/facts/local.go:22-25 or RemoteCollector.

ClusterSnapshot

A collection of NodeFacts representing the state of the entire cluster. It is the primary input for the Placement Engine.

• Implementation: ClusterSnapshot struct in internal/models/types.go:300-315.
• Assembly: Built by snapshot.Build(), which deduplicates nodes and classifies network topology.

The Truth Rule

A design principle stating that no generated output (from AI or otherwise) may present itself as cluster truth unless it is backed by a real snapshot or live probe docs/current-state.md:7-8.

---

5-Layer Architecture Glossary

Layer	Name	Responsibility	Key Code Entities
L5	Advisory	AI surfaces (Chat, Agent)	Agent, MCPServer, ChatConfig
L4	Execution	Task lifecycle & safety	RunGuarded, Evaluator, Ledger
L3	Placement	Deterministic node selection	FilterCandidates, RankCandidates
L2	Snapshot	State caching & triggers	Daemon, SnapshotCache, state.json
L1	Fact Plane	Hardware/Tool discovery	LocalCollector, SSHExecutor, Beacons

Sources: README.md:23-45, docs/current-state.md:20-71

---

Technical Terms (A-Z)

Allocatable RAM

The portion of total RAM available for AXIS tasks after subtracting the SystemReserveMB (OS overhead) and EvictionReservedMB (safety floor).

• Logic: Calculated in PopulateMemoryMetrics internal/models/types.go:151-170.

Beacon (UDP)

A lightweight UDP packet emitted by nodes to announce their presence to the cluster. Used for discovery without pre-configuring IP addresses.

• Implementation: BeaconRegistry in internal/daemon/daemon.go:88.

Deterministic Placement

The guarantee that given the same ClusterSnapshot and TaskRequirements, AXIS will always select the same node. This is achieved via a 10-level tie-breaking sort in RankCandidates internal/placement/ranker.go:55-67.

FitScore

A 0-100 score indicating how well a node matches a task. Unlike the deterministic rank, this is used for advisory UI display.

• Implementation: ComputeTaskFitScore in internal/placement/selector.go.

Guarded Execution

A task execution pattern where the command is parsed, evaluated against a RuleSet for safety, and executed only if it passes security gates.

• Implementation: RunGuarded in internal/execution/guarded.go.

Reservation Ledger

A double-entry accounting system that tracks RAM and VRAM committed to in-flight tasks to prevent oversubscription before the next fact refresh.

• Implementation: reservation.Ledger in internal/reservation/ledger.go.

Resident Model

An LLM that is already loaded into memory on a node (e.g., in Ollama or llama.cpp). AXIS prioritizes these nodes to avoid model load latency.

• Detection: Probed via discoverOllamaLocal internal/facts/local.go:105-115.

TurboQuant

An AXIS-specific optimization for Apple Silicon and Linux backends (MLX, llama.cpp) that allows for aggressive RAM reduction and long-context placement.

• Implementation: TurboQuantInfo struct in internal/models/types.go.
• Logic: detectTurboQuantSupport in internal/facts/local.go:125.

---

System Diagrams

Natural Language to Code Entity: Placement Pipeline

This diagram bridges the user's intent (natural language) to the specific code functions that handle the decision-making process.

graph TD
    UserIntent["'Run inference on 7b model'"] -- "1. workload.InferRequirements()" --> Req["models.TaskRequirements"]
    Req --> Filter["placement.FilterCandidates()"]
    Snap["models.ClusterSnapshot"] --> Filter
    
    subgraph "Layer 3: Placement Engine"
        Filter -- "2. Eligible Nodes" --> Rank["placement.RankCandidates()"]
        Rank -- "3. Sorted Keys" --> Select["placement.SelectBestNode()"]
    end
    
    Select --> Decision["placement.PlacementDecision"]
    Decision --> UI["axis task place output"]

Loading

Sources: internal/placement/ranker.go:37-45, internal/placement/ranker.go:68-202, README.md:121-151

Code Entity to Data Flow: Fact Collection

This diagram shows how raw system commands map to the NodeFacts entity used by the rest of the system.

graph LR
    subgraph "OS Probes (internal/facts/local.go)"
        P1["'sw_vers' / 'uname'"] --> OS["facts.OSVersion"]
        P2["'df' / 'free' / 'sysctl'"] --> Res["models.Resources"]
        P3["'ollama ps' / 'v1/models'"] --> RM["models.ResidentModels"]
        P4["'nvidia-smi' / 'ioreg'"] --> GPU["models.GPUInfo"]
    end

    OS --> NF["models.NodeFacts"]
    Res --> NF
    RM --> NF
    GPU --> NF

    NF -- "JSON Marshal" --> SSH["transport.SSHExecutor"]
    SSH -- "Network" --> Daemon["internal/daemon/daemon.go"]
    Daemon --> Cache["~/.axis/state.json"]

Loading

Sources: internal/facts/local.go:52-143, internal/models/types.go:57-107, internal/transport/ssh.go:85-94

---

Abbreviations

Abbreviation	Full Term	Context
MCP	Model Context Protocol	Standard for connecting AI agents to AXIS tools/resources.
PSI	Pressure Stall Information	Linux kernel metric used to filter nodes under heavy load.
VRAM	Video RAM	Memory dedicated to GPUs, tracked for inference placement.
NDJSON	Network Delimited JSON	The streaming format used by axis task run for logs.
ULA	Unique Local Address	IPv6 address type handled during network classification.

Sources: internal/models/types.go:86-88, docs/current-state.md:39-40, CHANGELOG.md:4-5