T81 Foundation

title: T81 Foundation Specification nav:

← Back to Spec Index

T81 Data Types Specification — Version 1.2 (Normative)

Status: Stable
Last Revised: 2026-03-01
Applies To: T81Lang, TISC, T81VM, Axion, Cognitive Tiers
Supersedes: v1.1
Purpose: Define deterministic, canonical, base-81 type semantics for the T81 ecosystem.

Freeze Exception — 2026-03-01
Scope: Additive corrections only — no existing type semantics changed.
Authorized by: @t81dev
Rationale: Prior versions documented only 4–5 of the 34 implemented type kinds. §11 adds the Extended Type Inventory; §9 is updated to remove types that are already implemented. No DCP surface content was changed.

Binary Host Execution Boundary

T81 is a ternary semantic architecture executed on binary hardware. This is an intentional design choice. The platform guarantees exact ternary correctness while leveraging 2-bit packed trits and SWAR (SIMD Within A Register) vectorization to map naturally and efficiently onto binary host CPUs.

0. Scope

This document defines:

It is normative for all runtime, compilation, and cognitive layers.

1. Design Goals (Normative)

All T81 data types MUST satisfy:

  1. Deterministic Semantics

    • no nondeterministic outcomes
    • all arithmetic, comparisons, and structural operations MUST produce identical results across implementations

  2. Canonical Representation

    • each representable value MUST have exactly one canonical encoding
    • no alternative or redundant forms permitted

  3. Base-81 Numeric Foundation

    • all numeric types MUST use balanced-ternary or base-81 semantics
    • internal binary shortcuts are permitted but MUST NOT affect observable behavior

  4. Zero Undefined Behavior

    • every operation MUST define behavior for all inputs
    • errors MUST resolve to deterministic fault states or Result[T, E] representations

  5. Axion Visibility

    • all canonical forms must be introspectable by the Axion kernel
    • all normalization steps MUST emit metadata hooks

2. Primitive Numeric Types

Primitive types form the base of all T81 computation.

2.1 Trit

Definition

A trit is the fundamental balanced-ternary digit:

−1 → T̄  
 0 → T0  
+1 → T1

Representation

Canonical 2-bit balanced encoding (implementation detail, nondeterministic allowed internally).

Operations

All MUST be deterministic.

2.2 T81BigInt

Definition

An arbitrary-precision base-81 integer with the following constraints:

Canonical Form

A value MUST satisfy:

- Zero encoded as: [+] [0]
- Nonzero MUST NOT contain leading zeros
- Negative: sign bit set, magnitude canonical

Arithmetic

All operations MUST be:

Operations:

Implementation

VM MAY implement long arithmetic, Karatsuba, FFT-based, or hardware-accelerated multiplication as long as results remain identical. Implementations MAY also spill large digit arrays to deterministic backing storage (e.g., mmap’d scratch files with fixed naming and allocation rules) when operands exceed in-memory thresholds. Such spill logic, as pioneered in the legacy hvm-trit-util.cweb, MUST remain transparent to observable behavior (no timing-dependent faults, no nondeterministic resource selection).

2.3 T81Float

Definition

A floating-point format with deterministic canonical storage but host-dependent arithmetic for complex operations.

Requirements (Normative)

  1. Storage Determinism: The canonical representation (mantissa/exponent/sign) MUST be identical across platforms.
  2. Arithmetic Dependency:
    • Add, Sub, Mul: MUST be deterministic (software implementation).
    • Div, Transcendentals (sin, cos, log, etc.): MAY rely on host double precision. Strict bit-exact determinism is NOT guaranteed for these operations in the current version.
  3. No NaN, no infinities: Invalid states MUST map to a deterministic error code.
  4. Round-trip encoding: encode(decode(x)) = x MUST hold for the canonical form.

Components

Note

Floating points are never silently lossy; any precision loss MUST be made explicit via a Result[T, E].

2.4 T81Fraction

Definition

A rational number represented as:

numerator:   T81BigInt  
denominator: T81BigInt (non-zero)

Canonicalization Rules

  1. Fraction MUST always be in lowest terms.
  2. Denominator MUST always be positive (+ sign).
  3. Zero MUST be encoded as 0/1.
  4. GCD MUST be computed deterministically.

