README
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:
- Load source files and preserve source identity.
- Tokenize source using the selected dialect and version.
- Parse tokens into an AST with source spans.
- Resolve names and declarations.
- Perform type checking and semantic analysis.
- Lower valid constructs into a typed, target-independent project IR.
- Perform target- or API-specific lowering where required.
- Generate LLVM IR and verify it.
- Generate native object code and link the selected runtime.
- 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.