Rust-native compiler platform for legacy languages.
Multi-frontend by design. Direct machine-code and executable-format output. Built for standalone release binaries.

Implementation Plan · Release Plan · Tag Stops · Modularity · Security Controls · Threat Model · Supply Chain · Licensing · Security

elderheim

elderheim is a universal compiler platform for legacy languages. The first supported language family is Dartmouth BASIC, specifically the locally planned manual-backed profiles for Dartmouth BASIC versions 1, 2, and 4.

The intended release model is one downloadable elderheim compiler binary per supported operating system and architecture. A user downloads elderheim, chooses the source dialect explicitly, and compiles old source files without installing Rust, rustc, Cargo, a C compiler, or a platform linker for the supported release path.

The final supported release path is meant to be self-contained:

• A user downloads one elderheim binary for their OS and architecture.
• A user runs elderheim --dartmouth-basic-1 program.bas -o program.
• No Rust install is required.
• No rustc is required.
• No Cargo is required.
• No C compiler is required.
• No external assembler is required.
• No external linker is required for the supported release path.
• No Cranelift or LLVM backend is used.
• Old source code compiles through elderheim itself.

Temporary C, Cranelift, LLVM, system assembler, system linker, or external runtime bridges are not part of the implementation strategy.

The first stable goal is 1.0.0: prove the compiler platform with complete manual-backed Dartmouth BASIC 1, then complete manual-backed Dartmouth BASIC 2, then complete manual-backed Dartmouth BASIC 4. Dartmouth BASIC 3 stays reserved until official documentation is available. Other BASIC variants and non-BASIC language families are future frontends under crates/languages/, not implementation claims in the foundation release.

Committed scope must not be half implemented. If a committed feature, profile, target, report, or security control cannot be finished in its current stop, the release plan must receive an explicit follow-up version such as 0.1.1, 0.2.1, or the next minor stop before the current release is treated as done. This rule does not turn out-of-scope work into a deferral: Dartmouth BASIC 4 means the documented source programming language, not Dartmouth timesharing session, editor, account, file, paper-tape, or operating-system commands.

elderheim source code is licensed under EUPL-1.2.

Licensing and Output Ownership

The EUPL-1.2 license applies to Elderheim itself: its source code, documentation, scripts, tests, and other project files unless a file states a different license.

Source programs compiled with Elderheim, and executable or object artifacts produced from those source programs, remain owned and licensed by their original authors, companies, or rights holders. Using Elderheim to compile a program does not by itself apply EUPL-1.2 to that source program or to the generated output.

If a generated artifact includes Elderheim-provided runtime, startup, or support code, that included Elderheim component remains covered by the project license or by any explicit runtime/output exception published for that component. The project will keep this boundary documented before generated executables include Elderheim runtime material.

See Licensing for the full project policy.

Historical Documentation

Elderheim depends on primary historical manuals to keep dialect support accurate. We are looking for help finding original manuals, scans, specifications, and era-appropriate reference texts for older programming languages.

The current priority search is:

• Dartmouth BASIC Third Edition / Version 3.
• Dartmouth BASIC Versions 5 through 7.
• SBASIC / Source BASIC / Structured BASIC variants.

The first local reference set is:

• Dartmouth BASIC First Edition, May 1964.
• Dartmouth BASIC Second Edition, October 1964.
• Dartmouth BASIC Fourth Edition, January 1968 text export.

If you have leads, public archive links, scans, or other historical language references that may fit Elderheim, please reply here: Seeking historical programming documents for Elderheim.

What Works Today

0.13.0 is the current Dartmouth BASIC 1 minimal parser release. It parses the first complete program shape: blank and quoted-label PRINT statements followed by exactly one final END, with typed, span-bearing parse failures.

The next stop is 0.13.1: require normalized-source capabilities at every public frontend boundary, convert frontend locations to absolute normalized source spans, and prove exact two-way corpus-manifest parity. Subsequent 0.13.x stops settle CST/semantic-HIR ownership, mandatory pipeline capabilities, unified budgets, sealed editions, and historical numeric semantics plus two-way manual provenance before numeric parser growth resumes in 0.14.0.

No Dartmouth BASIC full parser, semantic validator, or executable writer is implemented yet. The roadmap intentionally starts with compiler substrate, then makes BASIC 1 complete, then BASIC 2 complete, then BASIC 4 complete.

