mirror of
https://github.com/allaunthefox/Research-Stack.git
synced 2026-08-11 01:50:34 +00:00
153 lines
4.2 KiB
Markdown
153 lines
4.2 KiB
Markdown
# Canonical Specification for the Adaptive Virtual Machine (AVM)
|
|
## State: CALIBRATED_PENDING_VALIDATION
|
|
|
|
This document is the canonical design for **AVM as a Lean-defined core ISA**.
|
|
|
|
**Core rule:**
|
|
|
|
> **Lean is the source of truth. AVM is a Lean-only ISA.**
|
|
|
|
All non-Lean languages (Python, Rust, C/C++, Go, etc.) are **adapter shims** (a.k.a.
|
|
backends) that *strip / serialize / reinterpret* into AVM programs and execute
|
|
AVM semantics. They do not define new semantics.
|
|
|
|
---
|
|
|
|
## 0. Definitions
|
|
|
|
### 0.1 AVM Core
|
|
The **AVM core** is the ISA + operational semantics defined in Lean.
|
|
|
|
- Finite opcode set (closed-world)
|
|
- Finite value type set (closed-world)
|
|
- Deterministic step/run semantics
|
|
- No open string matching in decisions
|
|
- No dynamic "Any" values in the ISA
|
|
|
|
### 0.2 Adapter shims (backends)
|
|
Adapter shims are **extraction/interop targets**, not sources of truth.
|
|
|
|
They may:
|
|
- Encode/decode AVM programs and values (serialization)
|
|
- Interpret AVM programs (runtime interpreter)
|
|
- Emit target artifacts (Python bytecode, C, Rust, Verilog, FPGA netlists)
|
|
|
|
They may **not**:
|
|
- Introduce new ISA meaning
|
|
- Add ad-hoc branching policy
|
|
- Decide invariants or costs outside Lean
|
|
|
|
---
|
|
|
|
## 1. AVM Instruction Set Architecture (ISA) — Lean-only
|
|
|
|
The AVM ISA is a **Lean inductive** instruction set.
|
|
|
|
### 1.1 Closed-world opcodes
|
|
The opcode set MUST be finite and enumerable.
|
|
|
|
A minimal core (illustrative, not final):
|
|
|
|
- Stack ops: `push`, `pop`, `dup`, `swap`
|
|
- Locals: `load`, `store` (indexed by `Fin n`)
|
|
- Control flow: `jump`, `jumpIf`, `halt`
|
|
- Fixed-point arithmetic primitives: `addSat`, `subSat`, `mul`, etc.
|
|
|
|
### 1.2 Strict typing
|
|
The ISA operates over a finite type universe:
|
|
|
|
- `Q0_16` (default for dimensionless scalars)
|
|
- `Q16_16` (only when range/precision forces it)
|
|
- `Bool`
|
|
- (Optional later) `UInt8`, `UInt16`, `UInt32`, fixed-width words for IO/register surfaces
|
|
|
|
**No Float in core.** Float may exist only at boundary conversion shims.
|
|
|
|
### 1.3 No dynamic foreign calls in ISA
|
|
The ISA must not contain opcodes like `CALL("pythonMethod")` or `IMPORT("module")`.
|
|
|
|
If extensibility is needed, it must be via **finite enums** (e.g. `Prim : Type`)
|
|
with semantics defined in Lean:
|
|
|
|
- `Prim` is finite
|
|
- `evalPrim : Prim -> ...` is defined in Lean
|
|
- backends implement `Prim` by matching the Lean semantics
|
|
|
|
---
|
|
|
|
## 2. Execution model
|
|
|
|
### 2.1 Step semantics
|
|
AVM execution is defined by a Lean function:
|
|
|
|
- `step : Program -> State -> Outcome State`
|
|
|
|
### 2.2 Run semantics (fuel)
|
|
AVM execution must have a fuel-bounded run function:
|
|
|
|
- `run : Fuel -> Program -> State -> Outcome State`
|
|
|
|
This is required for totality and for extraction to bounded substrates.
|
|
|
|
### 2.3 Determinism invariant
|
|
The state transition must be deterministic:
|
|
|
|
For any two backend environments implementing the same AVM ISA,
|
|
|
|
- `run_backend1(program, state) == run_backend2(program, state)`
|
|
|
|
up to the same observable projection.
|
|
|
|
---
|
|
|
|
## 3. Serialization boundary (shim responsibility)
|
|
|
|
Adapters may represent AVM programs and values in JSON or binary form.
|
|
|
|
Rules:
|
|
- Serialization formats must be versioned.
|
|
- No semantic meaning may depend on string parsing.
|
|
- Decoders must reject unknown opcodes/types.
|
|
|
|
---
|
|
|
|
## 4. Receipt / provenance policy
|
|
|
|
Every adapter execution must be able to emit a receipt packet containing:
|
|
|
|
- AVM ISA version
|
|
- adapter version
|
|
- input program hash
|
|
- output state hash
|
|
- (optional) projection hash
|
|
|
|
This makes drift observable and auditable.
|
|
|
|
---
|
|
|
|
## 5. Relationship to prior "universal adapter" language
|
|
|
|
Earlier drafts described AVM as a universal adapter from many math languages.
|
|
|
|
**This spec supersedes that framing.** The correct architecture is:
|
|
|
|
- **Lean -> AVM ISA (Lean-defined) -> adapter shims/backends**
|
|
|
|
If other languages are supported as inputs, they must be compiled into AVM by a
|
|
shim that produces AVM programs; but the AVM ISA itself remains Lean-only.
|
|
|
|
---
|
|
|
|
## 6. Claim boundary
|
|
|
|
This document defines AVM as a Lean-only ISA and a backend adapter ecosystem.
|
|
|
|
It does not claim:
|
|
- that every backend already exists
|
|
- that all proofs are complete
|
|
- that the ISA opcodes are final
|
|
|
|
It does claim:
|
|
- strict typing + closed-world opcodes is mandatory
|
|
- all semantics live in Lean
|
|
- all non-Lean code is an adapter shim, not a semantic authority
|