# Find the ASPL MVP specification

Label: wayfinder:map
Status: resolved

## Destination

An implementation-ready specification for the first public ASPL MVP, represented by this map and its resolved decision tickets. It must make the Arabic-first language, C-written compiler and register VM, self-contained Linux build, shared-library interoperability, distribution, bilingual website, documentation, and browser-local playground precise enough to plan implementation without hidden product or architecture decisions.

## Notes

- This is a planning map. Its tickets resolve decisions; they do not implement ASPL or its website.
- Read [`CONTEXT.md`](../../../CONTEXT.md) before working a ticket. It holds the canonical project vocabulary and settled scope boundaries.
- Use the `grilling` and `domain-modeling` skills for decision tickets. Use `research` or `prototype` when the ticket type calls for it.
- The temporary public name is ASPL, Arabic Systems Programming Language, and source files use `.aspl`.
- Arabic is the default product language. English keyword aliases and equivalent English documentation are required.
- The primary audience is Arabic-speaking programmers who know basic C or systems programming.
- The implementation source targets portable C11 plus required Linux APIs and has no required third-party compiler or runtime library. Contributors may use C and WebAssembly build tools, but an ASPL user build starts no compiler, assembler, or linker subprocess. The MVP approves no vendored compiler or runtime library.
- The first native target is x86-64 Linux with glibc. The distributed tool is one executable.
- The browser playground runs bytecode in a WebAssembly-hosted VM. It does not load Linux shared libraries or execute ELF files.
- The small-program build budget is below 100 ms on a documented reference machine.
- License the project under the user's chosen dual MIT or Apache-2.0 terms.

## Decisions so far

- [Investigate ELF packaging without an external linker](issues/01-investigate-elf-packaging.md): Copy and patch a release-built x86-64 PIE VM template with a final read-only payload segment; keep native dependencies fixed and load program libraries at runtime.
- [Investigate runtime calls across the x86-64 C ABI](issues/02-investigate-runtime-c-abi-calls.md): Pure C supports only a closed catalog of exact, precompiled call signatures; ASPL may load any compatible shared library but cannot claim arbitrary function calls.
- [Investigate browser-local WebAssembly constraints](issues/03-investigate-browser-webassembly-constraints.md): Use one statically linked, single-threaded Emscripten module in a dedicated worker, with buffer APIs, direct bytecode execution, fixed imports, and explicit resource limits.
- [Investigate Unicode and bidirectional source rules](issues/04-investigate-unicode-source-rules.md): Pin strict UTF-8 and Unicode 17.0, use case-sensitive NFC Arabic-or-Latin identifiers, constrain bidi controls, warn on confusables, and require token-aware bidirectional display.
- [Define the MVP semantic core](issues/05-define-mvp-semantic-core.md): Fix five storable types plus `unit` results, checked deterministic semantics, immutable-by-default lexical bindings, typed top-level functions, operation-local unsafe C calls, and a semantic acceptance matrix.
- [Design the bilingual source notation](issues/06-design-bilingual-source-notation.md): Use one normalized Arabic/English token set with freely mixed aliases, ASCII structural syntax, case-sensitive single-script identifiers, and RTL/LTR token-aware display whose punctuation follows atom direction.
- [Choose the runtime value model](issues/07-choose-runtime-value-model.md): Use private tagged VM values, immutable program-owned strings, opaque C object pointers, explicit bounded call frames, defensive slot states, and separate halt, trap, limit, load, and VM-failure outcomes.
- [Choose the register bytecode contract](issues/08-choose-register-bytecode-contract.md): Use fixed-width typed register instructions, explicit branches, indexed constants and imports, a canonical versioned envelope, exact-version loading, and full validation before execution.
- [Define dynamic C interoperability](issues/09-define-dynamic-c-interoperability.md): Use explicit unsafe declarations and calls, two exact bilingual adapter profiles, eager glibc loading, call-scoped C-string loans, and sharply separated checking, load, trap, and foreign failures.
- [Choose native executable packaging](issues/10-choose-native-executable-packaging.md): Copy a validated PIE VM template, extend its final read-only load segment with a thin versioned envelope and canonical bytecode, and keep outputs deterministic while program libraries load at runtime.
- [Choose the compiler pipeline and internal contracts](issues/11-choose-compiler-pipeline-contracts.md): Use owned opaque stages from source through validated VM state, deterministic unoptimized lowering, buffer-only host adapters, and explicit limits, cancellation, and test views.
- [Define diagnostics and the safety boundary](issues/12-define-diagnostics-and-safety.md): Use structured Arabic-default diagnostics, safe Unicode locations, staged recovery, closed failure and trap catalogs, mapped traces, explicit unsafe edits, and editor-side conversion to ASCII digits.
- [Define the CLI and build behavior](issues/13-define-cli-and-build-behavior.md): Use a strict one-file Arabic-default CLI, complete check/run/build phases, fixed native limits and statuses, normal glibc lookup, and deterministic atomic ELF publication.
- [Design the browser playground behavior](issues/14-design-browser-playground.md): Use an Arabic-default worker console with token-aware editing, debounced checks, explicit snapshot runs, immediate worker replacement, clear browser-only boundaries, and fixed browser limits.
- [Design the bilingual website and documentation](issues/15-design-bilingual-website-and-docs.md): Use a Guided line whose Arabic-default first viewport runs canonical source, then connects short systems-programmer lessons to a parity-checked bilingual reference, explicit C and host boundaries, verified installation, and a WCAG 2.2 AA release gate.
- [Define distribution and installation](issues/16-define-distribution-and-installation.md): Publish immutable SemVer tar.xz releases for baseline x86-64 glibc 2.34+, verified by SHA-256 and manually installed as one executable with explicit upgrade, rollback, uninstall, and dual-license instructions.
- [Set the performance budget and benchmark protocol](issues/17-set-performance-budget.md): Gate complete warm-cache `aspl build` at p95 below 100 ms on the fixed physical reference host, with paired CI regressions, deterministic size checks, and separate Firefox and Chromium budgets.
- [Choose the MVP builtin environment](issues/19-choose-builtin-environment.md): Reserve `اطبع` and `print` as the sole `(string) -> unit` builtin, lower it to host-neutral `WRITE_STRING`, and give native stdout and bounded browser output the same byte semantics.
- [Define MVP conformance and release criteria](issues/18-define-mvp-conformance-and-release.md): Separate specification closure, common and host-profile conformance, and the official release; require traceable zero-waiver evidence, clean-host and browser matrices, reproducible artifacts, and immutable public reports.

## Not yet specified

None.

## Out of scope

- Native machine-code generation and release builds that bypass the register VM.
- Static C archives, automatic C-header parsing, inline C functions, C macros, variadic calls, and complete C ABI coverage.
- Structs, arrays, modules, package management, user-managed heap allocation, generics, concurrency, and metaprogramming.
- Self-hosting, LLVM, assembly, non-Linux native targets, and claims of production readiness or practical C replacement.
- Arabic-Indic and Extended Arabic-Indic digits as stored source syntax, Arabic punctuation alternatives, and newly invented Arabic operators.
- Bitwise operations, shifts, `break`, `continue`, globals, executable top-level statements, runtime string construction, general unsafe blocks, and raw pointer manipulation.
- A beginner curriculum, blog, community forum, package registry, and full compiler-internals manual.