This repository describes the RustScript (.rss) language, execution artifact formats, debugging contract, and host interop model.
The specification is implementation-derived, but the public text is intentionally high level: it describes observable language/runtime contracts rather than source layout or implementation details.
RustScript has no null literal and no T? optional type. Absence and failure are explicit values:
let unit: () = (); // Unit
let present: Option<int> = Some(0); // present
let absent: Option<int> = None; // absent
let ok: Result<int, string> = Result::Ok(1);
let err: Result<int, string> = Result::Err("bad input");()is Unit. Its physical carrier is the VM's internal Null value, but Unit is a logical type and is not a nullable value.Option<T>wraps at most one value, selected by the carrier's Booleantag.Some(0),Some(false),Some(""), andSome(())are present values; payload truthiness never selectsNone.Result<T, E>is a built-in typed success-or-guest-error value. Both parameters are required.?is expression-level propagation:OptionpassesSomethrough and exits the enclosingOption-returning function or closure onNone;ResultpassesOkthrough and returns the exactErrfrom the enclosingResult-returning function. Error types must match; usemap_error.ok_or(...)at the boundary.?.is fallible projection and yields anOption.- A host returns a guest option as
GuestOption<T>and a guest result asGuestResult<T, E>, with the outerVmResultreserved for fatal transport failures. See Host functions.
The language contract is checked by a dependency-free Node test that validates the grammar JSON, the keyword list, the documentation claims, and the fixture below:
node --test tests/option-result-contract.test.mjsThe fixture tests/fixtures/option-result.rss is executed by the same test when RUSTSCRIPT_CORE_BIN points at a built pd-vm-run:
RUSTSCRIPT_CORE_BIN=/path/to/pd-vm-run node --test tests/option-result-contract.test.mjsWithout RUSTSCRIPT_CORE_BIN the fixture-execution test fails with an explicit error; it is never skipped silently, because a skipped execution check would report success without running anything. To run only the static checks while a binary is unavailable:
node --test --test-skip-pattern='executes the fixture' tests/option-result-contract.test.mjs--test-skip-pattern is the flag that actually filters under current Node releases; --test-name-pattern does not exclude the fixture-execution test, so this document, the test header, and CI all use the skip pattern.
This draft covers:
- RustScript syntax and grammar shape.
- VM bytecode as a portable execution artifact.
- AOT packages as a distribution artifact.
- Debugger-facing source, frame, stack, and breakpoint conventions.
- Host function registration and call contracts.
It does not standardize optimizer strategy, internal compiler organization, private runtime data structures, or non-RustScript frontend compatibility.
Where this text and an implementation disagree, the implementation is the compatibility reference until this specification is updated.