diff options
Diffstat (limited to 'SWORD.md')
| -rw-r--r-- | SWORD.md | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/SWORD.md b/SWORD.md new file mode 100644 index 0000000..e08ceaa --- /dev/null +++ b/SWORD.md @@ -0,0 +1,24 @@ +# 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`). |