______________________________________________________________________

title: T81 Foundation Specification — Axion Kernel
nav:

- [Overview](t81-overview.md)
- [Data Types](t81-data-types.md)
- [TISC Specification](tisc-spec.md)
- [T81 Virtual Machine](t81vm-spec.md)
- [T81Lang](t81lang-spec.md)
- [Axion Kernel](axion-kernel.md)
- [Cognitive Tiers](cognitive-tiers.md)

______________________________________________________________________

[← Back to Spec Index](index.md)

# Axion Kernel Specification

Version 1.0 — Alpha

Status: Alpha\
Last Revised: 2026-03-16\
Applies to: T81VM, TISC, T81Lang, Cognitive Tiers

The **Axion Kernel** is the supervisory intelligence of the T81 Ecosystem.\
It enforces:

- deterministic execution invariants
- safety and recursion bounds
- ethics / policy constraints
- canonicalization of complex transformations
- tier transitions for advanced reasoning workloads

Axion does **not** execute user code; rather, it governs **how** code may execute.

This document defines Axion’s responsibilities, invariants, hooks, visibility, and interaction model.

______________________________________________________________________

# 0. Architectural Role

Axion sits **above** all executable layers:

```

┌─────────────────────────────┐
│     Cognitive Tiers         │
├─────────────────────────────┤
│        Axion Kernel         │  ← THIS LAYER
├─────────────────────────────┤
│ T81VM  |  TISC  |  DataTypes│
├─────────────────────────────┤
│           System            │
└─────────────────────────────┘

```

Axion:

- supervises T81VM state transitions
- vets TISC privileged instructions
- verifies safety and determinism
- enforces complexity and recursion limits
- anchors cross-tier invariants

______________________________________________________________________

# 1. Responsibilities

Axion has seven core responsibilities.

## 1.1 Determinism Stewardship

Axion MUST:

- receive a complete trace of T81VM state transitions
- detect nondeterministic patterns
- reject any state transition that violates deterministic semantics
- enforce canonical memory after GC or compaction

Axion is the final arbiter of “deterministic enough.”

> **Implementation status (AX-M5):** Determinism stewardship is partially
> implemented. `axion_log` captures instruction events but does not yet perform
> active nondeterminism detection (cross-run divergence comparisons). Active
> detection is AX-M5, targeting 2026-03-14.

## 1.2 Safety & Ethics Enforcement

Axion MUST enforce:

- safe memory operations
- security boundaries (especially around AXSET, AXREAD, AXVERIFY)
- resource ceilings
- recursion depth bounds
- purity / effect constraints at runtime
- cognitive escalation gating

Axion MAY terminate execution if invariants are violated.

## 1.3 Complexity Measurement

Axion measures:

- recursion depth
- call graph complexity
- tensor and matrix operation complexity
- shape explosion
- branching factor and path divergence

These metrics guide tier transitions.

> **Implementation status:** Complexity measurement currently tracks call depth
> and tensor operation counts. Call graph complexity, shape explosion detection,
> and branching factor metrics are not yet implemented.

## 1.4 Tier Supervision

Axion:

- promotes/demotes computation across cognitive tiers
- ensures that tier-appropriate invariants hold
- blocks entry into tiers requiring explicit annotation (e.g., Tier 3 deep recursion)

Tier rules are defined in `cognitive-tiers.md`.

> **Conformance program:** [`spec/conformance/axion-kernel/tier-supervision-invariant.t81`](conformance/axion-kernel/tier-supervision-invariant.t81)

## 1.5 Metadata Hosting

Axion maintains the META segment:

- fault history
- safety markers
- canonicalization logs
- GC and relocation logs
- configuration versions
- recursion depth counters

Axion MUST keep metadata deterministic and canonical.

> **Conformance program:** [`spec/conformance/axion-kernel/metadata-determinism.t81`](conformance/axion-kernel/metadata-determinism.t81)