Arithmetic

Exact and deterministic:

No floating approximations allowed.

2.5 T81Prob

Definition

A native log-odds probability representation using:

Note: T81Int<N> is a C++ implementation detail in include/t81/types.hpp used to express fixed-width ternary integers at compile time. The user-facing language type for arbitrary-precision integers is T81BigInt. See §11 for the complete type inventory.

Canonicalization Rules

  1. Value is stored as log(p / (1-p)) scaled to fixed-point integer.
  2. T81Int representation MUST be canonical (no leading zeros).
  3. Special values:
    • 0 (zero) represents p=0.5 (log-odds 0).
    • kMinValue represents p=0 (minus infinity log-odds).
    • kMaxValue represents p=1 (plus infinity log-odds).

Arithmetic

Operations are performed in log-space:

All operations MUST be deterministic and overflow-checked.

3. Composite Types

3.1 Arrays

Properties

[header][length][canonical elements...]

Allowed element types

Any T81 type.

3.2 Vectors, Matrices, Tensors

Canonical rules

Numeric Classification Note

Tensor implementations may distinguish between:

This classification is a semantic/result-class boundary, not a complete description of the arithmetic path used to compute the tensor.

In particular, a HostFloat tensor MAY still be produced through deterministic software-defined math in strict or deterministic execution modes. Current tensor contracts therefore treat:

as related but separate concerns.

Operations

3.3 Vector / Sequence Types

A Vector is a rank-1 Tensor. The canonical serialization of a Vector is identical to that of a rank-1 Tensor.

All MUST produce deterministic and canonical results.

3.3 Graphs

Structure

A deterministic graph consists of:

nodes: array of canonical nodes  
edges: array of (nodeA, nodeB, metadata)

Requirements

4. Structural Types

4.1 Records (Structs)

Requirements

4.2 Enums

Requirements

4.3 Optional and Result Types

Option[T]

Result[T, E]

5. Canonicalization Rules (Critical Normative Section)

This is the most important part of the entire spec.

Canonicalization MUST occur after:

5.1 Invariants for All Types

  1. No redundant forms

    • fractions reduce
    • integers strip leading zeros
    • floats normalize mantissa/exponent

  2. Deterministic ordering

    • arrays, structs, enums all follow strict order rules

  3. Deterministic hashing

    • MUST depend only on canonical form

  4. Axion visibility

    • Axion MUST be able to inspect normalized representation

Conformance programs: spec/conformance/t81-data-types/canonical-encoding.t81 · canonical-ordering.t81

6. Interoperability Rules

6.1 With TISC (Instruction Set)

6.2 With T81VM

6.3 With T81Lang

6.4 With Axion

6.5 With Cognitive Tiers

Higher tiers depend on deterministic and canonical types for:

7. Error Model (Normative)

All errors MUST be represented via:

Result[T, E]

Errors include:

No exceptions or traps allowed.

8. Serialization

All serialized forms MUST:

Binary and textual variants allowed; semantics identical.

9. Future Extensions (Non-Normative)

The following types are candidates for future normative specification. Types that were previously listed here but are now implemented are documented in §11.

Future type extensions MAY include:

All MUST follow determinism and canonicalization invariants.

10. Status

This document is v1.2 of the T81 Data Types Standard (freeze exception applied 2026-03-01). The §2 primitive types and §3–§8 normative rules are the frozen DCP surface. §11 (Extended Type Inventory) is additive and non-DCP unless the types listed there have individually been promoted to Verified status in the Implementation Matrix (docs/status/IMPLEMENTATION_MATRIX.md).

11. Extended Type Inventory (Freeze Exception — Additive)

This section was added in the 2026-03-01 freeze exception. It documents the full set of type kinds currently implemented in the T81 semantic analyzer (lang/frontend/semantic_analyzer.cpp). The four tiers mirror the structure in spec/t81lang-spec.md §2.

Conformance program: spec/conformance/t81-data-types/type-kind-completeness.t81

11.1 Ternary Core (Tier 1 — Fully Deterministic)

