# Sword Runtime Notes

## What Sword Aims to Deliver
- Replace Vere with a modern runtime that pairs static Nock code generation and the 2stackz allocator for near-native performance (`sword/docs/storyboard.md:8-44`).
- Lift persistence limits via a 64-bit, copy-on-write arena that keeps noun addresses stable across snapshots and supports terabyte-scale state (`sword/docs/storyboard.md:16-55`, `sword/docs/persistence.md:4-37`).
- Maintain compatibility with existing ships by mirroring Vere semantics while refining memory layout, noun tagging, and stack polarity rules (`sword/docs/stack.md:5-83`).

## Concrete References
- Interpreter: opcode state machines, tail-position rules, subject restores, and jet integration (`sword/rust/sword/src/interpreter.rs:1-168`).
- Jets: virtualization entry points (`+mink`, `+mure`, etc.), scry handling, and hot/warm/cold match strategy (`sword/rust/sword/src/jets/nock.rs:1-192`).
- Memory: dual-stack allocator invariants, orientation flags, and OOM diagnostics for 2stackz (`sword/rust/sword/src/mem.rs:17-147`).
- Build/Test Flow: pills for bootstrapping, single-threaded `cargo test`, and tooling assumptions when running ships (`sword/DEVELOPERS.md:7-37`).

## Gaps & Open Work
- Codegen remains R&D: subject-knowledge propagation, bytecode generation, and virtualization plumbing are still under active development (`sword/docs/storyboard.md:30-84`).
- Persistent arena integration (B-tree directory, GC, free-lists) is unfinished; impact on allocator wiring is tracked but unresolved (`sword/docs/storyboard.md:48-105`).
- Production parity tasks—jet coverage, LMDB event log, Urth frontend—are pending, so Sword is not ready as a turnkey runtime (`sword/docs/storyboard.md:58-97`).
- Recent updates highlight ongoing work on PMA plumbing, faster jets, and codegen bootstrapping, confirming that several subsystems are still in flux (`sword/rust/sword/updates/9-20-2023.md:1-24`).

## Guidance for the OCaml Port
- Use Sword’s noun tagging and stack documentation as ground truth when aligning OCaml representations and allocator behaviour (`sword/docs/stack.md:5-83`).
- Mirror the Rust interpreter’s control flow for tricky opcodes or virtualization semantics to stay consistent with Vere and Sword expectations (`sword/rust/sword/src/interpreter.rs:1-168`).
- Keep OCaml snapshotting close to Vere for now; adopt Sword’s persistent arena ideas only once the design stabilizes (`sword/docs/persistence.md:4-37`).
- Track Sword’s SKA/codegen progress so we can plan future OCaml integration without duplicating unfinished analysis work (`sword/docs/subject-knowledge.md:38-112`).