Axion also ingests the loop hints, match metadata s-expressions, and enum metadata described in [RFC-0019](../spec/rfcs/RFC-0019-axion-match-logging.md). The compiler populates `tisc::Program.axion_policy_text`, `match_metadata_text`, and `enum_metadata` so the runtime can emit deterministic `EnumIsVariant`/`EnumUnwrapPayload` events whose `AxionEvent.verdict.reason` strings include `enum=<name>`, `variant=<name>`, `payload=<type>`, and the guard result (`match=pass`/`match=fail`). These entries give DTS/VS the canonical guard context they need to enforce safety and determinism.

## 1.6 Privileged Instruction Arbitration

Axion is the arbiter of:

- `AXREAD`
- `AXSET`
- `AXVERIFY`

All privileged operations MUST invoke Axion before evaluating their effects.

## 1.7 VM Integration

Axion is not technically part of T81VM, but all VM behavior MUST be visible and conformant to Axion's expectations.

## 1.8 Deterministic Segment Trace

Axion also receives a deterministic trace of every segment transition and guarded decision inside the HanoiVM as described in [RFC-0020](../spec/rfcs/RFC-0020-axion-segment-trace.md). Each `AxionEvent.verdict.reason` includes the segment name, address, and action (e.g., `stack frame allocated stack addr=243 size=16`, `tensor slot allocated tensor addr=5`, `meta slot axion event segment=meta addr=1283`, `AxRead guard segment=stack addr=42`, `AxSet guard segment=heap addr=128`). CanonFS writes traverse `AXSET`/`AXREAD`, trigger the same meta-slot logging, and emit `meta slot axion event segment=meta ... action=Write/Read` so policy runners can enforce persistence guards deterministically. These strings anchor Axion policies and audits to the runtime's deterministic layout without requiring additional instrumentation. Axion MUST reject programs whose required segment-trace strings are missing when the policy explicitly requests them.

> **Implementation status (AX-M6):** The full canonical reason string form
> `segment=<name> addr=<value> action=<desc>` is the normative target. Current
> implementation emits the segment, address, and action fields as separate
> structured `AxionEvent` fields; verbatim concatenated string construction is
> AX-M6, targeting 2026-03-14.
>
> **Conformance program:** [`spec/conformance/axion-kernel/segment-trace-strings.t81`](conformance/axion-kernel/segment-trace-strings.t81)

## 1.9 Axion API & Policy Enforcement

The Axion Kernel exposes a constrained syscall surface (`AXREAD`, `AXSET`, `AXVERIFY`, `AXTRACE`, etc.) that every privileged opcode must call before performing non-deterministic or privileged actions. Each syscall supplies the opcode, the target addresses or handles, the calling snapshot, and any associated guard metadata (loop id, match metadata, enum/variant ids). The Axion Engine returns a deterministic `Verdict` (Allow/Deny) plus a canonical `reason` string. Denials immediately trigger deterministic `Axion Faults`; allows append the reason to `State::axion_log`.

Policies are encoded via the `(policy ...)` s-expression embedded in `tisc::Program.axion_policy_text`. Axion parses these forms (see `include/t81/axion/policy.hpp`) and enforces:

- tier ceilings (`tier`, `max-stack`);
- guard coverage (`require-match-guard`);
- loop hints (`require-loop-hint`);
- segment traces (`require-segment-event`).

Regression tests `axion_policy_match_guard_test` and
`axion_policy_segment_event_test` exercise those requirements against the
canonical `enum guard` and `stack frame allocated` strings, proving that the
policy engine never allows a privileged opcode unless the deterministic
trace strings already exist in `State::axion_log`.

Because the policy lexer is deterministic and the verdict strings are canonical (per RFC-0020/RFC-0019), Axion's policy enforcement remains purely declarative: it denies unless the runtime has already emitted the expected strings.

> **Conformance programs:** [`spec/conformance/axion-kernel/policy-deny-requires-reason.t81`](conformance/axion-kernel/policy-deny-requires-reason.t81) · [`policy-enforcement-allow-deny.t81`](conformance/axion-kernel/policy-enforcement-allow-deny.t81)

## 1.10 CanonFS Observability