Compiler Foundation

Capability	Status	Notes
Cargo workspace	Working	Shared compiler crates live directly under crates/; language frontends live under crates/languages/.
Rust toolchain pin	Working	Stable Rust 1.97.0, edition 2024, workspace resolver 3.
License	Working	EUPL-1.2.
no_std library skeletons	Working	Core/facade crates are prepared for no_std production logic.
Source and diagnostics core	Working	elderheim-core validates source byte and line limits, maps byte offsets to one-based line/column locations, checks spans, exposes a stable diagnostic code registry, and renders compact and snippet diagnostics.
Source normalization core	Working	elderheim-core normalizes LF/CRLF/CR into LF, rejects invalid control/non-ASCII bytes under the current policy, enforces blank-line policy, and returns stable normalized source IDs.
Compiler pipeline skeleton	Working	elderheim-core exposes ordered source-to-diagnostic, HIR-to-MIR, MIR-to-LIR, and LIR-to-target stages with fail-fast diagnostics and report sink events.
Reporting core	Working	elderheim-core exposes stable report sections and report events for section headers, pipeline stages, and diagnostics.
IR contracts	Working	elderheim-ir exposes HIR node IDs, MIR value/label IDs, LIR label/symbol IDs, bounded O(n log n) validators, and lowering sink traits.
Runtime fragment selection	Working	elderheim-runtime maps high-level runtime requirements to fragment dependencies without executable emission.
Manual corpus	Working	docs/languages/dartmouth-basic-1.md and examples/dartmouth-basic-1/ define the first controlled BASIC 1 corpus.
BASIC 1 line table	Working	The Dartmouth BASIC crate parses increasing numbered source lines, rejects malformed line numbers, duplicate line numbers, out-of-order lines, missing statement separators, and empty numbered lines.
BASIC 1 lexer	Working	The Dartmouth BASIC crate lexes BASIC 1 statement text into token kinds with spans and rejects invalid identifiers, invalid numbers, unterminated strings, and unknown characters.
BASIC 1 HIR shape	Working	The Dartmouth BASIC crate builds a source-shaped BASIC 1 HIR with program, line, statement, and token-sequence expression nodes plus stable debug snapshots.
BASIC 1 minimal parser	Working	Parses blank and comma-separated quoted-label PRINT forms, requires a final operand-free END, and rejects malformed or later-stop syntax with typed errors.
Target matrix identifiers	Working	Linux x86/x86_64/aarch32/aarch64, Windows x86_64, and macOS Apple Silicon aarch64 are represented with CLI-visible names and stable rejection diagnostics.
Dartmouth BASIC crate	Scaffolded	Active first language-family crate: crates/languages/elderheim-dartmouth-basic.
Direct backend plan	Planned	Native output is planned through Elderheim-owned instruction encoders and executable writers, not Cranelift, LLVM, C, or Rust transpilation.
ELF writer	Scaffolded	elderheim-format-elf separates checked file-offset and virtual-address ranges for future ELF32/ELF64 work.
x86 backend	Scaffolded	elderheim-backend-x86 is present for future x86 32-bit and x86_64 work.
Release/security gates	Working	Formatting, doc links, modularity, clippy, tests, cargo-deny, cargo-audit, and duplicate-safe SPDX SBOM generation pass locally.
Pentest/tag stops	Planned	Every planned tag has a stop gate and pentest class in the release plan.

Language Support

Compatibility is tracked per concrete language or dialect, not by loose family names. A dialect is marked complete only after manual-backed fixtures, target fixtures, release gates, and pentest evidence pass.

Language or dialect	Status	Comment
Dartmouth BASIC First Edition (dartmouth-basic-1)	Planned for first implementation line	BASIC 1 must reach complete manual-backed language support before BASIC 2 begins.
Dartmouth BASIC Second Edition (dartmouth-basic-2)	Planned after BASIC 1	Added as an explicit compatibility expansion over proven BASIC 1 behavior.
Dartmouth BASIC Third Edition (dartmouth-basic-3)	Reserved	No official documentation is available locally; not part of 1.0.0.
Dartmouth BASIC Fourth Edition (dartmouth-basic-4)	Planned after BASIC 2	Added only after BASIC 2 reaches its compatibility stop.
Other Dartmouth BASIC editions	Reserved	Need primary manuals before scheduling.
Other BASIC variants	Future	Planned only after source material and release scope are ready.
Non-BASIC languages	Future	The platform is designed for future language-family crates, but none are active in the foundation.

