GFA BASIC Rust Documentation

README

Architecture

Architecture documents

Topic Scope Document Tracking
Implementation dashboard Static maintainer dashboard, source-of-truth boundaries, progress states, evidence metrics, generation and freshness IMPLEMENTATION-DASHBOARD.md; ADR 0014 #304–#310
Repository consistency validation Deterministic Python/JSON checks for drift between repository sources VALIDATION.md; ADR 0013 architecture #248, validator #249, website generator #250
Website previews Per-PR preview URLs and automatic cleanup after PR closure WEBSITE_PREVIEWS.md
AI agent security Agent execution surfaces, untrusted content, capability tiers, workflow permissions, secrets, audit, and incident response AI-AGENT-SECURITY.md #580
AI agent evaluation Retrospective rubric, sample selection, CI/rework evidence, follow-up findings, and process improvements AI-AGENT-EVALUATION.md #578
Multi-version Amiga GFA-BASIC conformance 3.52 primary baseline with 3.5/3.5U and 3.0 comparison results ADR 0017; probe-writing guide #557

Project architecture and compatibility

Topic Scope Document Tracking
Project goals and compatibility Purpose, non-goals, compatibility dimensions GOALS.md #2
Dialects and versions Source dialect identity and version-specific rules DIALECTS.md; Amiga 3.5 lexer evidence inventory; ADR 0009; superseded ADR 0008; Amiga GFA BASIC 3.0 historical research; Atari ST GFA BASIC V2.xx/V3.0 research draft #3
Product scope Sole dialect, API profile, Linux x86-64 target, and SDL3 boundary ADR 0011 #3, #4
Target model Host/target distinction and target capabilities TARGETS.md; ADR 0003 #4
API profiles Amiga GFA BASIC 3.5 API compatibility only; Atari ST research is archival and unsupported API-PROFILES.md; ADR 0004; Amiga API research draft; Atari ST API research draft #5, #24, #25
Language tooling and editor integration LANGUAGE-TOOLING.md; ADR 0012 Shared compiler frontend, LSP server, editor client boundaries, and refactoring safety #209, #210, #211
Compiler pipeline and IR Frontend stages, semantic analysis, typed IR, LLVM boundary PIPELINE-AND-IR.md; ADR 0007 #6
Source formatting Lossless, evidence-gated formatter library and canonical style for the implemented subset FORMATTER.md #208
Diagnostics and compatibility reporting Stable diagnostic codes, source locations, support outcomes, migration guidance DIAGNOSTICS.md #26
Runtime Runtime layers and SDL3 adapter boundary RUNTIME.md #7
Memory model Storage, pointers, hardware access, safety policy MEMORY.md #8
CLI and configuration Commands, TOML project schema, precedence, diagnostics, output artifacts CLI-AND-CONFIG.md; ADR 0005 #9
Compatibility testing Test taxonomy, fixtures, conformance, deterministic behavior, release criteria TESTING.md; corpus conventions #10, #41, #42, #43
Version-scoped language constructs Exact-version manifest schema, evidence/expectation/execution separation, and construct-specific probes construct catalogue #570, #571, #572
Compatibility matrix Current dialect/version/profile/target support status COMPATIBILITY-MATRIX.md #10, #58
Frontend fuzzing Fuzz targets, corpus separation, resource budgets, and CI policy FUZZING.md strategy #43, implementation #118
Rust workspace Crate/module boundaries and dependency policy WORKSPACE.md #11
API registry Canonical TOML declarations, evidence/support states, schema validation API-REGISTRY.md; ADR 0006 #12, metadata validation #55 (complete), runtime handler resolution #115
Versioning and compatibility lifecycle Compiler releases, schema versions, runtime ABI, deprecation VERSIONING.md; ADR 0010 #58
Performance benchmarks Compiler, generated-program, runtime, and build measurements BENCHMARKING.md #60
Release and artifacts Tag triggers, validation gates, artifact metadata, checksums, provenance, reproducibility RELEASES.md #40

Detailed decisions remain open until the corresponding research and review are complete. The existence of a document does not mean that its issue is resolved.

Intended compiler pipeline

The proposed pipeline is:

  1. Load source files and preserve source identity.
  2. Tokenize source using the selected dialect and version.
  3. Parse tokens into an AST with source spans.
  4. Resolve names and declarations.
  5. Perform type checking and semantic analysis.
  6. Lower valid constructs into a typed, target-independent project IR.
  7. Perform target- or API-specific lowering where required.
  8. Generate LLVM IR and verify it.
  9. Generate native object code and link the selected runtime.
  10. Report diagnostics and build artifacts.

The frontend and project-owned IR must remain independent of SDL3 and of the initial output target. Semantic analysis belongs to the compiler, not LLVM. This pipeline is an architectural direction; interfaces and exact representations remain open.

Dependency boundaries

  • Language parsing must not depend on platform API implementation details.
  • The project-owned IR must not expose SDL3 or Linux-specific types.
  • The compiler must depend on stable project-owned runtime interfaces, not call SDL3 directly from generated code.
  • Frontend and IR work should be testable without LLVM or SDL3 installed.
  • Platform API profiles must not silently alter language-core semantics.
  • No language/API feature may be claimed as supported without a dialect/version-specific reference and an implementation/test status.

Decision records

Use numbered Architecture Decision Records in adr/. Each record states context, decision, status, alternatives, consequences, and evidence. An accepted ADR can be superseded by a later ADR; do not silently rewrite the historical rationale. The ADR template defines the required structure.

Glossary

  • Dialect: a defined GFA BASIC language variant associated with a platform and/or release.
  • Version: a specific release of a dialect.
  • Language core: language syntax and semantics not tied to a platform API.
  • API profile: a selectable set of platform-specific declarations and behavior.
  • Host: the machine and environment on which the compiler runs.
  • Target: the machine and ABI for which the compiler generates output.
  • Runtime: project-owned support code used by generated programs.
  • Backend: the component that translates project IR into target code.
  • Compatibility: a measured degree of agreement with a specified source dialect/version and API profile, not a blanket claim.
  • Conformance test: a test that compares compiler or runtime behavior with a documented rule or trusted reference implementation.

Open questions

  • Which 3.0/3.03 language rules are inherited by Amiga GFA BASIC 3.5, and which require explicit 3.5 confirmation or page-image verification?
  • Which Amiga and Atari ST manual editions are authoritative for each profile?
  • What is the exact documentation format requirement referred to as “OKF” in issue #14?
  • Which LLVM version and Rust binding are suitable for the chosen Rust toolchain?
  • Which compiler components justify separate Cargo crates?
  • Which runtime operations require software emulation rather than direct platform adapters?

Record evidence and decisions in the relevant issue and ADR before claiming closure.