Canonical File System (CanonFS) is the deterministic store where Axion writes loop/match policy hints, bounds-fault snippets, and trace exports. Each CanonFS write traverses `AXSET`, so Axion can validate shape/segment constraints and record `meta slot` events before persistence. The `axion_policy_runner` example (documented in `docs/guides/axion-trace.md`) mirrors this path and shows auditors how to capture the required `verdict.reason` strings without digging into VM sources. CanonFS therefore acts as the official audit trail for Axion policy enforcement, and the persistent driver described in `spec/supplemental/canonfs-spec.md` guarantees those `meta slot axion event segment=meta ... action=Write/Read` strings fire before bytes hit `objects/<hash>.blk`.

> **Implementation status (AX-M7):** CanonFS observability integration is
> partial. Full `AXSET` propagation to CanonFS meta slots and end-to-end
> `meta slot axion event` emission for all persistence paths is AX-M7,
> targeting 2026-03-14.

______________________________________________________________________

# 2. Subsystems

> **Implementation status note:** The five subsystems described below are
> **architectural targets**. In the current implementation their functionality
> is distributed across `kernel/axion/policy_engine.cpp` and `core/vm/vm.cpp`
> rather than realized as distinct classes with formal boundaries. Formal
> subsystem separation is a post-Alpha milestone.

Axion consists of **five deterministic subsystems**.

## 2.1 Deterministic Trace Subsystem (DTS)

DTS receives:

- executed instruction address
- all register deltas
- memory writes (structural granularity)
- faults
- GC movements
- scheduling decisions
- loop guard metadata extracted from `axion_policy_text` and match guard metadata (variant ids, declared payload types, guard presence) captured by `EnumIsVariant`/`EnumUnwrapPayload` events. These guard-aware logs show the file/line/column hint, the canonical enum/variant identity, the guard result, and payload reason strings, so DTS keeps a complete, deterministic record of guard coverage together with the normal instruction trace.

DTS MUST maintain a **canonical record** of the program's observable behavior.

## 2.2 Verification Subsystem (VS)

Responsible for:

- verifying every privileged instruction
- checking safety invariants
- validating canonicalization of values
- enforcing limits (recursion, tensor rank, VM resources)

If verification fails:

- VS emits a deterministic **Axion Fault**, which MUST halt or redirect execution.

## 2.3 Constraint Resolution Subsystem (CRS)

CRS ensures:

- tier-appropriate constraints
- purity constraints for non-effectful functions
- memory safety constraints
- shape and algebraic constraints for tensor ops
- deterministic aliasing rules

## 2.4 Recursion Control Subsystem (RCS)

Tracks and checks:

- recursion depth
- recursive call signatures
- call patterns
- dynamic termination behavior
- loop iteration bounds

RCS MAY impose a hard stop if recursion becomes unbounded or unsafe.

## 2.5 Tier Transition Subsystem (TTS)

Decides when execution should:

- remain in Tier 1 (pure logic and arithmetic)
- advance to Tier 2 (structured algorithms, branching)
- enter Tier 3 (deep recursion or symbolic reasoning)
- escalate to Tier 4+ (cognitive reasoning layers)

TTS requires metadata from:

- RCS
- VS
- CRS

______________________________________________________________________

# 3. Recursion Controls

Axion enforces deterministic recursion limits:

### 3.1 Static Bound

If T81Lang provides an annotation like:

```t81
@bounded(100)
```

Axion MUST enforce it strictly.

### 3.2 Meta-Structural Bound

Axion evaluates recursion signatures:

- argument shrinkage
- fixed-point approach
- structural decrease

If a recursion does not appear to converge, Axion MAY halt it.

### 3.3 Tier-Dependent Bound

Higher tiers allow deeper recursion but require explicit annotation.

### 3.4 Catastrophic Recursion Detection

If execution resembles:

- unbounded branching
- shape explosion
- exponential stack growth
- runaway tensor expansion

Axion MUST halt with a deterministic Axion Fault.

______________________________________________________________________

# 4. Tier Model

Axion is the **gatekeeper** of cognitive tiers.

### Tier 1 — Pure Deterministic Computation

Simple arithmetic, no recursion, no large tensors.

### Tier 2 — Structured Algorithms