These types are DCP-verified. Their semantics are normatively defined in §2.

Type Kind Description
T81BigInt BigInt Arbitrary-precision base-81 integer. User-facing language type. See §2.2.
T81Float Float Base-81 floating-point. See §2.3.
T81Fraction Fraction Exact rational p/q. See §2.4.
Symbol Symbol Interned immutable identifier. Created with :name literal syntax in T81Lang. Stored in the VM’s symbol pool; canonical text comparison.

Symbol literal syntax: In T81Lang, Symbol values are created using the colon-prefix literal: :my_symbol. This produces a value of type Symbol that is interned in the VM symbol pool for the lifetime of the program.

11.2 Text and Binary (Tier 1)

Type Kind Description
T81String String UTF-8 text. Immutable, canonical. Compared by code-point sequence.
T81Bytes Bytes Raw byte array. Immutable, canonical. No encoding assumed.

11.3 Extended Numeric (Tier 2 — DCP-Target)

These types are implemented but not yet DCP-promoted. They follow the determinism and canonicalization rules of §1 and §5.

Type Kind Description
T81Fixed Fixed Fixed-point decimal with explicit scale.
T81Complex Complex Complex number with T81Float real and imaginary parts.
T81Quaternion Quaternion Quaternion (a + bi + cj + dk) over T81Float.
T81Prob Prob Log-odds probability. See §2.5.
T81Qutrit Qutrit Single balanced ternary digit {-1, 0, +1}.
T81Uint Uint Unsigned base-81 integer (non-negative, no sign trit).

11.4 Binary Interop (Tier 1 — Interop Surface)

Fixed-width binary types for FFI and host-interop. These do NOT have balanced-ternary semantics; overflow semantics follow standard two’s-complement binary rules and MUST be explicitly annotated when used in T81Lang.

Type Kind Description
i32 I32 Signed 32-bit integer.
i16 I16 Signed 16-bit integer.
i8 I8 Signed 8-bit integer.
i2 I2 Signed 2-bit integer (values: -1, 0, +1; maps to a single trit).
bool Bool Boolean. Canonical values: true, false.

11.5 Collection Types (Tier 2)

Generic collection types with deterministic ordering and canonical iteration.

Type Kind Description
Vector[T] Vector Resizable ordered sequence.
T81Vector[T, N] T81Vector Fixed-size rank-1 tensor with base-81 dimension N.
Matrix[T] Matrix Rank-2 tensor (rows × cols). Shape immutable after construction.
Tensor[T] Tensor Rank-N tensor. Tier constraint: rank ≤ 9 (Tier 5 max).
List[T] List Singly-linked or array-backed deterministic list.
Map[K, V] Map Sorted key-value mapping. Key ordering MUST be canonical.
Set[T] Set Sorted set. Membership test MUST be canonical.
Tree[T] Tree Rooted tree with canonical child ordering.
Graph Graph Directed graph. See §3.3 for structure rules.

Generic type syntax uses square brackets: Vector[T81BigInt], Map[Symbol, i32].

11.6 Structural Types (Tier 1)

Type Kind Description
Option[T] Option Some(value) or None. No nulls. See §4.3.
Result[T, E] Result Ok(value) or Err(error). No exceptions. See §4.3.

11.7 Meta Type

Type Kind Description
void Void Unit return type. Functions returning no value use void.

11.8 Numeric Widening Order

When types are mixed in arithmetic, the VM applies implicit widening in this rank order (lowest to highest):

T81Qutrit < i2 < i8 < i16 < i32 < T81Uint < T81BigInt
    < T81Fraction < T81Fixed < T81Float

Widening is always explicit at the TISC level (conversion opcodes I2F, I2FRAC, etc.). T81Lang performs widening implicitly within the same rank group but requires explicit casts across group boundaries.

Conformance programs: spec/conformance/t81-data-types/widening-order.t81 · widening-upper-chain.t81 · widening-binary-interop.t81

Cross-References

Data Types

TISC (Ternary Instruction Set)

T81 Virtual Machine

T81Lang

Current spec version: v1.2 (updated 2026-03-01).

Axion Kernel

Cognitive Tiers

This site is open source. Improve this page.