docs/ARCHITECTURE.md

Binary Substrate Harness — Complete Architecture Specification

Executive Summary

The Binary Substrate Harness (BSH) is a static, zero-dependency, ahead-of-time compiled computational environment for transformer inference. It eliminates dynamic memory allocation, garbage collection, and runtime introspection. The architecture operates exclusively on pre-allocated, contiguous virtual memory pages. All tensor geometries and execution graphs are resolved during the reduction phase, leaving a purely deterministic, flattened instruction pipeline.

---

1. Recursive Dependency Graph & Decomposition

The framework abstraction collapses through the following rigid reduction hierarchy:

1. NEURAL NETWORK (layers + learned parameters)
   ↓ (unwrap into sequential affine transforms)
2. MODEL (static DAG of tensor operations)
   ↓ (express as topologically sorted operations)
3. GRAPH (memory-mapped buffer order)
   ↓ (flatten each tensor to 1D contiguous space)
4. TENSOR (multi-dimensional array)
   ↓ (unfold as loop nest over strides)
5. OPERATOR (loops with memory access patterns)
   ↓ (block into register-sized tiles)
6. MATRIX/VECTOR (SIMD register tiles)
   ↓ (IEEE 754 bit pattern)
7. SCALAR (32-bit or 16-bit float)
   ↓ (ALU bitwise logic)
8. INTEGER/BIT (machine operations)
   ↓ (hardware instruction)
9. INSTRUCTION (x86_64/ARM64/SASS opcode)
   ↓ (state of CPU registers + condition codes)
10. MACHINE STATE (architectural state)

Key Property: At each level, all abstractions are fully reduced. The system cannot be simplified further without breaking the I/O state model.

---

2. Neural-Operation Lowering Rules

2.1 Softmax Recursion

Mathematical Definition:

softmax(x_i) = e^(x_i) / Σ_j e^(x_j)

Hardware Lowering:

1. Base conversion: e^x = 2^(x·log₂(e))
2. Range reduction: 2^(I+F) = 2^I × 2^F
3. 2^I implemented as integer addition to IEEE 754 exponent bias
4. 2^F implemented via 3rd-degree minimax polynomial + FMA instructions

Critical: No libm calls, no transcendental lookups. Pure minimax polynomial evaluation = deterministic latency.

2.2 Scaled Dot-Product Attention

Attention(Q, K, V) = softmax(QK^T / √d_k) V

Lowering:

• Collapse to GEMM (General Matrix Multiplication)
• GEMM → Macro-kernel (L2 blocking) → Micro-kernel (L1 blocking) → Inner loop
• Inner loop: Unrolled independent outer products via SIMD
• No matrix abstraction at runtime; only register streams

---

3. Deterministic State Model

State Transition:

S_{t+1} = Φ(S_t, I_t)

Where:

• S: Memory state (buffer contents)
• I: Verified input payload (with provenance header)
• Φ: Static neural transformation

Invariant: Identical (S_0, I_{0...n}) → identical output (bit-for-bit) on compatible microarchitectures.

---

4. SYSCALL ABI & Assembly Boundary

Register Layout (x86_64 System V):

%rax: Syscall number (also return value)
%rdi: Arg 1 (e.g., fd)
%rsi: Arg 2 (e.g., buffer pointer)
%rdx: Arg 3 (e.g., count/size)
%r10: Arg 4 (replaces %rcx)
%r8:  Arg 5
%r9:  Arg 6

Permitted Syscalls:

1. sys_read (0x00): Ingest input payloads
2. sys_write (0x01): Emit inference results
3. sys_mmap (0x09): Allocate memory regions
4. sys_exit (0x3C): Terminate execution

---

5. Primitive Operation Inventory

18 x86_64 Mnemonics:

Control Flow:

• jmp, je, jne, syscall

Memory Movement:

• mov, vmovaps, vmovups, vbroadcastss

Scalar/Integer:

• add, sub, imul, shl, shr, and, or

Vector/SIMD:

• vaddps, vsubps, vmulps, vfmadd231ps, vmaxps

---

6. Memory Layout

0x0000000000400000 │ ELF Header + .text (14.2 KB)
                   │ _start, sys_mmap bootstrap
                   │ gemm_micro_kernel, softmax_fma_loop
                   ├─────────────────────────────────
0x0000000000500000 │ .rodata (Read-Only)
                   │ Minimax Polynomial Coefficients
                   │ Static Model Weights
                   ├─────────────────────────────────
0x0000000000600000 │ .bss (Read-Write, Uninitialized)
                   │ Ingestion Buffer (4 KB)
                   ├─────────────────────────────────
0x0000000000601000 │ Execution Arena (960 KB)
                   │ K/V Cache, Temp buffers
                   ├─────────────────────────────────
0x00000000006F0000 │ Output Buffer (4 KB)
                   └─────────────────────────────────

---

7. Fixed-Point Analysis

99% Template Saturation: System reached irreducible substrate.

Abstractions removed:

• Python GIL
• PyTorch Autograd engine
• CUDA runtime initialization
• Dynamic shape inference
• cuBLAS heuristic dispatcher
• Threading pools
• Garbage collector

Remaining dependencies: Bare-metal kernel ABI only.

---

8. Reproducible Build Procedure

# 1. Offline tensor compiler (PyTorch → C/Assembly DAG)
python3 lower_model.py model.pt --output harness_dag.s

# 2. Assemble
as -mcpu=native harness_dag.s -o harness.o

# 3. Link (no libc, no dynamic linking)
ld -nostdlib -static harness.o -o BSH_Twin_v1.bin

# 4. Verify determinism
sha256sum BSH_Twin_v1.bin
# Compare against declared manifest

---

Last Updated: 2026-09-27
Version: 1.0
Status: Specification Complete