Controlled loops, branching, bounded recursion.

### Tier 3 — Recursive / Symbolic Reasoning

Complex recursion, structural transformations, limited tree search.

### Tier 4+ — Cognitive Reasoning Layers

Only allowed with explicit tier annotation and Axion approval.

Axion MUST verify the program's declared tier intent matches its behavior.

______________________________________________________________________

# 5. Privileged Instructions

Axion defines normative semantics for all `AX*` instructions.

**Tier restriction:** `AXREAD` and `AXSET` are restricted to Tier 2 and above.
`AXVERIFY` is the only `AX*` instruction permitted in Tier 1. See
[`cognitive-tiers.md §1`](cognitive-tiers.md#tier-1--pure-deterministic-computation).

### 5.1 AXREAD

Used to read Axion metadata.

- Allowed only for whitelisted tags
- Returns canonical values
- Unrecognized or restricted tags MUST produce a **Security Fault**

### 5.2 AXSET

Used to request Axion to alter metadata or policy.

- Allowed only for authorized tags
- Axion MUST validate requested value
- Conflicting or unsafe changes MUST produce a **Policy Fault**

### 5.3 AXVERIFY

Used to request verification of the current execution state.

- Axion MUST validate deterministic invariants
- Returns a canonical code describing success/failure
- MUST NOT fault unless verification infrastructure itself fails deterministically

______________________________________________________________________

# 6. T81VM Integration

Axion MUST interact with T81VM as follows:

### 6.1 Pre-instruction Hook

Before T81VM executes:

- privileged instructions
- unsafe memory writes
- CALL/RET that cross tiers
- tensor operations with rank > 2
- recursion-critical steps

Axion receives the machine state and may veto.

### 6.2 Post-instruction Hook

After execution:

- Axion records deltas
- updates recursion depth
- records memory write descriptors
- updates tier analysis metadata

### 6.3 Fault Propagation

On any fault:

- VM halts normal execution
- Axion receives full fault context
- Axion decides termination or rehabilitation

______________________________________________________________________

# 7. Axion Faults

Axion faults are distinct from VM/TISC faults.

## 7.1 Types of Axion Faults

- **Determinism Fault**
  Execution deviated from deterministic rules.

- **Safety Fault**
  Unsafe memory or control-flow pattern detected.

- **Policy Fault**
  Axion policy violation (security, ethics, recursion policies).

- **Tier Fault**
  Execution attempted to enter a higher tier without annotation.

- **Canonicalization Fault**
  Value failed canonical validation.

## 7.2 Behavior on Fault

Axion MUST:

1. Halt VM execution
2. Store structured fault metadata in META
3. Emit deterministic reason code
4. Optionally capture a full VM snapshot

Faulting MUST never leave VM state ambiguous.

______________________________________________________________________

# 8. Interoperability Summary

Axion MUST interoperate with:

- **TISC**: verifying privileged instructions
- **T81VM**: supervising execution and metadata
- **T81Lang**: enforcing purity and tier semantics
- **Data Types**: canonicalization of values
- **Cognitive Tiers**: providing constraints and safety boundaries

______________________________________________________________________

# Cross-References

## Overview

- **Axion Position in Architecture** → [`t81-overview.md`](t81-overview.md#2-architectural-layers)

## Data Types

- **Canonicalization Requirements** → [`t81-data-types.md`](t81-data-types.md#5-canonicalization-rules-critical-normative-section)

## TISC

- **Privileged Instructions** → [`tisc-spec.md`](tisc-spec.md#510-axion-privileged-instructions)

## T81VM

- **Trace and Metadata Requirements** → [`t81vm-spec.md`](t81vm-spec.md#51-observation)
- **Determinism and Fault Rules** → [`t81vm-spec.md`](t81vm-spec.md#2-determinism-constraints)

## T81Lang

- **Purity, Effects, and Tier Intent** → [`t81lang-spec.md`](t81lang-spec.md#3-purity-and-effects)

## Cognitive Tiers

- **Tier Definitions and Rules** → [`cognitive-tiers.md`](cognitive-tiers.md#1-tier-structure)

______________________________________________________________________