Why elderheim

• Standalone compiler goal: released binaries should compile supported source files without requiring users to install Rust, Cargo, a C compiler, an external assembler, or an external linker for the supported release path.
• Rust first: memory-safe implementation with a pinned modern Rust toolchain.
• Direct native output: Elderheim owns the machine-code backend and executable-format writer instead of shelling out to Cranelift, LLVM, C, Rust, assemblers, or linkers.
• Language-family frontend crates: each language family gets its own crate under crates/languages/ when source material and release scope justify it.
• Security first: unsupported constructs fail explicitly, dependencies are audited, releases require SBOM evidence, and every tag has a pentest class.

Quick Start

Run the full local gate:

scripts/checks.sh

Run the release-candidate gate before asking the maintainer to push and wait for GitHub Actions / CodeQL:

scripts/validate-release-candidate.sh v0.13.0

Run the dependency and advisory gates:

cargo deny check
cargo audit

Generate an SBOM:

scripts/generate-sbom.sh

Run the current CLI scaffold:

cargo run -p elderheim --bin elderheim

List supported 1.0 target names:

cargo run -p elderheim --bin elderheim -- --list-targets

Validate a target name:

cargo run -p elderheim --bin elderheim -- --target linux-x86_64-elf64

Workspace

elderheim/
├── crates/
│   ├── elderheim/                  # no_std facade library and CLI shell
│   ├── elderheim-core/             # source, spans, diagnostics, pipeline, limits
│   ├── elderheim-ir/               # HIR/MIR/LIR and pipeline boundary contracts
│   ├── elderheim-runtime/          # runtime fragment inventory and selection
│   ├── elderheim-target/           # target and format identifiers
│   ├── elderheim-backend-x86/      # x86 32-bit and x86_64 backend contracts
│   ├── elderheim-format-elf/       # ELF32/ELF64 writer contracts
│   └── languages/
│       └── elderheim-dartmouth-basic/
├── docs/
├── examples/
├── release-notes/
├── scripts/
├── security/
└── tools/

Documentation

Document	Purpose
Implementation Plan	Compiler architecture, workspace shape, Dartmouth sequencing, and output strategy.
Release Plan	Granular roadmap from 0.1.0 through 1.0.0.
Release Procedure	Commit, tag, pentest-input, and CodeQL reporting policy.
Tag Stops	Stop gate and pentest class for every planned tag.
Target Matrix	Supported 1.0 target names and rejection diagnostics.
Source Diagnostics	Source byte, span, limit, and diagnostic rendering contract.
Source Normalization	Line ending, byte policy, blank-line, and source ID contract.
Diagnostics Reporting	Diagnostic registry, snippet rendering, and report section/event contract.
IR Contracts	HIR/MIR/LIR IDs, validators, and lowering interface contract.
ELF Layout	File-offset, virtual-address, overflow, and entry-point validation contract.
Runtime Fragments	Runtime requirement, fragment inventory, and dependency selection contract.
Licensing	Project license scope, generated-output ownership, and runtime boundary policy.
Manual Corpus	Local manual provenance and committed corpus policy.
Dartmouth BASIC 1	Elderheim-authored BASIC 1 corpus reference.
Pipeline Contract	Compiler stage ordering, error propagation, and report sink contract.
Modularity Policy	Crate split rules and 500-line source-file policy.
Unsafe Policy	Unsafe admission rules and serialization safety policy.
Toolchain Policy	Rust version pin and tooling expectations.
Security Controls	Required compiler, release, and CodeQL controls.
Threat Model	Assets, trust boundaries, and residual risks.
Supply-Chain Security	Dependency and tooling review policy.
Security Policy	Security checks and reporting guidance.

Release Direction

The project does not aim to make one giant parser that guesses every old language. Users should choose the dialect explicitly:

elderheim --dartmouth-basic-1 program.bas -o program
elderheim --dartmouth-basic-2 program.bas -o program
elderheim --dartmouth-basic-4 program.bas -o program

Future language families should live in their own local workspace crates under crates/languages/. Shared compiler infrastructure stays in the core crates, while source-language rules remain isolated inside each language-family frontend.