Find the ASPL MVP specification

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 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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.